Workspace Isolation

Overview

Workspace isolation is the most critical safety mechanism in Symphony. Every coding agent runs in a dedicated per-issue directory, preventing unintended access to the source repository or other workspaces.

Security boundary: The coding agent must never run in the source repository or escape the workspace root. All workspace operations enforce strict path validation.

Workspace Path Structure

Directory Layout

<workspace.root>/
├── ABC-123/          ← Issue workspace
│   ├── .git/         ← Per-issue repository clone (if using Git hooks)
│   ├── src/
│   └── ...
├── MT-649/           ← Another issue workspace
└── PROJ_456/         ← Sanitized identifier (original: "PROJ/456")

Default workspace root: <system-temp>/symphony_workspaces

Path Construction

def workspace_path_for_issue(safe_id) do
  Path.join(Config.workspace_root(), safe_id)
end

Example:

issue.identifier = "ABC-123"
workspace_root   = "/tmp/symphony_workspaces"
workspace_path   = "/tmp/symphony_workspaces/ABC-123"

Reference: elixir/lib/symphony_elixir/workspace.ex:111-113

Identifier Sanitization

Safety Rules

Only [A-Za-z0-9._-] are allowed in workspace directory names. All other characters are replaced with _.

defp safe_identifier(identifier) do
  String.replace(identifier || "issue", ~r/[^a-zA-Z0-9._-]/, "_")
end

Reference: elixir/lib/symphony_elixir/workspace.ex:115-117

Sanitization Examples

"ABC-123"      → "ABC-123"     (no change)
"MT.649"       → "MT.649"      (no change)
"PROJ_456"     → "PROJ_456"    (no change)

Path traversal attempts like ../ become ___/, which is then joined with workspace root to produce a safe path inside the workspace.

Path Validation

Three-Layer Safety Check

Before using any workspace path, Symphony validates:

Layer 1: Prefix Check

defp validate_workspace_path(workspace) do
  expanded_workspace = Path.expand(workspace)
  root = Path.expand(Config.workspace_root())
  root_prefix = root <> "/"
  
  cond do
    expanded_workspace == root ->
      {:error, {:workspace_equals_root, expanded_workspace, root}}
    
    String.starts_with?(expanded_workspace <> "/", root_prefix) ->
      ensure_no_symlink_components(expanded_workspace, root)
    
    true ->
      {:error, {:workspace_outside_root, expanded_workspace, root}}
  end
end

Normalize both paths to absolute
Reject if workspace equals root
Reject if workspace not under root prefix

Reference: elixir/lib/symphony_elixir/workspace.ex:213-228

Layer 2: Symlink Escape Prevention

defp ensure_no_symlink_components(workspace, root) do
  workspace
  |> Path.relative_to(root)
  |> Path.split()
  |> Enum.reduce_while(root, fn segment, current_path ->
    next_path = Path.join(current_path, segment)
    
    case File.lstat(next_path) do
      {:ok, %File.Stat{type: :symlink}} ->
        {:halt, {:error, {:workspace_symlink_escape, next_path, root}}}
      
      {:ok, _stat} ->
        {:cont, next_path}
      
      {:error, :enoent} ->
        {:halt, :ok}  # Path doesn't exist yet, safe to create
      
      {:error, reason} ->
        {:halt, {:error, {:workspace_path_unreadable, next_path, reason}}}
    end
  end)
end

Walk each path component from root to workspace
Use File.lstat/1 (does not follow symlinks)
Reject if any component is a symlink

Reference: elixir/lib/symphony_elixir/workspace.ex:230-256

Layer 3: Codex cwd Validation

defp validate_workspace_cwd(workspace) do
  workspace_path = Path.expand(workspace)
  workspace_root = Path.expand(Config.workspace_root())
  root_prefix = workspace_root <> "/"
  
  cond do
    workspace_path == workspace_root ->
      {:error, {:invalid_workspace_cwd, :workspace_root, workspace_path}}
    
    not String.starts_with?(workspace_path <> "/", root_prefix) ->
      {:error, {:invalid_workspace_cwd, :outside_workspace_root, workspace_path, workspace_root}}
    
    true ->
      :ok
  end
end

Validate before launching Codex subprocess
Ensure cwd is inside workspace root
Prevent running agent in source repo or system directories

Reference: elixir/lib/symphony_elixir/codex/app_server.ex:144-160

Attack Resistance

Path Traversal

../../../etc sanitizes to ___________etc, still under workspace root

Symlink Escape

/tmp/workspaces/link -> /etc detected by lstat check, rejected

Absolute Paths

/etc/passwd as identifier becomes _etc_passwd, safe relative path

Null Bytes

Regex replacement handles null bytes like any other unsafe character

Workspace Lifecycle

Creation Flow

defp ensure_workspace(workspace) do
  cond do
    File.dir?(workspace) ->
      clean_tmp_artifacts(workspace)  # Remove .elixir_ls/, tmp/
      {:ok, false}  # Reused
    
    File.exists?(workspace) ->
      File.rm_rf!(workspace)  # File exists, not a directory
      create_workspace(workspace)
    
    true ->
      create_workspace(workspace)  # Doesn't exist
  end
end

defp create_workspace(workspace) do
  File.rm_rf!(workspace)
  File.mkdir_p!(workspace)
  {:ok, true}  # Newly created
end

Reference: elixir/lib/symphony_elixir/workspace.ex:32-51

Workspace Reuse

Workspaces are preserved across runs for the same issue until the issue reaches a terminal state.

Benefits:

Incremental progress: Agent can build on previous work
Faster iteration: No need to re-clone repository or re-install dependencies
Debugging: Operators can inspect workspace state between runs

Trade-offs:

Disk usage: Workspaces accumulate over time
State pollution: Previous run artifacts may affect future runs

Use before_run hook to reset workspace state if needed.

Lifecycle Hooks

Hooks are shell scripts executed in the workspace directory with configurable timeout.

Hook Configuration

hooks:
  after_create: |
    git clone https://github.com/org/repo.git .
    git checkout -b $ISSUE_BRANCH
  
  before_run: |
    git fetch origin
    git reset --hard origin/main
    npm install
  
  after_run: |
    git status > /tmp/workspace_status.txt
  
  before_remove: |
    git push origin :$ISSUE_BRANCH  # Delete remote branch
  
  timeout_ms: 60000

Hook Execution

defp run_hook(command, workspace, issue_context, hook_name) do
  timeout_ms = Config.workspace_hooks()[:timeout_ms]  # Default: 60000
  
  Logger.info("Running hook=#{hook_name} workspace=#{workspace}")
  
  task = Task.async(fn ->
    System.cmd("sh", ["-lc", command], cd: workspace, stderr_to_stdout: true)
  end)
  
  case Task.yield(task, timeout_ms) do
    {:ok, {_output, 0}} ->
      :ok
    
    {:ok, {output, status}} ->
      Logger.warning("Hook failed hook=#{hook_name} status=#{status} output=#{inspect(output)}")
      {:error, {:workspace_hook_failed, hook_name, status, output}}
    
    nil ->
      Task.shutdown(task, :brutal_kill)
      Logger.warning("Hook timed out hook=#{hook_name} timeout_ms=#{timeout_ms}")
      {:error, {:workspace_hook_timeout, hook_name, timeout_ms}}
  end
end

Reference: elixir/lib/symphony_elixir/workspace.ex:166-187

Hook Failure Semantics

after_create

Fatal: Workspace creation aborted, agent run fails

before_run

Fatal: Current run attempt aborted, worker exits with error

after_run

Logged and ignored: Run result not affected

before_remove

Logged and ignored: Workspace deletion proceeds anyway

Hook Environment

Shell Context

Shell: sh -lc <script> (login shell, loads user profile)
Working directory: Workspace path (e.g. /tmp/symphony_workspaces/ABC-123)
Standard streams: stderr_to_stdout: true (combined output)
Timeout: hooks.timeout_ms (default: 60 seconds)

Available Data

Hooks don’t receive environment variables automatically. Access issue data via:

Workspace path: pwd → /tmp/symphony_workspaces/ABC-123
Issue identifier: Parse from workspace directory name
WORKFLOW.md: Can embed issue context in hook script

Example:

ISSUE_ID=$(basename $(pwd))
echo "Running for issue: $ISSUE_ID"

Common Hook Patterns

Git Repository Clone

git clone https://github.com/org/repo.git .
git config user.name "Symphony Bot"
git config user.email "[email protected]"

# Create issue branch
ISSUE_ID=$(basename $(pwd))
git checkout -b "symphony/$ISSUE_ID"

Dependency Management

# after_create
npm install --prefer-offline

# before_run
npm ci  # Clean install from package-lock.json

Resource Provisioning

# before_run
docker compose up -d postgres redis
docker compose run --rm app mix ecto.migrate

# after_run
docker compose down

Cleanup Policies

Automatic Cleanup Triggers

Terminal State Transition

Issue moves to Closed, Done, Cancelled, etc. during reconciliation

Startup Terminal Cleanup

On service start, clean workspaces for issues already in terminal states

Terminal State Cleanup

During reconciliation, if an issue moves to a terminal state:

terminal_issue_state?(issue.state, terminal_states) ->
  Logger.info("Issue #{issue.identifier} moved to terminal state=#{issue.state}; stopping agent")
  terminate_running_issue(state, issue.id, true)  # cleanup_workspace=true

Reference: elixir/lib/symphony_elixir/orchestrator.ex:303-306 Cleanup sequence:

Terminate worker process (if running)
Run before_remove hook (if configured)
Delete workspace directory
Remove from running/claimed/retry_attempts maps

Startup Cleanup

Before the first poll tick:

defp run_terminal_workspace_cleanup do
  case Tracker.fetch_issues_by_states(Config.linear_terminal_states()) do
    {:ok, issues} ->
      Enum.each(issues, fn
        %Issue{identifier: identifier} when is_binary(identifier) ->
          Workspace.remove_issue_workspaces(identifier)
      end)
    
    {:error, reason} ->
      Logger.warning("Skipping startup cleanup; failed to fetch terminal issues")
  end
end

Reference: elixir/lib/symphony_elixir/orchestrator.ex:776-791

Startup cleanup prevents workspace accumulation across service restarts. Workspaces for issues already marked “Done” are removed before polling begins.

Manual Cleanup

Operators can manually clean workspaces:

# Remove all workspaces
rm -rf /tmp/symphony_workspaces/*

# Remove specific workspace
rm -rf /tmp/symphony_workspaces/ABC-123

# Trigger cleanup via API (if HTTP server enabled)
curl -X POST http://localhost:4000/api/v1/workspaces/ABC-123/clean

Safety Invariants

Critical Rules

These invariants must NEVER be violated. Violations can lead to data loss or security breaches.

Invariant 1: Run agent only in workspace path

# BEFORE launching Codex subprocess:
with :ok <- validate_workspace_cwd(workspace) do
  Port.open({:spawn_executable, "bash"}, [
    cd: String.to_charlist(workspace),  # ← Must be validated workspace
    # ...
  ])
end

Never launch Codex in:

Source repository directory
System directories (/, /etc, /usr, etc.)
User home directory
Parent of workspace root

Invariant 2: Workspace path inside workspace root

expanded_workspace = Path.expand(workspace)
root = Path.expand(Config.workspace_root())

# Require workspace_path starts with workspace_root
String.starts_with?(expanded_workspace <> "/", root <> "/")

Both paths must be normalized to absolute before comparison.

Invariant 3: Workspace key is sanitized

# Only [A-Za-z0-9._-] allowed in directory names
String.replace(identifier, ~r/[^a-zA-Z0-9._-]/, "_")

All other characters must be replaced before use in filesystem paths.

Enforcement Points

These invariants are enforced at:

Workspace creation: validate_workspace_path/1 before mkdir
Codex launch: validate_workspace_cwd/1 before Port.open/2
Workspace removal: validate_workspace_path/1 before rm_rf/1

Observability

Workspace State Inspection

ls -la /tmp/symphony_workspaces/

# Output:
drwxr-xr-x  5 user  wheel  160 Mar  4 10:30 ABC-123
drwxr-xr-x  5 user  wheel  160 Mar  4 10:45 MT-649
drwxr-xr-x  5 user  wheel  160 Mar  4 11:00 PROJ-456

Workspace Logs

Key log messages:

Running workspace hook hook=after_create issue_id=abc123 workspace=/tmp/symphony_workspaces/ABC-123
Workspace hook failed hook=before_run status=1 output="npm install failed"
Workspace hook timed out hook=after_create timeout_ms=60000
Issue moved to terminal state=Done; stopping active agent

Troubleshooting

Common Issues

Hook timeout

Symptom: Workspace hook timed out hook=after_create timeout_ms=60000Causes:

Slow network (git clone, npm install)
Large repository
Expensive build step

Solutions:

Increase hooks.timeout_ms in WORKFLOW.md
Optimize hook script (use --depth=1 for git clone)
Cache dependencies outside workspace

Workspace outside root

Symptom: {:error, {:workspace_outside_root, "/tmp/other/path", "/tmp/symphony_workspaces"}}Causes:

Incorrect workspace.root configuration
Symlink in path
Path traversal attempt

Solutions:

Check workspace.root in WORKFLOW.md
Use absolute paths, not relative
Ensure no symlinks in workspace root path

Workspace creation failed

Symptom: Workspace creation failed issue_id=abc123 error=...Causes:

Permission denied
Disk full
Hook failure

Solutions:

Check filesystem permissions on workspace root
Verify disk space: df -h /tmp
Review hook logs for specific error

Debug Mode

Enable verbose workspace logging:

# In config/dev.exs
config :logger, level: :debug

Logs will include:

Path validation steps
Symlink checks
Hook stdout/stderr
Workspace creation/deletion

Security Considerations

Threat Model

Malicious Issue Identifiers

Path traversal attempts in issue identifier are sanitized before use

Symlink Escapes

Each path component checked with lstat to detect symlink escapes

Arbitrary Code Execution

Hooks run in workspace context, not system-wide. Use codex.approval_policy to control agent permissions

Resource Exhaustion

No built-in disk quota enforcement. Use OS-level quotas or monitoring

Best Practices

Defense in depth: Multiple safety layers protect against workspace isolation failures.

Use absolute paths: Configure workspace.root with absolute path
Monitor disk usage: Set up alerts for workspace root disk consumption
Limit hook complexity: Keep hooks simple, move complex logic to agent tools
Audit workspace access: Review which processes can write to workspace root
Use read-only mounts: If possible, mount source repo read-only in workspace

Next Steps

Configuration Reference

Complete WORKFLOW.md schema and hook examples

Component Reference

Implementation details for Workspace Manager

Workflow Lifecycle

How workspaces fit into the overall execution flow

Troubleshooting

Common workspace issues and solutions

Get Started

Setup & Deployment

Architecture

Operations

Advanced

​Overview

​Workspace Path Structure

​Directory Layout

​Path Construction

​Identifier Sanitization

​Safety Rules

​Sanitization Examples

​Path Validation

​Three-Layer Safety Check

​Attack Resistance

Path Traversal

Symlink Escape

Absolute Paths

Null Bytes

​Workspace Lifecycle

​Creation Flow

​Workspace Reuse

​Lifecycle Hooks

​Hook Configuration

​Hook Execution

​Hook Failure Semantics

after_create

before_run

after_run

before_remove

​Hook Environment

​Common Hook Patterns

​Git Repository Clone

​Dependency Management

​Resource Provisioning

​Cleanup Policies

​Automatic Cleanup Triggers

Terminal State Transition

Startup Terminal Cleanup

​Terminal State Cleanup

​Startup Cleanup

​Manual Cleanup

​Safety Invariants

​Critical Rules

​Enforcement Points

​Observability

​Workspace State Inspection

​Workspace Logs

​Troubleshooting

​Common Issues

​Debug Mode

​Security Considerations

​Threat Model

Malicious Issue Identifiers

Symlink Escapes

Arbitrary Code Execution

Resource Exhaustion

​Best Practices

​Next Steps

Configuration Reference

Component Reference

Workflow Lifecycle

Troubleshooting

Build docs developers (and LLMs) love

Overview

Workspace Path Structure

Directory Layout

Path Construction

Identifier Sanitization

Safety Rules

Sanitization Examples

Path Validation

Three-Layer Safety Check

Attack Resistance

Workspace Lifecycle

Creation Flow

Workspace Reuse

Lifecycle Hooks

Hook Configuration

Hook Execution

Hook Failure Semantics

Hook Environment

Common Hook Patterns

Git Repository Clone

Dependency Management

Resource Provisioning

Cleanup Policies

Automatic Cleanup Triggers

Terminal State Cleanup

Startup Cleanup

Manual Cleanup

Safety Invariants

Critical Rules

Enforcement Points

Observability

Workspace State Inspection

Workspace Logs

Troubleshooting

Common Issues

Debug Mode

Security Considerations

Threat Model

Best Practices

Next Steps