Skip to content

External Agent CLI Nodes

Orcheo can run Claude Code, Codex, and Gemini CLI as workflow nodes through the execution worker. This feature is intended for self-hosted deployments where the worker host can safely run external coding-agent CLIs inside validated Git worktrees.

Support Scope

  • Self-hosted only.
  • Worker-managed installs only; Orcheo does not install these CLIs into global system paths.
  • Manual provider login is still required on the worker host.
  • Canvas can also disconnect worker auth state without uninstalling the managed runtime.
  • Claude Code unattended runs require the worker process to run as a non-root user. Anthropic blocks --dangerously-skip-permissions under root/sudo.
  • V1 does not add new Orcheo environment variables for runtime roots, maintenance cadence, or provider selection.

Runtime Behavior

Orcheo manages provider runtimes under a persistent root with strong defaults:

  • Use /data/agent-runtimes when /data exists and is writable.
  • Otherwise use ~/.orcheo/agent-runtimes.
  • In Docker deployments, keep the worker HOME on persistent storage so provider login state such as ~/.claude* and $CODEX_HOME/auth.json survives container restarts.
  • In Docker deployments, run backend and worker processes as a non-root user and make the mounted workspace writable by that container user.
  • Install the latest published provider CLI into a versioned provider-owned prefix.
  • Keep one current runtime and one previous known-good runtime for rollback and debugging.
  • Check maintenance on a fixed 7-day cadence.
  • Do not perform inline upgrades immediately before executing a workflow step.

Failed maintenance or failed upgrades do not replace the active runtime. New versions are staged side-by-side and only become current after install verification succeeds.

Provider Bootstrap

Codex

  • Package: @openai/codex
  • Runtime command: codex exec --full-auto --sandbox workspace-write
  • Manual login:
codex login
  • Programmatic auth is also supported through provider-native credentials such as CODEX_API_KEY or OPENAI_API_KEY. Orcheo does not rename or wrap those credentials.

Claude Code

  • Package: @anthropic-ai/claude-code
  • Runtime command: claude --dangerously-skip-permissions --print ...
  • Manual login:
claude
  • Provider-native auth is also supported when the worker environment already exposes supported Claude Code credentials such as ANTHROPIC_API_KEY.

Gemini CLI

  • Package: @google/gemini-cli
  • Runtime command: gemini --prompt ... --approval-mode yolo --output-format text
  • Manual login:
cd /workspace/agents
gemini /auth signin
  • Provider-native auth is also supported when the worker environment already exposes supported Gemini credentials such as GEMINI_API_KEY, or Vertex AI credentials such as GOOGLE_GENAI_USE_VERTEXAI=true with the required Google Cloud environment.
  • Orcheo starts Gemini sign-in from /workspace/agents so Gemini can record that trusted folder in ~/.gemini/trustedFolders.json.
  • For Google-account login portability across workers, Orcheo persists a single versioned GEMINI_AUTH_JSON vault secret whose files object contains every ~/.gemini/*.json file plus any installation_id files, then restores them before auth probes and runs.

Node Contract

ClaudeCodeNode, CodexNode, and GeminiNode share the same workflow-facing fields:

  • prompt
  • system_prompt
  • working_directory
  • auto_init_git_worktree
  • timeout_seconds

By default, Orcheo initializes a Git worktree in working_directory when the path is safe but not yet inside one. Orcheo still rejects /, the worker home directory, and the managed runtime root.

Normalized node output includes:

  • status
  • provider
  • resolved_version
  • command
  • command_path
  • working_directory
  • exit_code
  • stdout
  • stderr
  • reason
  • message

If auth is missing, the node returns status = "setup_needed" plus exact login commands and rerun guidance instead of a generic failure.

Example Snippets

Codex autofix node

{
  "type": "CodexNode",
  "name": "codex_fix",
  "prompt": "Read the repository, run the targeted tests, make the minimal fix, and stop.",
  "working_directory": "{{inputs.repo_path}}",
  "timeout_seconds": 1800
}

Claude Code review node

{
  "type": "ClaudeCodeNode",
  "name": "claude_review",
  "prompt": "Review the current branch for behavioral regressions and summarize the highest-risk issues.",
  "working_directory": "{{inputs.repo_path}}",
  "timeout_seconds": 1800
}

Gemini review node

{
  "type": "GeminiNode",
  "name": "gemini_review",
  "prompt": "Review the current branch for behavioral regressions and summarize the highest-risk issues.",
  "working_directory": "{{inputs.repo_path}}",
  "timeout_seconds": 1800
}

Canvas Delivery Checklist

Backend support does not automatically make these nodes usable in Canvas. The frontend delivery checklist is:

  • Add ClaudeCodeNode, CodexNode, and GeminiNode to the Canvas node catalog.
  • Expose prompt, system_prompt, working_directory, and timeout_seconds through the current node editing surface. Do not rely on the deprecated node inspector for external-agent setup actions.
  • Add a shared Canvas settings surface for worker-scoped provider readiness, OAuth login, and disconnect/logout, because external-agent auth belongs to the worker host, not to individual workflow nodes.
  • Label the nodes as self-hosted/execution-worker features.
  • Surface setup-needed results so operators can jump to the shared External Agents settings flow instead of shelling into the worker manually.