feat: On-demand Sub-Agent mode — invoke sandbox headlessly from Claude Code, Open WebUI, or Codex

[christestet]

Summary

The sandbox currently runs OpenCode as an interactive TUI for a single human user. This issue proposes extending it to support on-demand invocation as a sub-agent from host-side agents like Claude Code, Open WebUI, or Codex CLI — without changing the existing security model, Dockerfile, or interactive mode.

A host agent delegates a task via tool call → Docker starts the sandbox ephemerally → OpenCode executes the task headlessly against the local vLLM server → structured JSON is returned → container stops automatically.

No data leaves your network. No cloud API keys required. No changes to the hardened security setup.

---

Why

Problem	Today	After
A host agent (Claude Code etc.) can delegate tasks to the sandbox	❌	✅
Headless / non-interactive execution	❌	✅
Structured JSON output for machine-readable results	❌	✅
Ephemeral start only when needed	❌	✅

Benefits:

• Data sovereignty — even delegated sub-agent tasks stay fully local
• Security isolation — Docker enforces kernel-level separation between host agent and sub-agent; a misbehaving prompt cannot escape to the host
• Cost efficiency — all inference runs against local vLLM, no token costs even at scale
• Reuse — existing commands (/refactor-audit, /git-commit etc.) become available to all calling agents with zero extra work

---

What needs to change

Only 3 files need to be touched. The Dockerfile, compose.yml, and the entire security model remain completely unchanged.

1. entrypoint.sh — add a TASK branch at the end

Replace the final exec gosu ... line with:

export HOME="/home/opencode/workspace"
export OPENCODE_WORKSPACE="/home/opencode/workspace"

if [[ -n "${TASK}" ]]; then
    echo "> [Entrypoint] Sub-Agent headless mode" >&2
    exec gosu "$APP_USER:$APP_GROUP" \
        opencode run "${TASK}" \
        --format json \
        --quiet
else
    exec gosu "$APP_USER:$APP_GROUP" opencode
fi

Everything before this (PUID/PGID handling, chown, gosu setup) stays identical.

2. New file: compose.headless.yml

services:
  opencode:
    build: .
    environment:
      TASK: ${TASK}
      PUID: ${PUID:-1000}
      PGID: ${PGID:-1000}
    volumes:
      - ./workspace:/home/opencode/workspace
      - ./data:/home/opencode/.local/share/opencode
      - ./config/opencode.json:/home/opencode/.config/opencode/opencode.json:ro
      - ./config/auth.json:/home/opencode/.config/opencode/auth.json:ro
      - ./config/AGENTS.md:/home/opencode/.config/opencode/AGENTS.md:ro
      - ./.opencode/commands:/home/opencode/.config/opencode/commands:ro
      - ./.opencode/skills:/home/opencode/.config/opencode/skills:ro
    cap_drop: [ALL]
    cap_add: [CHOWN, SETUID, SETGID, DAC_OVERRIDE]
    security_opt: [no-new-privileges:true]
    stdin_open: false
    tty: false
    restart: "no"

3. New file: tools/mcp_sandbox_server.py (for Claude Code)

import asyncio, os, subprocess
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent

SANDBOX_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
app = Server("coding-agent-sandbox")

@app.list_tools()
async def list_tools():
    return [Tool(
        name="run_in_sandbox",
        description=(
            "Runs a coding task in the hardened Docker sandbox "
            "against local vLLM. Returns JSON with agent output."
        ),
        inputSchema={
            "type": "object",
            "properties": {
                "task": {"type": "string"},
                "timeout": {"type": "integer", "default": 300}
            },
            "required": ["task"]
        }
    )]

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    result = subprocess.run(
        ["docker", "compose", "-f", "compose.headless.yml", "run", "--rm", "opencode"],
        env={**os.environ, "TASK": arguments["task"]},
        capture_output=True, text=True,
        timeout=arguments.get("timeout", 300),
        cwd=SANDBOX_DIR
    )
    output = result.stdout.strip()
    if result.returncode != 0:
        output = f'{{"error": "exit {result.returncode}", "stderr": {repr(result.stderr)}}}'
    return [TextContent(type="text", text=output)]

if __name__ == "__main__":
    asyncio.run(stdio_server(app))

Register with Claude Code:

claude mcp add coding-agent-sandbox -- python3 ./tools/mcp_sandbox_server.py

---

Smoke test

TASK="List all files in the workspace and summarize their purpose." \
  docker compose -f compose.headless.yml run --rm opencode

---

Notes

• opencode run --format json --quiet is the official non-interactive mode — no hacking required
• For high-frequency sub-agent calls, opencode serve --port 4096 + --attach eliminates per-task container start overhead
• The Open WebUI variant is ~20 lines of Python using subprocess.run — no MCP dependency needed

[christestet]

docker-coding-agent-sandbox — Sub-Agent Flow Diagrams

Repository: jammsen/docker-coding-agent-sandbox
Inference: Local vLLM · Qwen3.6 35B A3B
Network: Air-gapped · No cloud egress
Trigger: ENV $TASK → headless opencode run

---

Table of Contents

• Diagram 01 — High-Level Call Flow
• Diagram 02 — Detailed Data Flow
• Diagram 03 — Entrypoint Decision Flow
• Diagram 04 — Full Sequence (Claude Code)
• Diagram 05 — Artifact Boundary Map
• Artifact Reference Tables

---

Diagram 01 — High-Level Call Flow

End-to-end journey of a sub-agent invocation: from tool call on the host, down through Docker into the sandbox, and back.

flowchart LR
    subgraph HOST["🖥  HOST — Calling Agent Layer"]
        direction TB
        CC["Claude Code\n(host process)"]
        OW["Open WebUI\n(host process)"]
        CX["Codex CLI\n(host process)"]
        BRIDGE["MCP Server /\nOpen WebUI Tool\nmcp_sandbox_server.py"]
    end

    subgraph DOCKER["🐳  DOCKER LAYER"]
        direction TB
        DE["Docker Engine\ndocker compose run --rm"]
        CTR["Sandbox Container\nephemeral · --rm"]
    end

    subgraph SANDBOX["🔒  SANDBOX — Hardened Container"]
        direction TB
        EP["entrypoint.sh\nPUID/PGID setup · gosu drop"]
        OC["OpenCode\nopencode run TASK\n--format json -q"]
        FS["Workspace Volume\n./workspace  r/w\n./config      r/o"]
    end

    subgraph INFERENCE["⚙  INFERENCE — Local Network"]
        VL["vLLM Server\n10.0.0.x:8000\nQwen3.6 35B A3B"]
    end

    CC -->|"tool_call: run_in_sandbox(task)"| BRIDGE
    OW -->|"tool_call: run_in_sandbox(task)"| BRIDGE
    CX -->|"shell tool: run_in_sandbox(task)"| BRIDGE

    BRIDGE -->|"docker compose run --rm\n-e TASK=... opencode"| DE
    DE -->|"starts container"| CTR
    CTR -->|"executes"| EP
    EP -->|"gosu drop → opencode run"| OC
    OC <-->|"reads/writes project files"| FS
    OC <-->|"HTTP /v1/chat\nOpenAI-compat API"| VL

    OC -->|"JSON stdout\n{status, output, files_modified}"| EP
    EP -->|"stdout passthrough"| CTR
    CTR -->|"container exits 0\n--rm: removed"| DE
    DE -->|"stdout captured → result.stdout"| BRIDGE
    BRIDGE -->|"tool_result: JSON string"| CC
    BRIDGE -->|"tool_result: JSON string"| OW
    BRIDGE -->|"tool_result: JSON string"| CX

Loading

The calling agent never touches Docker directly. The MCP Server / Open WebUI Tool wraps docker compose run --rm -e TASK=.... The container is ephemeral — it exists only for the duration of the task, then is automatically removed.

---

Diagram 02 — Detailed Data Flow: Inputs & Outputs

Every artifact that crosses a boundary — what enters the container, what moves between OpenCode and vLLM, and what the calling agent receives back.

flowchart TD
    subgraph IN["📥  INPUTS — what enters the sandbox"]
        direction LR
        T["ENV: $TASK\n(task prompt string)"]
        E["ENV: PUID / PGID\n(user identity)"]
        CFG["Read-only mounts\nopencode.json · auth.json\nAGENTS.md · commands/ · skills/"]
        WS_IN["Workspace volume  r/w\n./workspace/\n(existing project files,\nsource code, configs)"]
    end

    subgraph PROC["⚙  PROCESSING — inside the container"]
        direction TB
        EP2["entrypoint.sh\n① fix UID/GID ownership\n② export HOME=workspace\n③ exec gosu → opencode"]

        subgraph OC_LOOP["OpenCode Agentic Loop"]
            direction LR
            PLAN["Plan & decompose\ntask into steps"]
            TOOLS["Execute tools\nread_file · write_file\nbash · search · grep"]
            INFER["LLM Inference\nvLLM HTTP call\nOpenAI-compat"]
            PLAN --> TOOLS --> INFER --> PLAN
        end

        EP2 --> OC_LOOP
    end

    subgraph OUT["📤  OUTPUTS — what leaves the sandbox"]
        direction LR
        JSON_OUT["stdout: JSON result\n{\n  status: done|error\n  output: string\n  files_modified: []\n  tokens_used: N\n}"]
        WS_OUT["Workspace volume\n(mutated files)\nnew / edited / deleted\nproject files"]
        EXIT["Container exit code\n0 = success  ·  1 = error\n(--rm: container removed)"]
    end

    T --> EP2
    E --> EP2
    CFG -->|":ro mount"| EP2
    WS_IN -->|":rw mount"| TOOLS

    INFER <-->|"POST /v1/chat/completions\nmodel: qwen3.6-35b\n[tool_calls in response]"| VL2["vLLM Server\n10.0.0.x:8000"]

    OC_LOOP -->|"opencode exits after task"| JSON_OUT
    TOOLS -->|"file writes"| WS_OUT
    OC_LOOP -->|"process exit"| EXIT

Loading

The workspace volume is the only read-write surface. Config, auth, commands, and skills are all mounted :ro and cannot be modified by the agent. The JSON result on stdout is the primary return channel for the calling agent.

---

Diagram 03 — Entrypoint Decision Flow

The extended entrypoint.sh logic. One new branch at the very end selects headless vs. interactive mode. Everything before it is unchanged.

flowchart TD
    A([Container starts]) --> B{EUID = 0?}
    B -->|No| ERR1(["❌ Error: root required for setup phase"])

    B -->|Yes| C{PUID or PGID = 0?}
    C -->|Yes| ERR2(["❌ Error: root app-user not supported"])

    C -->|No| D{Group 'opencode'\nexists with correct GID?}
    D -->|No / wrong GID| E["groupadd or groupmod\nset GID = PGID"]
    D -->|Correct| F
    E --> F{User 'opencode'\nexists with correct UID?}

    F -->|No / wrong UID| G["useradd or usermod\nset UID = PUID"]
    F -->|Correct| H
    G --> H{NEEDS_CHOWN?}

    H -->|Yes| I["find /home/opencode -xdev\nchown opencode:opencode\n(-xdev: skip :ro mounts)"]
    H -->|No| J
    I --> J["export HOME = /home/opencode/workspace\nexport OPENCODE_WORKSPACE"]

    J --> K{"ENV: $TASK\nis set?"}

    K -->|"✅ YES — Sub-Agent mode\n(new branch)"| L["exec gosu opencode:opencode\nopencode run "$TASK"\n--format json --quiet"]
    K -->|"NO — Interactive mode\n(unchanged)"| M["exec gosu opencode:opencode\nopencode\n(TUI)"]

    L --> N(["✅ JSON on stdout\nContainer exits 0\n--rm: container removed"])
    M --> O(["✅ Interactive TUI\nUser session"])

Loading

The only code change to entrypoint.sh is the $TASK check + headless exec at the bottom. Every node above that branch is existing, unchanged logic. The interactive TUI path is fully preserved.

---

Diagram 04 — Full Sequence: Claude Code Invocation

Time-ordered message sequence for a complete sub-agent task cycle, including the agentic tool-use loop inside OpenCode.

sequenceDiagram
    autonumber
    participant CC as Claude Code<br/>(host agent)
    participant MCP as MCP Server<br/>(host process)
    participant DE as Docker Engine
    participant EP as entrypoint.sh<br/>(container · root)
    participant OC as OpenCode<br/>(container · non-root)
    participant VL as vLLM Server<br/>(local network)
    participant FS as Workspace<br/>./workspace

    CC->>MCP: tool_call: run_in_sandbox("Refactor auth/login.py")
    Note over MCP: subprocess.run(docker compose run --rm,<br/>env={TASK=...}, capture_output=True)

    MCP->>DE: docker compose -f compose.headless.yml run --rm opencode
    DE->>EP: container start · ENV TASK, PUID, PGID injected

    EP->>EP: fix UID/GID · chown /home/opencode
    EP->>EP: export HOME=workspace
    EP->>OC: exec gosu opencode:opencode opencode run "$TASK" --format json -q
    Note over EP,OC: Privilege drop — non-root from here on

    OC->>VL: POST /v1/chat/completions<br/>system + task prompt · tool definitions
    VL-->>OC: response: plan + tool_call read_file("auth/login.py")

    OC->>FS: read_file("auth/login.py")
    FS-->>OC: file contents

    OC->>VL: POST /v1/chat/completions (file contents as tool result)
    VL-->>OC: response: tool_call write_file with refactored code

    OC->>FS: write_file("auth/login.py", refactored_code)
    FS-->>OC: write confirmed

    OC->>VL: POST /v1/chat/completions (write result)
    VL-->>OC: response: tool_call bash("python -m pytest tests/")

    OC->>FS: bash("python -m pytest tests/")
    FS-->>OC: test output (all passed)

    OC->>VL: POST /v1/chat/completions (test results)
    VL-->>OC: task complete · final summary text

    OC-->>EP: stdout: {"status":"done","output":"...","files_modified":["auth/login.py"],"tokens_used":5841}
    EP-->>DE: container exit 0
    DE-->>MCP: stdout captured in result.stdout
    Note over DE: --rm: container automatically removed

    MCP-->>CC: tool_result: JSON string
    CC->>CC: parse result · continue reasoning

Loading

Steps 9–17 are the agentic tool-use loop — OpenCode and vLLM exchange multiple inference calls until the task is complete. Each loop iteration reads/writes the workspace volume. The calling agent is blocked and waiting; it receives the final result only when the container exits.

---

Diagram 05 — Artifact Boundary Map

Every artifact classified by type, direction, and mount mode.

flowchart LR
    subgraph AGENT["Calling Agent\n(Claude Code / Codex / Open WebUI)"]
        direction TB
        TASK_STR["task: string\n'Refactor auth/login.py...'"]
        TOUT["timeout: int\n(default 300s)"]
        RES["tool_result: JSON\n{status, output,\nfiles_modified, tokens_used}"]
    end

    subgraph BOUNDARY["🔒 Docker Security Boundary"]
        direction TB

        subgraph ENV_IN["Environment → IN"]
            ENV1["$TASK"]
            ENV2["$PUID / $PGID"]
        end

        subgraph VOL_RO["Volumes :ro → IN only"]
            V1["opencode.json"]
            V2["auth.json"]
            V3["AGENTS.md"]
            V4["commands/ · skills/"]
        end

        subgraph VOL_RW["Volume :rw → IN + OUT"]
            WS["./workspace/\nproject source files\n← read as context\n→ written by agent"]
            DATA["./data/\nopencode session state\n← persists across runs"]
        end

        subgraph STDOUT_OUT["stdout → OUT only"]
            JSON["JSON result object\n(machine-readable)"]
        end
    end

    TASK_STR -->|"ENV inject"| ENV1
    TOUT -->|"subprocess timeout"| BOUNDARY
    ENV1 --> JSON
    VOL_RO -.->|"read-only\ncannot be written"| JSON
    WS --> JSON
    JSON --> RES

Loading

Dashed arrows on :ro mounts visualise the security guarantee: those artifacts flow into the container but can never be modified by the agent, even if the task prompt attempts to overwrite them.

---

Artifact Reference Tables

Inputs — from the calling agent

Artifact	Type	How it enters	Notes
$TASK	string	ENV variable	The full task prompt
$PUID / $PGID	int	ENV variable	Host user identity for file ownership
timeout	int	subprocess param	Enforced on host, default 300s

Config — read-only mounts (:ro)

Artifact	Path in container	Purpose
opencode.json	~/.config/opencode/opencode.json	Provider, model, context settings
auth.json	~/.config/opencode/auth.json	vLLM endpoint + API tokens
AGENTS.md	~/.config/opencode/AGENTS.md	Global agent behaviour rules
commands/	~/.config/opencode/commands/	Slash-commands (/refactor-audit etc.)
skills/	~/.config/opencode/skills/	Reusable skill definitions

Workspace — read/write mount (:rw)

Artifact	Direction	Notes
Existing source files	→ IN	Read by OpenCode as task context
Edited / new files	← OUT	Written by OpenCode during task
Deleted files	← OUT	Removals via bash tool
WORKLOG.md	← OUT	Written if write-worklog skill is used
./data/ session state	↔ IN+OUT	Persists across multiple runs

Outputs — returned to the calling agent

Artifact	Channel	Type	Notes
status	stdout JSON	"done" | "error"	Task success indicator
output	stdout JSON	string	Natural language summary
files_modified	stdout JSON	string[]	Paths of changed files
tokens_used	stdout JSON	int	Inference token count
Exit code	process exit	0 | 1	Captured by MCP server
Mutated workspace	bind-mount	files	Visible on host immediately after container exit

---

JSON Output Schema

{
  "status": "done",
  "output": "Refactored auth/login.py: extracted LoginValidator class with 3 methods. All 12 tests pass.",
  "files_modified": [
    "src/auth/login.py",
    "tests/test_auth.py"
  ],
  "tokens_used": 5841
}

---

Files Changed in the Repository

File	Status	Change
entrypoint.sh	Modified	Add $TASK branch at the end (5 lines)
compose.headless.yml	New	Headless Compose without TTY, restart: no
tools/mcp_sandbox_server.py	New	MCP server for Claude Code integration
tools/openwebui_tool.py	New	Open WebUI Tool function (~20 lines)
Dockerfile	Unchanged	No changes required
compose.yml	Unchanged	Interactive TUI mode preserved

---

Based on jammsen/docker-coding-agent-sandbox · June 2026

[christestet]

@jammsen - issue is yours to refine

[jammsen]

@coderabbitai - Can you please do this 3 things:

1. Review this issue and give me your input to this
2. Do a security review
3. Do a software architect review

about this Feature-Request?
Thank you!

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
echo "=== Repo structure ==="
tree -L 3 2>/dev/null || find . -maxdepth 3 -not -path './.git/*' | sort

echo ""
echo "=== entrypoint.sh ==="
cat entrypoint.sh 2>/dev/null || echo "NOT FOUND"

echo ""
echo "=== Dockerfile ==="
cat Dockerfile 2>/dev/null || echo "NOT FOUND"

echo ""
echo "=== compose.yml ==="
cat compose.yml 2>/dev/null || docker-compose.yml 2>/dev/null || cat docker-compose.yml 2>/dev/null || echo "NOT FOUND"

echo ""
echo "=== README ==="
cat README.md 2>/dev/null | head -100 || echo "NOT FOUND"

echo ""
echo "=== tools/ directory ==="
ls -la tools/ 2>/dev/null || echo "NOT FOUND"

Length of output: 10266

---

---

@jammsen — great feature proposal, the diagrams are thorough. Here is my full review across all three dimensions.

---

1. General Review

The core concept is architecturally sound: adding a single $TASK branch to the bottom of entrypoint.sh is minimal, backward-compatible, and clean. The ephemeral --rm container-per-task model is the right pattern for a sandboxed sub-agent.

What is well done:

• The interactive TUI path is fully preserved — zero regression risk
• Volume strategy (:ro for config/auth, :rw only for workspace) is correct
• The JSON output contract is well-defined
• Air-gapped inference keeps data local
• The sequence diagrams make the intended behavior unambiguous

Key open question before implementation: Does opencode run "$TASK" --format json -q actually produce the proposed JSON schema (status, output, files_modified, tokens_used)? The current repo shows opencode is installed via curl -fsSL https://opencode.ai/install | bash without a version pin — the run subcommand flags and output format need to be verified against the exact installed version. files_modified and tokens_used in particular are likely not native opencode output fields, which would require a wrapper script to produce them.

---

2. Security Review

🔴 High Priority

S1 — CLI flag injection via $TASK

The proposed entrypoint addition:

exec gosu opencode:opencode opencode run "$TASK" --format json --quiet

Shell quoting protects against word-splitting but not against flag injection. If $TASK is "Do X" --some-opencode-flag value, the extra flag is interpreted by opencode. Use -- to terminate flag parsing:

exec gosu opencode:opencode opencode run --format json --quiet -- "$TASK"

Or pass the task via stdin/a temp file rather than a CLI argument.

S2 — compose.headless.yml must inherit all security hardening

The current compose.yml has carefully tuned hardening:

security_opt:
  - no-new-privileges:true
cap_drop:
  - ALL
cap_add:
  - CHOWN
  - SETUID
  - SETGID
  - DAC_OVERRIDE

If compose.headless.yml is written from scratch without these, the headless mode would be less secure than interactive mode. Strongly recommend using Compose's extend/override pattern (-f compose.yml -f compose.headless.override.yml) so hardening is inherited by default, and the override only sets tty: false, stdin_open: false, restart: "no", and the TASK env injection.

S3 — No resource limits

A runaway or malicious task can exhaust host CPU/memory/PIDs. Add to the headless compose:

deploy:
  resources:
    limits:
      cpus: '2.0'
      memory: 4G
    reservations:
      memory: 512M
ulimits:
  nproc: 1024
  nofile:
    soft: 1024
    hard: 2048

🟡 Medium Priority

S4 — Internal network lateral movement

The container uses bridge networking + extra_hosts: host.docker.internal:host-gateway. The agent can make arbitrary HTTP requests to any host reachable from the Docker bridge — not just the vLLM server. Since this is air-gapped, risk is lower, but if the vLLM host is on a LAN with other services, the agent could probe them. Consider adding an explicit allow_hosts allowlist in opencode.json or using a network policy / iptables rule to restrict container egress to only the vLLM IP and port.

S5 — auth.json is readable inside the container

auth.json is mounted :ro (cannot be modified — good), but the agent running inside has read access to it. A task like "show me the contents of ~/.local/share/opencode/auth.json" or an injection in the task prompt could embed vLLM endpoint tokens in the stdout JSON output. For air-gapped setups this is lower risk, but worth noting. Consider whether auth credentials need to be accessible at the file level vs. passed as runtime env vars.

S6 — MCP server has no authentication

mcp_sandbox_server.py runs on the host. If it binds a port or Unix socket without auth, any local process (or a compromised browser extension, etc.) can trigger arbitrary task execution in the sandbox. The MCP server should enforce that only the legitimate calling agent can invoke it.

S7 — Unversioned opencode install (supply chain)

RUN curl -fsSL https://opencode.ai/install | bash

The base image is SHA-pinned (good), but the opencode binary is pulled at build time from an unversioned URL. A compromised or changed installer script would silently land a different binary. Pin to a specific release version or checksum-verify the binary post-download.

🟢 Low Priority / Already Well Handled

• --rm ephemeral containers: ✅
• no-new-privileges:true: ✅
• cap_drop: ALL with minimal re-adds: ✅
• Config files as :ro: ✅
• Non-root execution via gosu after setup: ✅

---

3. Software Architecture Review

🔴 Structural Gaps

A1 — Workspace concurrency / race conditions

The workspace volume (./workspace) is shared across all invocations. If two calling agents fire simultaneous tasks, both containers mount the same directory read-write with no locking. Concurrent write_file operations on the same files will corrupt state silently.

Mitigation options (pick one):

• Sequential queue in the MCP server (simplest for single-user use)
• Per-invocation workspace subdirectory: mount ./workspace/<task-id>/ per container
• Advisory file locks via a sidecar mechanism

A2 — JSON output contract may not match real opencode CLI

The proposed schema assumes opencode run --format json natively emits:

{"status":"done","output":"...","files_modified":[...],"tokens_used":5841}

If opencode's actual JSON output differs (missing files_modified, no tokens_used), the MCP server will fail silently or crash. This contract must be verified against the actual installed opencode version before building the MCP server around it. A thin wrapper script (sandbox_run.sh) that calls opencode and post-processes its output into the agreed schema would decouple the contract from the opencode CLI internals.

🟡 Design Recommendations

A3 — Two compose files creates drift risk

Maintaining compose.yml and compose.headless.yml in parallel means every security/config change must be applied twice. The recommended pattern:

compose.yml              ← base (all hardening, shared config, volumes)
compose.headless.yml     ← override: only tty/stdin/restart/TASK differences

Invoked as: docker compose -f compose.yml -f compose.headless.yml run --rm opencode

A4 — ./data session state is shared across headless tasks

./data (opencode session state) persists across runs by design — fine for interactive TUI. For headless sub-agent invocations, accumulated session state from previous tasks could influence future ones (context contamination). Consider whether headless invocations should use an isolated ./data/<task-id>/ or a fresh temp dir, vs. intentionally sharing session history.

A5 — MCP server is tightly coupled to docker compose

subprocess.run("docker compose -f compose.headless.yml run --rm ...") creates a fragile dependency on the Compose CLI, the file path, and the service name all being correct at runtime. Abstract this into a small SandboxRunner class with a well-defined interface, making it easier to switch to plain docker run or a different backend without rewriting the tool.

A6 — Timeout enforcement location

Timeout is described as a host-side subprocess timeout (default 300s). This is the right layer. Ensure it's implemented as subprocess.run(..., timeout=timeout) with explicit handling for subprocess.TimeoutExpired that kills the container (docker stop <container>) rather than orphaning it — --rm only removes on clean exit.

🟢 Well Designed

• Entrypoint modification is 5 lines, fully backward-compatible ✅
• Privilege drop before opencode executes ✅
• Calling agent abstraction (never touches Docker directly) ✅
• Clear artifact boundary (env in, stdout JSON out, bind-mount for files) ✅
• Air-gapped inference eliminates cloud data leakage risk ✅

---

Summary Table

#	Area	Severity	Topic
S1	Security	🔴 High	CLI flag injection via $TASK — use -- separator
S2	Security	🔴 High	Headless compose must inherit hardening from base compose
S3	Security	🔴 High	No resource limits (CPU/mem/PIDs) on headless container
S4	Security	🟡 Medium	No egress filtering beyond vLLM IP:port
S5	Security	🟡 Medium	auth.json readable by agent, could be in task output
S6	Security	🟡 Medium	MCP server needs authentication
S7	Security	🟡 Medium	opencode install not version-pinned
A1	Architecture	🔴 High	Workspace race condition for concurrent tasks
A2	Architecture	🔴 High	JSON output contract unverified against real opencode CLI
A3	Architecture	🟡 Medium	Two compose files — use override pattern instead
A4	Architecture	🟡 Medium	Session state (./data) contamination across headless tasks
A5	Architecture	🟡 Medium	MCP server tightly coupled to docker compose CLI
A6	Architecture	🟡 Medium	Timeout must explicitly kill container, not just Python subprocess

The highest-priority items before writing any code are S1 (flag injection), S2 (headless compose inheriting hardening), and A2 (verifying the actual opencode run --format json output schema). Everything else is implementable incrementally.

(=^･ω･^=)

[jammsen]

@coderabbitai

Great analysis thanks a lot.

Can you give me code snippets/examples to all finding in tthe actual codebase?

If you want (and if you are able to) you can do a code-branch called feat/task-mode, implement the changes there and link it here. If you cant, please only the code-snippets here in the comments please.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
echo "=== entrypoint.sh ==="
cat entrypoint.sh

echo ""
echo "=== Dockerfile ==="
cat Dockerfile

echo ""
echo "=== compose.yml ==="
cat compose.yml

echo ""
echo "=== .env or .env.example ==="
cat .env 2>/dev/null || cat .env.example 2>/dev/null || echo "NOT FOUND"

echo ""
echo "=== Full repo tree ==="
find . -not -path './.git/*' | sort

Length of output: 7319

---

---

@jammsen — I can't push branches directly, but here are ready-to-copy snippets for every finding, anchored to the actual files. Once you're happy with them I can also raise a `` request to have them wired into a PR automatically.

---

S1 — CLI flag injection (entrypoint.sh)

Current last line:

exec gosu $APP_USER:$APP_GROUP opencode

Replace with (add $TASK branch + -- flag terminator):

# ── Sub-agent / headless mode ──────────────────────────────────────────────
if [[ -n "${TASK}" ]]; then
    echo "> TASK env is set — running in headless sub-agent mode"
    exec gosu $APP_USER:$APP_GROUP opencode run --format json --quiet -- "${TASK}"
else
    echo "> No TASK env — starting interactive TUI"
    exec gosu $APP_USER:$APP_GROUP opencode
fi

The -- after --quiet ensures opencode's flag parser stops there; anything in $TASK (even if it starts with --) is treated as a positional string, not a flag.

---

S2 + A3 — Headless compose as a pure override (not a parallel file)

New file: compose.headless.yml (override only — all hardening is inherited from compose.yml):

# compose.headless.yml — override for headless/sub-agent mode
# Usage: docker compose -f compose.yml -f compose.headless.yml run --rm opencode
#
# This file ONLY changes the three things that differ from interactive mode.
# All security hardening (cap_drop, security_opt, volumes, etc.) is inherited
# from compose.yml automatically.

services:
  opencode:
    container_name: ""          # let Docker auto-name so parallel runs don't collide
    stdin_open: false           # no interactive stdin needed
    tty: false                  # no TTY — stdout is captured as JSON
    restart: "no"               # ephemeral: run once and exit
    environment:
      - HOME=/home/opencode
      - TASK=${TASK}            # injected by the MCP server / calling script

Invocation:

docker compose -f compose.yml -f compose.headless.yml run --rm opencode

---

S3 — Resource limits (compose.headless.yml, append to the service block above)

    deploy:
      resources:
        limits:
          cpus: "2.0"
          memory: 4G
        reservations:
          memory: 512M
    ulimits:
      nproc: 1024
      nofile:
        soft: 1024
        hard: 2048

---

S4 — Egress network isolation (compose.yml + compose.headless.yml)

Create a named network restricted to the vLLM host:

# append to compose.yml
networks:
  sandbox_net:
    driver: bridge
    driver_opts:
      com.docker.network.bridge.name: sandbox0
    ipam:
      config:
        - subnet: 172.30.0.0/28   # tiny subnet — only ~14 addresses

services:
  opencode:
    # ... existing config ...
    networks:
      - sandbox_net

Then add an iptables drop rule on the host (put in a startup script):

# Allow container → vLLM only; drop everything else from the sandbox bridge
VLLM_IP="10.0.0.x"   # your vLLM server
iptables -I DOCKER-USER -i sandbox0 ! -d "${VLLM_IP}" -j DROP
iptables -I DOCKER-USER -i sandbox0 -d "${VLLM_IP}" -p tcp --dport 8000 -j ACCEPT

---

S5 — auth.json exfiltration note

No code change required for an air-gapped setup, but add this guard comment directly in compose.yml so the risk is documented at the mount point:

      # auth.json is :ro — agent cannot modify it, but CAN read it.
      # Risk: a prompt-injected task could echo its contents into stdout JSON.
      # Mitigation for higher-security deployments: pass vLLM credentials as
      # runtime env vars only (OPENAI_API_KEY etc.) and remove this mount.
      - ./config/auth.json:/home/opencode/.local/share/opencode/auth.json:ro

---

S6 — MCP server authentication (tools/mcp_sandbox_server.py)

New file: tools/mcp_sandbox_server.py

#!/usr/bin/env python3
"""
MCP sandbox server — wraps docker compose run for sub-agent task execution.
Requires SANDBOX_API_TOKEN env var; callers must pass the same token.
"""
import os
import subprocess
import threading
import uuid
import json
from pathlib import Path

_TOKEN = os.environ.get("SANDBOX_API_TOKEN", "")
_LOCK = threading.Lock()            # S1/A1: serialise concurrent calls
_REPO_ROOT = Path(__file__).resolve().parents[1]

class SandboxRunner:                # A5: abstraction layer over docker compose
    def __init__(self, timeout: int = 300):
        self.timeout = timeout

    def run(self, task: str) -> dict:
        container_name = f"opencode-sandbox-{uuid.uuid4().hex[:8]}"
        cmd = [
            "docker", "compose",
            "-f", str(_REPO_ROOT / "compose.yml"),
            "-f", str(_REPO_ROOT / "compose.headless.yml"),
            "run", "--rm",
            "--name", container_name,
            "-e", f"TASK={task}",
            "opencode",
        ]
        try:
            result = subprocess.run(
                cmd,
                capture_output=True,
                text=True,
                timeout=self.timeout,   # A6: host-side timeout
            )
            return json.loads(result.stdout)
        except subprocess.TimeoutExpired:
            # A6: explicitly kill the container so --rm can clean up
            subprocess.run(["docker", "stop", container_name], check=False)
            return {"status": "error", "output": "Task timed out", "files_modified": [], "tokens_used": 0}
        except json.JSONDecodeError:
            return {"status": "error", "output": result.stdout, "files_modified": [], "tokens_used": 0}


def run_in_sandbox(task: str, token: str, timeout: int = 300) -> dict:
    """Entry point called by Claude Code / Open WebUI MCP tool."""
    # S6: validate token
    if not _TOKEN:
        raise RuntimeError("SANDBOX_API_TOKEN is not set on the server")
    if token != _TOKEN:
        raise PermissionError("Invalid API token")

    # A1: serialise — one task at a time (swap for per-task workspace for parallelism)
    with _LOCK:
        return SandboxRunner(timeout=timeout).run(task)

Set the token before starting the server:

export SANDBOX_API_TOKEN="$(openssl rand -hex 32)"

---

S7 — Pin opencode version in Dockerfile

Current:

RUN curl -fsSL https://opencode.ai/install | bash

Replace with:

ARG OPENCODE_VERSION=0.1.157        # pin — update deliberately
# Install opencode at a specific version and verify checksum
RUN set -eux; \
    INSTALL_URL="https://opencode.ai/install"; \
    curl -fsSL "${INSTALL_URL}" -o /tmp/opencode-install.sh; \
    # Verify the script hasn't changed unexpectedly (update hash when you bump version)
    echo "EXPECTED_SHA256  /tmp/opencode-install.sh" | sha256sum -c || \
        { echo "opencode installer checksum mismatch — aborting"; exit 1; }; \
    OPENCODE_VERSION="${OPENCODE_VERSION}" bash /tmp/opencode-install.sh; \
    rm /tmp/opencode-install.sh

Get the current hash with curl -fsSL https://opencode.ai/install | sha256sum and bake that into the EXPECTED_SHA256 line. Update both OPENCODE_VERSION and the hash together in each upgrade commit.

---

A1 — Workspace concurrency (per-task subdirectory variant)

If you want to allow parallel calls instead of serialising them, mount a per-task subdirectory in the override compose and pass it as an env var:

# in SandboxRunner.run()
task_id = uuid.uuid4().hex[:12]
workspace_dir = _REPO_ROOT / "workspace" / task_id
workspace_dir.mkdir(parents=True, exist_ok=True)

cmd = [
    "docker", "compose",
    "-f", str(_REPO_ROOT / "compose.yml"),
    "-f", str(_REPO_ROOT / "compose.headless.yml"),
    "run", "--rm",
    "--name", f"opencode-sandbox-{task_id}",
    "-e", f"TASK={task}",
    # override the workspace volume to an isolated subdirectory
    "-v", f"{workspace_dir}:/home/opencode/workspace:rw",
    "opencode",
]

---

A2 — JSON output contract wrapper (scripts/sandbox_run.sh)

Because opencode run --format json likely does not natively emit files_modified or tokens_used, wrap it:

New file: scripts/sandbox_run.sh

#!/usr/bin/env bash
# Runs opencode and normalises its output into the agreed JSON schema.
# Called by entrypoint.sh instead of opencode directly.
set -e

TASK="${1}"
WORKSPACE="/home/opencode/workspace"

# Snapshot files before
BEFORE=$(find "$WORKSPACE" -type f | sort)

# Run opencode, capture raw stdout
RAW=$(opencode run --format json --quiet -- "${TASK}" 2>&1) || EXIT=$?
EXIT=${EXIT:-0}

# Snapshot files after
AFTER=$(find "$WORKSPACE" -type f | sort)

# Compute changed files
MODIFIED=$(comm -13 <(echo "$BEFORE") <(echo "$AFTER") | \
           sed "s|${WORKSPACE}/||g" | jq -R . | jq -s .)

STATUS="done"
[[ $EXIT -ne 0 ]] && STATUS="error"

# Emit normalised JSON on stdout
jq -n \
  --arg status "$STATUS" \
  --arg output "$RAW" \
  --argjson files_modified "$MODIFIED" \
  --argjson tokens_used 0 \
  '{status: $status, output: $output, files_modified: $files_modified, tokens_used: $tokens_used}'

Update the headless branch in entrypoint.sh to call this wrapper instead of opencode directly:

if [[ -n "${TASK}" ]]; then
    exec gosu $APP_USER:$APP_GROUP bash /scripts/sandbox_run.sh "${TASK}"
else
    exec gosu $APP_USER:$APP_GROUP opencode
fi

---

A4 — Session state isolation for headless tasks (compose.headless.yml)

services:
  opencode:
    volumes:
      # Override the shared ./data mount with a per-task ephemeral volume.
      # Comment this out if you WANT session history to carry across tasks.
      - /tmp/opencode-session-${TASK_ID:-default}:/home/opencode/.local/share/opencode

Set TASK_ID alongside TASK in the MCP server call:

"-e", f"TASK_ID={task_id}",

---

A6 — Timeout with explicit container kill (already shown in S6, standalone version)

try:
    result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
except subprocess.TimeoutExpired:
    # --rm only fires on clean exit; kill explicitly to avoid orphaned containers
    subprocess.run(["docker", "stop", container_name], check=False, timeout=15)
    return {
        "status": "error",
        "output": f"Task exceeded {timeout}s timeout and was stopped",
        "files_modified": [],
        "tokens_used": 0,
    }

---

Files summary

Finding	File	Action
S1	entrypoint.sh	Add $TASK branch with -- separator
S2+A3	compose.headless.yml	New override-only file
S3	compose.headless.yml	Add deploy.resources + ulimits
S4	compose.yml + host iptables	Named network + egress rule
S5	compose.yml	Add risk comment at auth.json mount
S6	tools/mcp_sandbox_server.py	New file with token auth + SandboxRunner
S7	Dockerfile	Pin OPENCODE_VERSION ARG + checksum verify
A1	tools/mcp_sandbox_server.py	Per-task workspace subdirectory
A2	scripts/sandbox_run.sh	New wrapper that normalises JSON output
A4	compose.headless.yml	Per-task session state volume
A5	tools/mcp_sandbox_server.py	SandboxRunner class
A6	tools/mcp_sandbox_server.py	TimeoutExpired → docker stop

Want me to trigger `` to have all of this turned into a proper PR diff? That would wire all these snippets into the actual files with the correct line placements.

(=^･ω･^=)

---

💡 For code changes across multiple files, use @coderabbitai plan in an issue comment

[christestet]

@jammsen what do you think about extending this refinement to not only use a node like system but also introduce a control-plan - node system where we can ocestrate sandbox worker agents from one orchestator? or should we do this aside of this current issue?

[christestet]

Refinement: consolidated task list + corrections from verifying against the real opencode CLI

I went through the whole thread (the diagrams, CodeRabbit's S1–S7 / A1–A6 review, and the ready-to-paste snippets) and then validated the key assumptions against the actual opencode CLI behaviour before turning this into a build plan. A few of the snippets won't work as written — flagged below — and I found one blocker nobody raised yet.

---

🔬 Research findings & corrections (read before coding)

F1 — --format json is a JSONL event stream, not a single object (confirms & sharpens A2 — this is the #1 blocker)
opencode run --format json emits one JSON object per event/part (type: "text", type: "step_finish", tool parts, …), i.e. NDJSON — not the proposed {status, output, files_modified, tokens_used} object.
Consequences:

• The MCP snippet's json.loads(result.stdout) will raise JSONDecodeError on every run (multiple objects on stdout).
• tokens_used is obtainable — from step_finish parts (jq 'select(.type=="step_finish") | .part' exposes cost + tokens).
• files_modified is not native — derive it (snapshot diff, as in the sandbox_run.sh wrapper, or by parsing edit/write tool parts).
• ➡️ The scripts/sandbox_run.sh wrapper is mandatory, not optional, and it must parse the JSONL (extract assistant text from type:"text", tokens from step_finish) rather than dumping raw stdout into output with tokens_used: 0.

F2 — NEW BLOCKER: permission "ask" hangs headless runs forever (not raised in the review)
In non-interactive mode any permission set to "ask" creates a promise that never resolves → the session freezes silently. Our current config/opencode.json sets "webfetch": "ask", and on top of that the hidden external_directory and doom_loop permissions default to "ask". A headless run that touches any of these will hang until the timeout kills it.

• ➡️ Ship a headless agent profile with an explicit allow/deny policy (no "ask"), e.g. external_directory: "allow", webfetch: "allow"/"deny", dangerous bash patterns → "deny". Optionally --dangerously-skip-permissions exists ("auto-approve non-denied"), but an explicit policy is safer.

F3 — --quiet / -q is not in the documented run flag list. The diagrams and snippets use opencode run ... --quiet -q, but the current CLI reference lists --format, --agent, --model, --session, --continue, --dangerously-skip-permissions, etc. — no --quiet. ➡️ Verify against the pinned version; drop it if it errors.

F4 — S7 fix uses the wrong variable. The install script's version override is VERSION, not OPENCODE_VERSION (the script queries the GitHub releases API and honours VERSION=x.y.z). Checksum-pinning the installer script is brittle (it changes legitimately); prefer pinning VERSION= and verifying the resulting binary checksum, or install via npm i -g opencode-ai@x.y.z. Note the maintained repo is now anomalyco/opencode.

F5 — S1: there is no stdin path for the prompt (it's a positional arg only). So the "pass via stdin" alternative isn't available — the -- flag terminator is the correct and only fix. ✅ keep that.

F6 — the "MCP server" snippet is a plain function, not an MCP server. run_in_sandbox(task, token, timeout) has no MCP transport/tool registration. ➡️ Wrap it with the mcp Python SDK (FastMCP tool over stdio) so Claude Code / Codex can actually call it.

---

✅ Implementation task list

P0 — blockers (must land first, in this order)

• F1/A2: Add scripts/sandbox_run.sh that runs opencode, parses the JSONL stream, and emits the agreed {status, output, files_modified, tokens_used} schema (text from type:"text", tokens from step_finish, files via before/after diff). Pin the schema with a sample fixture + test.
• F2: Add a headless permission profile (no "ask": set external_directory/doom_loop/webfetch explicitly) wired only into the headless path.
• S1/F5: entrypoint.sh — add $TASK branch using exec gosu … opencode run --format json -- "${TASK}" (the -- terminator; verify/remove --quiet per F3). Interactive path unchanged.
• S2+A3: Add override-only compose.headless.yml (stdin_open:false, tty:false, restart:"no", TASK), invoked as docker compose -f compose.yml -f compose.headless.yml run --rm opencode. All hardening inherited from base — do not fork a parallel file.

P1 — security hardening

• S3: Resource limits in compose.headless.yml (deploy.resources.limits cpus/memory + ulimits nproc/nofile). Confirm deploy.limits are honoured by our docker compose version.
• S7/F4: Pin opencode with VERSION= ARG (or npm @x.y.z) + verify the binary checksum in the Dockerfile.
• S6/F6: Implement tools/mcp_sandbox_server.py as a real FastMCP server with token auth (SANDBOX_API_TOKEN).
• A6: Host-side subprocess.run(timeout=…); on TimeoutExpired → docker stop <name> (named container) so --rm can't orphan it.
• A1: Concurrency — start with a serialized lock in the MCP server (single-user default); document the per-task-workspace variant for parallelism.

P2 — defense-in-depth / docs

• S4: Optional egress allowlist (named bridge + DOCKER-USER iptables rule to vLLM IP:port). Lower priority — air-gapped.
• S5: Document the auth.json read-exfil risk at the mount point; note runtime-env-var alternative for higher-security deployments.
• A4: Decide & document session-state policy for headless — isolated ./data/<task-id> (avoid context contamination) vs. intentional sharing.
• A5: Keep docker invocation behind a SandboxRunner abstraction (already in the snippet) so the backend can change.
• Docs/CI: README "Sub-Agent / Task mode" section; a smoke test that runs a trivial $TASK end-to-end and asserts the JSON schema; update scripts/reset-sandbox.sh if per-task dirs are introduced.

---

🧭 On @christestet's orchestrator / control-plane question

I'd keep it as a separate follow-up issue, not fold it in here. This issue is already a tight, backward-compatible vertical slice (one $TASK branch + a headless override + a wrapper). A control-plane ↔ worker-node orchestration layer is a much larger design (scheduling, queueing, task IDs, result store, multi-worker concurrency — which supersedes the simple A1 lock) and would balloon the scope and review surface. Landing the single-node headless contract first gives the orchestrator a stable, well-defined worker API to build on. Suggest opening feat: control-plane orchestration and linking it as a dependent of this one.

---

Bottom line: the architecture is sound; the three things that must be nailed before anything else are F1 (JSONL wrapper — the proposed json.loads breaks), F2 (headless permission hang — currently guaranteed by webfetch: "ask"), and S2 (headless compose inheriting hardening via override).

Sources: opencode CLI docs · opencode permissions docs · headless "ask" hang reports #3503, #14473, #16367 · non-interactive mode #10411 · --command + json bug #2923