Skip to content
EdgePlane v0.13

Agent Setup

edgeplane run is the unified agent launcher. It validates your environment, fetches the agent’s onboarding manifest, and injects EdgePlane as an MCP server before handing off to the agent binary.

Supported Runtimes

Section titled “Supported Runtimes”

All runtimes launch through edgeplane run <runtime>:

RuntimeCommandAgent type
claudeedgeplane run claudeClaude Code (ACP, persistent session)
codexedgeplane run codexOpenAI Codex CLI
geminiedgeplane run geminiGoogle Gemini CLI
openclawedgeplane run openclawOpenClaw driver agent
customedgeplane run customCustom ACP agent with instance isolation

ACP Runtimes (Claude Code)

Section titled “ACP Runtimes (Claude Code)”

The claude runtime uses the Agent Communication Protocol (ACP): a persistent JSON-RPC session over stdio. EdgePlane injects itself as an MCP server at launch, then maintains a live session until the agent exits or completes naturally.

Key behaviors:

  • Session persists across compaction — EdgePlane re-injects context on compact
  • Lifecycle hooks fire automatically: session registration, context injection, tool-audit, session-end
  • edgeplane run claude resumes the previous session automatically; pass --new to force a fresh session instead

What edgeplane run does

Section titled “What edgeplane run does”
  1. Checks that the agent binary is on PATH (prints an install hint if not)
  2. Validates profile and session context against the tower
  3. Fetches agent config from the onboarding manifest
  4. Writes runtime config to ~/.edgeplane/instances/<session-id>/
  5. Injects EdgePlane by writing itself into the agent’s mcpServers configuration before handoff — no manual MCP config required
  6. execs the agent

Session Tokens

Section titled “Session Tokens”

Session tokens are revocable, expiring, and never written to agent config files on disk. They are injected at exec time from ~/.edgeplane/session.json.

Terminal window
edgeplane auth login                       # browser OIDC flow → ~/.edgeplane/session.json (default TTL: 365 days)
edgeplane auth login --ttl-hours 24        # shorter TTL (max: 87600 hours / 10 years)
edgeplane auth login --print-token         # print token value (for scripting)


edgeplane auth whoami                      # verify identity and expiry
edgeplane auth logout                      # revoke server-side and clear local file
edgeplane auth logout --local-only         # clear local file only

For CI and headless pipelines, use service account tokens (ep_sa_*) created via the API. There is no EP_TOKEN — static shared-secret auth was removed in v0.11.0. For non-interactive use (CI, automation), set EP_AGENT_TOKEN to a service account token (ep_sa_*) instead of using edgeplane auth login.

Auth typeRecommended for
OIDC interactive (edgeplane auth login)Interactive use, SSO environments
Service account (ep_sa_*)CI, headless pipelines
Node JWTDaemons and machines (edgeplaned)

Profiles

Section titled “Profiles”

Profiles carry an operator’s personal environment config, tool settings, and instruction files. The profile loads automatically when you run edgeplane run.

Terminal window
edgeplane profile activate --name <name>    # switch to a different profile
edgeplane profile publish --name <name>     # push local profile to the tower
edgeplane profile pull --name <name>        # pull profile from the tower

MCP Configuration (manual wiring)

Section titled “MCP Configuration (manual wiring)”

If you’re running Claude Code manually without edgeplane run, add EdgePlane as an MCP server in your .mcp.json or mcpServers block:

Claude Code (.mcp.json):

{
  "mcpServers": {
    "edgeplane": {
      "command": "edgeplane",
      "args": ["serve"],
      "env": {
        "EP_BASE_URL": "https://edgeplane.example.com"
      }
    }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.edgeplane]
command = "edgeplane"
args = ["serve"]
startup_timeout_sec = 45
tool_timeout_sec = 60
env = { EP_BASE_URL = "https://edgeplane.example.com" }

Gemini CLI (~/.gemini/settings.json):

{
  "mcpServers": {
    "edgeplane": {
      "command": "edgeplane",
      "args": ["serve"],
      "env": {
        "EP_BASE_URL": "https://edgeplane.example.com"
      }
    }
  }
}

edgeplane serve reads auth automatically from ~/.edgeplane/session.json (OIDC session) or the node JWT at /etc/edgeplane/node.json. No token in the config is needed.

Environment Variables

Section titled “Environment Variables”
VariablePurposeDefault
EP_BASE_URLControl plane HTTP base URLhttp://localhost:8008

Output format is controlled by the --json global flag on any command (e.g. edgeplane health --json).

There is no EP_TOKEN. Auth is handled via session file, node JWT, or service account token — never a static shared secret.

Diagnosing Issues

Section titled “Diagnosing Issues”
Terminal window
edgeplane run codex doctor --json       # detailed readiness diagnostics
edgeplane auth whoami                   # verify auth before launching
edgeplane health --json                 # verify server connectivity

If an agent fails to bring up the edgeplane MCP server:

  • Confirm edgeplane auth whoami succeeds before launching
  • Confirm EP_BASE_URL points at the right tower and edgeplane health --json succeeds
  • Run edgeplane run <runtime> doctor --json for a full readiness report

What’s Next

Section titled “What’s Next”