takt/docs/provider-sandbox.md

Provider Sandbox Configuration

TAKT supports configuring sandbox settings for AI agent providers. This document covers how sandbox isolation works across providers, how to configure it, and the security trade-offs.

Overview

Provider	Sandbox Mechanism	Build Tool Issues	TAKT Configuration
Claude Code	macOS Seatbelt / Linux bubblewrap	Gradle/JVM blocked in edit mode	provider_options.claude.sandbox
Codex CLI	macOS Seatbelt / Linux Landlock+seccomp	npm/maven/pytest failures (widespread)	provider_options.codex.network_access
OpenCode CLI	None (no native sandbox)	No constraints (no security either)	N/A

Claude Code Sandbox

The Problem

When a movement uses permission_mode: edit (mapped to Claude SDK's acceptEdits), Bash commands run inside a macOS Seatbelt sandbox. This sandbox blocks:

• Writes outside the working directory (e.g., ~/.gradle)
• Certain system calls required by JVM initialization
• Network access (by default)

As a result, build tools like Gradle, Maven, or any JVM-based tool fail with Operation not permitted.

Solution: provider_options.claude.sandbox

TAKT exposes Claude SDK's SandboxSettings through provider_options.claude.sandbox at four configuration levels.

Option A: allow_unsandboxed_commands (Recommended)

Allow all Bash commands to run outside the sandbox while keeping file edit permissions controlled:

provider_options:
  claude:
    sandbox:
      allow_unsandboxed_commands: true

Option B: excluded_commands

Exclude only specific commands from the sandbox:

provider_options:
  claude:
    sandbox:
      excluded_commands:
        - ./gradlew
        - npm
        - npx

Configuration Levels

Settings are merged with the following priority (highest wins):

Movement > Piece > Project Local > Global

Global (~/.takt/config.yaml)

Applies to all projects and all pieces:

# ~/.takt/config.yaml
provider_options:
  claude:
    sandbox:
      allow_unsandboxed_commands: true

Project Local (.takt/config.yaml)

Applies to this project only:

# .takt/config.yaml
provider_options:
  claude:
    sandbox:
      excluded_commands:
        - ./gradlew

Piece (piece_config section)

Applies to all movements in this piece:

# pieces/my-piece.yaml
piece_config:
  provider_options:
    claude:
      sandbox:
        allow_unsandboxed_commands: true

Movement (per step)

Applies to a specific movement only:

movements:
  - name: implement
    permission_mode: edit
    provider_options:
      claude:
        sandbox:
          allow_unsandboxed_commands: true
  - name: review
    permission_mode: readonly
    # No sandbox config needed — readonly doesn't sandbox Bash

Security Risk Comparison

Configuration	File Edits	Network	Bash Commands	CWD-external Writes	Risk Level
permission_mode: edit (default)	Permitted	Blocked	Sandboxed	Blocked	Low
excluded_commands: [./gradlew]	Permitted	Blocked	Only ./gradlew unsandboxed	Only via ./gradlew	Low
allow_unsandboxed_commands: true	Permitted	Allowed	Unsandboxed	Allowed via Bash	Medium
permission_mode: full	All permitted	Allowed	Unsandboxed	All permitted	High

Key difference between allow_unsandboxed_commands and permission_mode: full:

• allow_unsandboxed_commands: File edits still require Claude Code's permission check (acceptEdits mode). Only Bash is unsandboxed.
• permission_mode: full: All permission checks are bypassed (bypassPermissions mode). No guardrails at all.

Practical Risk Assessment

The "Medium" risk of allow_unsandboxed_commands is manageable in practice because:

• TAKT runs locally on the developer's machine (not a public-facing service)
• Input comes from task instructions written by the developer
• Agent behavior is reviewed by the supervisor movement
• File edit operations still go through Claude Code's permission system

Codex CLI Sandbox

Codex CLI uses macOS Seatbelt (same as Claude Code) but has more severe compatibility issues with build tools. Community reports show npm, Maven, pytest, and other tools frequently failing with Operation not permitted — even when the same commands work in Claude Code.

Codex sandbox is configured via ~/.codex/config.toml (not through TAKT):

# ~/.codex/config.toml
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true
writable_roots = ["/Users/YOU/.gradle"]

TAKT provides provider_options.codex.network_access to control network access via the Codex SDK:

provider_options:
  codex:
    network_access: true

For other sandbox settings (writable_roots, sandbox_mode), configure directly in ~/.codex/config.toml.

OpenCode CLI Sandbox

OpenCode CLI does not have a native sandbox mechanism. All commands run without filesystem or network restrictions. For isolation, the community recommends Docker containers (e.g., opencode-sandbox).

No TAKT-side sandbox configuration is needed or available for OpenCode.