Orchestrating agent CLIs from another agent

How to use one agent CLI to test and automate other agent CLIs. We used OpenCode as the orchestrator to test OpenCode, Codex, and Cursor onboarding against Conductor.

When to use: regression-test MCP onboarding. Humans connecting day-to-day should follow connecting.md and connect/bootstrap.md instead.

Client config SoT: connecting.md (single page). This guide is for orchestration/testing only.

The pattern

Orchestrator (opencode or agent --print)
  │
  ├── opencode run --model X --auto --dir <workspace> "prompt"
  ├── codex exec -m X -C <workspace> --sandbox danger-full-access --skip-git-repo-check "prompt"
  └── agent --print --force --trust --approve-mcps --sandbox disabled --workspace <workspace> "prompt"

Commands by CLI

OpenCode (orchestrator and target)

opencode run executes a prompt non-interactively and exits. Use for scripting.

opencode run \
  --model opencode/deepseek-v4-flash-free \
  --auto \
  --dir "$HOME/workspace/test-folder" \
  "Your prompt here"

Key flags: - --model <provider/model> — select the model - --auto — auto-approve permissions (required for MCP config writes, git clones, etc.) - --dir <path> — working directory - --continue / --session <id> — resume a previous session

Codex

codex exec runs non-interactively.

codex exec \
  -m gpt-5.6-luna \
  -C "$HOME/workspace/test-folder" \
  --sandbox danger-full-access \
  --skip-git-repo-check \
  "Your prompt here"

Key flags: - -m <model> — model name - -C <dir> — working directory - --sandbox <mode> — workspace-write (default, blocks network) or danger-full-access (allows network to Conductor) - --skip-git-repo-check — allow running outside a git repo - --ephemeral — don't persist session files - codex mcp add <name> --url <url> --bearer-token-env-var <VAR> — add MCP server

Cursor / agent CLI

Cursor IDE launcher (cursor) is GUI-only. Cursor Agent CLI (agent) supports headless --print runs. See connect/cursor.md for .cursor/mcp.json, agent mcp enable, session-reload, and approval-layer notes.

agent --print --force --trust --approve-mcps --sandbox disabled \
  --workspace "$HOME/workspace/test-folder" \
  "Your prompt here"

Automate config write + mcp-smoke.sh; unattended setup tool calls may still be approval-gated even with --approve-mcps.

MCP configuration per CLI

CLI	Preferred config	Token handling
OpenCode	JSON Bearer {env:CONDUCTOR_MCP_AUTH_TOKEN}	Runtime env interpolation
Codex	bearer_token_env_var = "CONDUCTOR_MCP_AUTH_TOKEN"	Env var name only
Cursor Agent (agent)	.cursor/mcp.json + ${CONDUCTOR_MCP_AUTH_TOKEN}	Env interpolation; agent mcp enable

Full snippets: connect/opencode.md, connect/codex.md, connect/cursor.md.

Token retrieval

Authoritative path is the Python secret-gate CLI (not legacy secret-gate.ps1).

secret-gate auth   # if needed
eval "$(secret-gate refresh --set ci --print-env)"
printf 'token present (%s chars)\n' "${#CONDUCTOR_MCP_AUTH_TOKEN}"

Windows: use pwsh 7.2+ only — see connect/bootstrap.md.

Invoke-Expression (& secret-gate refresh --set ci --print-env --shell pwsh)
Write-Host "token present ($($env:CONDUCTOR_MCP_AUTH_TOKEN.Length) chars)"

Common failure modes

Symptom	CLI	Cause	Fix
"Permission denied" writing config	OpenCode	Missing --auto flag	Add --auto
"Socket access denied" fetching URL	Codex	workspace-write blocks network	--sandbox danger-full-access or offline connect docs
No run/exec on cursor IDE	Cursor IDE	GUI launcher only	Use agent --print CLI instead
Conductor missing mid-session	agent	mcp.json written after start	Start a new agent process
User rejected MCP: conductor-setup	agent	Tool-call approval ≠ server approval	Interactive approve, or HTTP smoke/tools/call
Token printed in error output	OpenCode	Wrong header Authorization: Bearer	Prefer JSON {env:…}; CLI must use KEY=VALUE
"Session not found" on MCP call	Any	Missing Mcp-Session-Id	Capture from initialize; or use scripts/mcp-smoke.sh
secret-gate version error on Windows	Any	PowerShell 5.1	Switch to pwsh

Test workspace layout

ai-agent-workspace/
├── opencode-cli-test/
│   └── conductor/            # cloned conductor repo
├── codex-cli-test/
│   └── conductor/
└── cursor-cli-test/
    ├── .cursor/mcp.json
    └── conductor/