OPCODE

Workflow orchestration engine for AI agents. Runs as a persistent SSE daemon — 1 server, N agents, 1 database. Workflows are JSON-defined DAGs executed level-by-level with automatic parallelism. Communication happens via 6 MCP tools over SSE (JSON-RPC). Includes a built-in web panel for multi-agent monitoring and management.

Token economy: define a template once, execute it unlimited times for free (no re-reasoning). Reasoning nodes store decisions as events and never replay them.

Which Tool?

Prerequisites

• Go 1.25+ (required)
• CGO enabled (CGO_ENABLED=1) — required by embedded libSQL (go-libsql)
• C compiler — gcc or clang for CGO compilation

Installation

go install github.com/rendis/opcode/cmd/opcode@latest

Installs the opcode binary to $GOBIN (default: $GOPATH/bin). Ensure it’s in your PATH.

Running

OPCODE runs as a persistent SSE daemon. 1 server, N agents, 1 database. Agents connect via HTTP.

Configuration

Data directory: ~/.opcode/ (DB, settings, pidfile). Created automatically.

First-time setup (installs config and starts daemon):

opcode install --listen-addr :4100 --vault-key "my-passphrase"

--vault-key is memory-only (not persisted). For production, set OPCODE_VAULT_KEY env var.

Writes ~/.opcode/settings.json, downloads mermaid-ascii to ~/.opcode/bin/ for enhanced ASCII diagrams, and starts the daemon. All settings overridable via env vars (OPCODE_LISTEN_ADDR, OPCODE_DB_PATH, etc.).

Security: Never put OPCODE_VAULT_KEY in settings.json. Use env vars or your platform’s secrets manager. The passphrase derives the AES-256 encryption key via PBKDF2.

If the process stops, restart with:

OPCODE_VAULT_KEY="my-passphrase" opcode

install is only needed once. Subsequent restarts use opcode directly with the env var.

Subcommands

Hot-Reload via SIGHUP

Running opcode install with a server already running sends SIGHUP to reload configuration without restarting. You can also send it manually: kill -HUP $(cat ~/.opcode/opcode.pid).

Building with Version

make build          # embeds git tag/commit as version
./opcode version    # prints e.g. "v1.0.0" or "abc1234-dirty"

Without make, go build works normally (version = dev).

MCP Client Configuration

Connect to the running daemon via SSE URL:

{
  "mcpServers": {
    "opcode": {
      "url": "http://localhost:4100/sse"
    }
  }
}

Agent Identity

Each agent self-identifies via the agent_id parameter in tool calls. Opcode auto-registers unknown agents on first use. Choose a stable, unique ID per agent (e.g., "content-writer", "deploy-bot"). Use opcode.query with filter.agent_id to see only your workflows.

Startup Sequence

1. Writes pidfile to ~/.opcode/opcode.pid
2. Loads config from ~/.opcode/settings.json (env vars override)
3. Creates data directory, opens/creates libSQL database, runs migrations
4. Suspends orphaned active workflows (emits workflow_interrupted)
5. Initializes secret vault (if OPCODE_VAULT_KEY set)
6. Registers 24 built-in actions
7. Starts cron scheduler (recovers missed jobs)
8. Registers SIGHUP handler for config hot-reload
9. Begins listening for MCP JSON-RPC over SSE (+ web panel if panel enabled) on same port
10. Shuts down gracefully on SIGTERM/SIGINT (10s timeout), removes pidfile

Recovery

Workflows survive process restarts. On startup, opcode transitions orphaned active workflows to suspended and recovers missed cron jobs.

Find interrupted workflows:

opcode.query({ "resource": "workflows", "filter": { "status": "suspended" } })

Inspect via opcode.status, then resume or cancel with opcode.signal.

Security Model

Built-in actions respect ResourceLimits configured at startup:

Defaults are permissive (no path deny-lists, no network restrictions). For production:

• Set DenyPaths for sensitive directories (/etc/shadow, ~/.ssh)
• Set WritablePaths to constrain write scope
• Run the opcode process under a restricted OS user
• Use a network proxy/firewall for HTTP egress control
• Treat OPCODE_VAULT_KEY as root-equivalent for stored secrets

Crypto, assert, and workflow actions perform no I/O beyond the opcode database.

MCP Tools

opcode.define

Register a reusable workflow template. Version auto-increments (v1, v2, v3…).

Returns: { "name": "...", "version": "v1" }

opcode.run

Execute a workflow from a registered template.

Returns:

{
  "workflow_id": "uuid",
  "status": "completed | suspended | failed",
  "output": { ... },
  "started_at": "RFC3339",
  "completed_at": "RFC3339",
  "steps": {
    "step-id": { "step_id": "...", "status": "completed", "output": {...}, "duration_ms": 42 }
  }
}

If status is "suspended", call opcode.status to see pending_decisions.

opcode.status

Get workflow execution status.

Returns:

{
  "workflow_id": "uuid",
  "status": "suspended",
  "steps": { "step-id": { "status": "...", "output": {...} } },
  "pending_decisions": [
    {
      "id": "uuid",
      "step_id": "reason-step",
      "context": { "prompt": "...", "data": {...} },
      "options": [ { "id": "approve", "description": "Proceed" } ],
      "timeout_at": "RFC3339",
      "fallback": "reject",
      "status": "pending"
    }
  ],
  "events": [ ... ]
}

Workflow statuses: pending, active, suspended, completed, failed, cancelled.

opcode.signal

Send a signal to a suspended workflow.

Payload by signal type:

Returns (decision): { "ok": true, "resumed": true, "status": "completed", ... } Returns (other): { "ok": true, "workflow_id": "...", "signal_type": "..." }

opcode.query

Query workflows, events, or templates.

Filter fields by resource:

Note: event queries require either event_type or workflow_id in filter.

Returns: { "<resource>": [...] } — results wrapped in object keyed by resource type.

opcode.diagram

Generate a visual DAG diagram from a template or running workflow.

* One of template_name or workflow_id required.

Use cases:

• template_name — preview DAG structure before execution
• workflow_id — visualize with live step status (completed, running, suspended, pending)
• format: "ascii" — CLI-friendly text output with box-drawing characters
• format: "mermaid" — markdown-embeddable flowchart syntax
• format: "image" — base64-encoded PNG for visual channels (Telegram, WhatsApp, Slack)

Returns: { "format": "ascii", "diagram": "..." } — diagram content as text (ascii/mermaid) or base64 PNG (image).

Web Panel

The daemon can serve a web management panel at the same port as MCP SSE (default http://localhost:4100). Enable with --panel flag or OPCODE_PANEL=true env var. Can be toggled at runtime via SIGHUP.

Live updates via SSE — dashboard and workflow detail pages auto-refresh on new events.

Workflow Definition

Durations use Go format: 500ms, 30s, 5m, 1h30m.

{
  "steps": [ ... ],
  "inputs": { "key": "value or ${{secrets.KEY}}" },
  "context": { "intent": "...", "notes": "..." },
  "timeout": "5m",
  "on_timeout": "fail | suspend | cancel",
  "on_complete": { /* step definition */ },
  "on_error": { /* step definition */ },
  "metadata": {}
}

Step Definition

{
  "id": "step-id",
  "type": "action | condition | loop | parallel | wait | reasoning",
  "action": "http.get",
  "params": { ... },
  "depends_on": ["other-step"],
  "condition": "CEL guard expression",
  "timeout": "30s",
  "retry": { "max": 3, "backoff": "exponential", "delay": "1s", "max_delay": "30s" },
  "on_error": { "strategy": "ignore | fail_workflow | fallback_step | retry", "fallback_step": "id" },
  "config": { /* type-specific */ }
}

type defaults to action. The config field varies by type. See workflow-schema.md for all config blocks.

Step Types

action (default)

Executes a registered action. Set action to the action name, params for input.

condition

Evaluates a CEL expression and branches.

{
  "id": "route",
  "type": "condition",
  "config": {
    "expression": "inputs.env",
    "branches": { "prod": [...], "staging": [...] },
    "default": [...]
  }
}

loop

Iterates over a collection or condition. Loop variables: ${{loop.item}}, ${{loop.index}}.

{
  "id": "process-items",
  "type": "loop",
  "config": {
    "mode": "for_each",
    "over": "[\"a\",\"b\",\"c\"]",
    "body": [
      {
        "id": "hash",
        "action": "crypto.hash",
        "params": { "data": "${{loop.item}}" }
      }
    ],
    "max_iter": 100
  }
}

Modes: for_each (iterate over), while (loop while condition true), until (loop until condition true).

parallel

Executes branches concurrently.

{
  "id": "fan-out",
  "type": "parallel",
  "config": {
    "mode": "all",
    "branches": [ [{ "id": "a", "action": "http.get", "params": {...} }], [{ "id": "b", "action": "http.get", "params": {...} }] ]
  }
}

Modes: all (wait for all branches), race (first branch wins).

wait

Delays execution or waits for a named signal.

{ "id": "pause", "type": "wait", "config": { "duration": "5s" } }

reasoning

Suspends workflow for agent decision. Empty options = free-form (any choice accepted).

{
  "id": "review",
  "type": "reasoning",
  "config": {
    "prompt_context": "Review data and decide",
    "options": [
      { "id": "approve", "description": "Proceed" },
      { "id": "reject", "description": "Stop" }
    ],
    "data_inject": { "analysis": "steps.analyze.output" },
    "timeout": "1h",
    "fallback": "reject",
    "target_agent": ""
  }
}

Variable Interpolation

Syntax: ${{namespace.path}}

Two-pass resolution: non-secrets first, then secrets via AES-256-GCM vault.

CEL gotcha: loop is a reserved word in CEL. Use iter.item / iter.index in CEL expressions. The ${{loop.item}} interpolation syntax is unaffected.

See expressions.md for CEL, GoJQ, Expr engine details.

Built-in Actions

Quick reference (most-used actions):

• http.get: url (req), headers, timeout, fail_on_error_status — output: { status_code, headers, body, duration_ms }
• shell.exec: command (req), args, stdin, timeout, env, workdir — output: { stdout, stderr, exit_code, killed }
• fs.read: path (req), encoding — output: { path, content, encoding, size }
• workflow.notify: message (req), data — output: { notified: true/false } — pushes real-time notification to agent via MCP SSE (best-effort)

See actions.md for full parameter specs of all 25 actions.

Scripting with shell.exec

shell.exec supports any language (Bash, Python, Node, Go, etc.). Scripts receive input via stdin and produce output via stdout. JSON stdout is auto-parsed — access fields directly with ${{steps.cmd.output.stdout.field}}.

Convention: stdin=JSON, stdout=JSON, stderr=errors, non-zero exit=failure. Use stdout_raw for unprocessed text.

See patterns.md for full templates.

Reasoning Node Lifecycle

1. Workflow reaches a reasoning step

2. Executor creates PendingDecision, emits decision_requested event

3. Workflow status becomes suspended

4. Agent calls opcode.status to see pending decision with context and options

5. Agent resolves via opcode.signal:

   {
     "workflow_id": "...",
     "signal_type": "decision",
     "step_id": "reason-step",
     "payload": { "choice": "approve" }
   }
   

6. Workflow auto-resumes after signal

7. If timeout expires: fallback option auto-selected, or step fails if no fallback

Common Patterns

See patterns.md for full JSON examples: linear pipeline, conditional branching, for-each loop, parallel fan-out, human-in-the-loop, error recovery, sub-workflows, and MCP lifecycle.

Error Handling

Backoff: none, linear, exponential, constant. Non-retryable errors (validation, permission, assertion) are never retried.

See error-handling.md for circuit breakers, timeout interactions, error codes.