Workspace

The workspace is the isolated directory where Experts execute. All file operations are confined to this directory.

Default workspace

By default, the current directory becomes the workspace:

/path/to/my-project

cd /path/to/my-project
npx perstack run my-expert "query"

Security

Workspace isolation prevents Experts from accessing unintended files.

Allowed:

• Read/write files within the workspace
• Create/delete directories within the workspace
• Relative and absolute paths (resolved within workspace)

Blocked:

• Access outside the workspace
• Symlink escape attempts
• Path traversal (../../../etc/passwd)
• Direct access to perstack/ directory

These restrictions ensure Experts can only affect their designated environment.

Data exchange between Experts

Delegated Experts don’t share LLM context. They exchange data through workspace files:

[experts."coordinator"]
instruction = """
1. Delegate to researcher to gather information
2. Read the report from ./reports/research.md
3. Summarize findings
"""
delegates = ["researcher"]

[experts."researcher"]
instruction = "Research the topic and save to ./reports/research.md"

Benefits:

• Token efficiency — no context duplication
• Independence — each Expert runs with clean context
• Explicit data flow — files make data exchange visible

Runtime data

The runtime stores execution history in perstack/jobs/ within the workspace. This directory is managed automatically — see Runtime for details.