Expand description
§apoc
Unrestricted process control and durable execution for LLM agents.
apoc (apocalypse) replaces shell-shaped process inspection, PID bookkeeping,
background-job glue, and one-off supervisors with one typed control plane. It
gives agents fresh process state, exact process identities, durable executions,
bounded concurrency, resource ownership, causal history, and JavaScript
composition through the same command graph.
It is built for workloads where independent operations run concurrently, long-lived work must survive the initiating call, and later agents need to inspect exact outcomes without reconstructing state from terminal transcripts.
Install · Quick start · Execution model · MCP · Security · Operations · Reference
§Core guarantees
| Capability | Contract |
|---|---|
| Process identity | Mutations target boot ID, PID, and nanosecond start time to prevent PID-reuse mistakes. |
| Durable execution | Accepted commands retain specifications, attempts, bounded logs, events, ownership, and terminal results. |
| Exact arguments | Direct argv is the default; shell parsing requires explicit --shell. |
| Replay safety | Caller-supplied idempotency keys prevent repeated operating-system mutations. |
| One command graph | CLI, MCP, and Code Mode share schemas, validation, history, and execution state. |
| Local-first operation | No account, telemetry service, or required remote control plane. |
§Status and scope
| Property | Current contract |
|---|---|
| Release | 0.9.1 |
| Platform | Supported: macOS |
| Minimum Rust version | 1.95 |
| Interfaces | CLI, MCP stdio, Code Mode JavaScript, and an embedded Rust library |
| Compatibility | SemVer releases with versioned durable schemas and pre-migration database backups |
| Release gates | rustfmt, Clippy with warnings denied, workspace tests, package contents, and publish dry-run on macOS CI |
| State | Local SQLite database, execution logs, and content-addressed artifacts |
| Authority | The operating-system permissions of the user who starts apoc |
| License | MIT |
The 0.x line is actively evolving. Breaking public-interface changes receive
a minor version bump; durable state changes use explicit schema migrations.
§Security and trust model
apoc is not a sandbox, policy engine, confirmation layer, or embedded model. It exposes destructive operations and their metadata directly, using the authority of the user who starts it. The calling agent remains responsible for selecting the correct target and action.
apoc can ask a decider you register before it launches a command. It ships no deciders and no rules; with none registered it asks nothing, records nothing, and refuses nothing. A decider guards against accidents, not adversaries: apoc has no privilege boundary, so an agent that can run commands can also remove a decider. See Ask a decider before commands run.
apoc has no telemetry, account service, update checker, or automatic network access. Network requests occur only when the user configures and invokes an HTTP, MCP, or OpenAPI provider.
§Composed Code Mode
Prefer native MCP arguments over shell-quoted JavaScript. A short call is enough:
{"code":"return await apoc.execution_command({executable:'cargo',arg:['check','--locked']});"}Local calls inherit the outer purpose and derive mutation keys automatically.
Optional outer purpose states the intent once. Optional idempotency_key
preserves child replay across new executions; without it, keys stay scoped to
one execution and its replay passes. Explicit nested values override defaults,
and external connector arguments remain unchanged.
Save lengthy source and use apoc code run @program.js --purpose 'Verify build' --idempotency-key build-v1 --timeout-ms 45000. Files are UTF-8 and resolve
relative to the caller directory. CLI mutations require a purpose and key;
framework discovery is purpose-free.
Commands judge exit zero by default. Add an expectation when success means
something else. Compose dependent calls with await, independent calls with
Promise.all, and return only the result the next decision needs.
See the operator skill for concise examples and references.
§Install
cargo install apoc --version 0.9.1 --locked
apoc skill install --purpose 'Install the apoc operator skill.' --idempotency-key skill/install-v1
apoc version --purpose 'Check the installed apoc version.' --format json
apoc skill status --purpose 'Check the apoc skill installation.' --format jsonapoc skill install writes the embedded operator contract to
~/.agents/skills/apoc and links the Codex and Claude skill roots to that
canonical copy. Run it again after an upgrade. A successful status reports
"ready": true.
Each crates.io release contains the complete MIT-licensed source. Development happens in a private repository; the crates.io package and docs.rs source view are the public source distribution.
§Quick start
Run one exact-argv command and receive its durable result:
apoc execution command /usr/bin/printf \
--purpose 'verify the apoc installation' \
--idempotency-key quick-start/printf-v1 \
--format json \
-- '%s\n' 'hello from apoc'The default response contains only the execution ID and verdict:
{"id":"EXECUTION_ID","outcome":"passed"}Retained logs and the complete record require an explicit addressed read.
Use the returned execution ID to inspect or control the work later:
apoc execution get EXECUTION_ID --purpose 'Check the execution state.' --format json
apoc execution tree EXECUTION_ID --purpose 'Inspect the managed process tree.' --format json
apoc execution logs EXECUTION_ID --tail-bytes 65536 --purpose 'Read the latest execution logs.' --format json
apoc execution wait EXECUTION_ID --timeout-ms 30000 --purpose 'Wait for the execution to finish.' --format json
apoc execution cancel EXECUTION_ID --timeout-ms 2000 --idempotency-key execution/cancel-1 --purpose 'Cancel the active execution.' --format jsonexecution wait --timeout-ms is a client wait boundary. If the execution is
still active at that boundary, it returns the current pending verdict without
canceling or failing the execution.
Limit a native execution and every process it owns with one family budget:
apoc code run '
return await apoc.execution_command({
executable: "cargo",
arg: ["test", "--workspace"],
cwd: "/absolute/project",
memory_limit_mb: 2048,
cpu_percent: 200,
cpu_time_ms: 600000,
child_processes: 64,
timeout_ms: 900000,
idempotency_key: "tests/resource-budget-v1",
purpose: "Run the workspace tests inside a bounded native execution family."
});
' --purpose 'Run the workspace tests inside a bounded native execution family.' \
--idempotency-key tests/resource-budget-outer-v1 --format jsonmemory_limit_mb caps combined resident memory. cpu_percent caps the sampled
combined CPU rate, where 100 percent equals one logical CPU. cpu_time_ms caps
accumulated CPU time. apoc samples these native ceilings every 100 milliseconds,
persists the measured breach, and recursively cancels the execution graph. They
are cancellation ceilings, not kernel reservations. Use built-in isolated
execution with memory_mb, cpu_count, and pids_max when the command needs
hard VM resource allocation.
Run the same exact-argv command in apoc’s built-in macOS VZ guest with
--isolated. This path does not require provider registration. local resolves
the packaged or development VM bundle; an absolute bundle path and a canonical
sha256:<digest> image reference are also accepted.
Rust INCURS owns this command surface and the native apoc-macos-vz provider.
apoc keeps the durable execution identity, retry policy, verified image,
exports, redacted logs, controls, and recovery. The provider owns
Virtualization.framework configuration, pooling, snapshot attempts, and the
guest transport. Snapshot restore failures are recorded against the compatible
image fingerprint and fall back to a cold warmed VM instead of claiming a
snapshot exists.
apoc execution command /bin/uname \
--isolated \
--image local \
--workspace-mode none \
--idempotency-key quick-start-isolated-v1 \
--purpose 'Read the isolated guest kernel identity.' \
--format json \
-- -aDeclare files or directories to import after the guest command with --export.
Each matching export becomes a verified, content-addressed execution artifact.
The source is an absolute guest path, the destination is a unique artifact name,
and when is success, failure, or always.
apoc execution command /bin/sh \
--isolated \
--workspace-mode none \
--export '{"source":"/tmp/result","destination":"result","when":"success"}' \
--artifact-bytes 1048576 \
--idempotency-key isolated-export-v1 \
--verbosity trace \
--purpose 'Create and retain one isolated result.' \
--format json \
-- -c 'printf result > /tmp/result'
apoc code artifact EXECUTION_ID ARTIFACT_ID \
--purpose 'Read the retained isolated result.' \
--format jsonapoc verifies the guest SHA-256 and the total artifact byte budget before it
stores anything. It rejects incomplete streams, undeclared indexes, duplicate
destinations, missing condition-matching exports, and exports emitted for the
wrong terminal condition. The stored envelope uses application/x-tar; its
archive contains the exported value at value.
An isolated execution remains controllable through its apoc execution ID. Start the command, then send UTF-8 input, a named signal, or cancellation through the same public lifecycle used for native commands.
apoc execution start /usr/bin/head \
--isolated \
--workspace-mode none \
--guest-cwd /tmp \
--idempotency-key isolated-input-v1 \
--verbosity trace \
--purpose 'Start an isolated input consumer.' \
--format json \
-- -c 5
apoc execution input EXECUTION_ID hello \
--idempotency-key isolated-head/input-1 \
--purpose 'Write five bytes to the isolated input consumer.' \
--format json
apoc execution signal EXECUTION_ID TERM \
--idempotency-key isolated-head/term-1 \
--purpose 'Terminate the isolated execution.' \
--format json
apoc execution cancel EXECUTION_ID \
--idempotency-key isolated-head/cancel-1 \
--purpose 'Cancel the isolated execution and release its VM.' \
--format jsonapoc claims each input, signal, or cancel idempotency key before dispatch and records the result afterward. An exact retry returns the original result, a changed request conflicts, and an ambiguous prior dispatch is not repeated. It rejects new controls before provider acceptance and after terminal state. Terminal publication guarantees the active control handle is gone and the VM slot can return to the pool.
Pass --pty to allocate a controlling terminal inside the isolated guest.
Standard output and standard error share the stdout event stream, and
execution input writes through the PTY master. The initial terminal size is
80 columns by 24 rows.
apoc execution command /bin/sh \
--isolated \
--workspace-mode none \
--pty \
--idempotency-key isolated-shell/tty-1 \
--purpose 'Verify the isolated controlling terminal.' \
--format json \
-- -c 'test -t 0 && test -t 1 && test -t 2 && printf tty-ready'Isolated commands accept secret environment references without storing their
resolved values. apoc resolves each value only while constructing the provider
request, withholds logs while redaction is pending, and replaces every complete
value with [REDACTED] before publishing terminal state. Recovery removes
potentially unsafe logs if a required value can no longer be resolved.
apoc execution command /bin/sh \
--isolated \
--workspace-mode none \
--secret-env TOKEN=env:DEPLOY_TOKEN \
--idempotency-key isolated-secret/check-1 \
--purpose 'Verify isolated secret transport and redaction.' \
--format json \
-- -c 'printf "%s" "$TOKEN"'--max-attempts also applies to isolated executions. apoc retains one public
execution ID, assigns deterministic provider request IDs ending in
:attempt:N, records every failed attempt, appends output in attempt order,
and makes cancellation wake retry backoff immediately. Live input and signals
are unavailable between attempts until the next provider identity is accepted.
§Choose the smallest execution surface
| Work | Preferred surface |
|---|---|
| One process query or mutation | apoc process ... |
| One managed command | apoc execution command or start |
| One isolated macOS VZ command | apoc execution command --isolated or start --isolated |
| Live processes for a known execution | apoc execution tree EXECUTION_ID |
| Repeat a command or typed apoc operation until an outcome | apoc poll run or start |
| Known independent commands | apoc execution batch |
| A native stdout pipeline | apoc execution pipeline |
| Heterogeneous concurrent tools | apoc code run |
| Agent-host integration | apoc --mcp |
| External MCP, OpenAPI, or macOS action | apoc provider ... and apoc action ... |
| Prior apoc use in this worktree | apoc history ... |
Every surface resolves through the same typed graph and durable lifecycle:
CLI MCP Code Mode
| | |
+----------+-------------+
|
typed command graph
|
per-user daemon
/ | \
executions events ownership
|
macOS processes, isolated VZ, and providersAll commands support TOON, JSON, YAML, Markdown, and JSONL output. Use
--schema for one command’s JSON Schema and --llms for the compact
LLM-readable command manifest. Use --filter-output when an agent needs only a
few fields from a CLI response. Code Mode programs should return a compact
synthesis instead of complete nested execution envelopes.
§Process discovery and control
apoc resolves a selector from a fresh native snapshot before every mutation.
The durable identity is BOOT_ID:PID@STARTED_AT_NS, so PID reuse cannot redirect
an operation to a different process.
When an execution ID is available, inspect its processes with execution tree.
It recursively follows owned child executions and verifies every captured root by
boot ID, PID, and nanosecond start time before returning a fresh tree. Its
state is pending, active, terminal, or inconsistent; terminal
executions return an explicit terminal result with an empty processes array.
Do not extract a PID or PGID from execution get and pass it to process tree.
apoc execution tree EXECUTION_ID --purpose 'Inspect the managed process tree.' --format json
apoc process list --selector match:node --sort memory --limit 20 --purpose 'List relevant Node processes.'
apoc process select port:5173/tcp --purpose 'Select the development server process.'
apoc process tree name:vite --purpose 'Inspect the Vite process tree.'
apoc process files pid:4242 --purpose 'List files opened by the process.'
apoc process sockets --listening --protocol tcp --purpose 'List listening TCP sockets.'
apoc process probe pid:4242 --purpose 'Check whether the process still exists.'
apoc process sample --selector match:node --count 5 --interval-ms 250 --purpose 'Sample resource use for Node processes.'Selectors are pid:, name:, match: regular expressions, pgid:, port:
with optional /tcp or /udp, and all. A bare integer is a PID.
Structured queries combine process fields, regular expressions, socket ownership, and recorded apoc ownership:
apoc process query '{
"all":[{"command_regex":"node|bun"}],
"any":[{"port":5173},{"actor":"release-agent"}],
"not":[{"name":"Code Helper"}],
"sort":"memory",
"limit":20
}' --purpose 'Find high-memory Node processes.'The causal journal answers relationship questions from recorded evidence:
apoc process why pid:4242 --purpose 'Explain why apoc knows this process.'
apoc process impact pid:4242 --purpose 'Assess the impact of controlling the process.'
apoc process owner pid:4242 --purpose 'Identify the process owner.'
apoc process related pid:4242 --purpose 'Find related process records.'
apoc process changed pid:4242 --purpose 'Read recorded changes for the process.'
apoc process context pid:4242 --events 50 --purpose 'Read the durable process context.'Process mutations accept caller-supplied idempotency keys. Repeating the same
normalized request and key returns the original receipt without another
operating-system call. Empty selections fail unless --allow-empty is explicit.
These commands can stop or suspend host processes. Resolve and inspect the selector before mutating a target when its identity is not already known.
apoc process signal name:vite TERM --purpose 'Terminate the Vite process cleanly.' --idempotency-key deploy-91/term
apoc process stop port:5173/tcp --timeout-ms 2000 --force \
--purpose 'Stop the process holding the development port.' \
--idempotency-key deploy-91/free-port
apoc process pause pgid:4242 --purpose 'Pause the process group for debugging.' --idempotency-key debug-7/pause
apoc process resume pgid:4242 --purpose 'Resume the paused process group.' --idempotency-key debug-7/resume§Durable execution contract
execution is the public lifecycle abstraction. Direct argv is the default.
Place apoc options before the first literal --, then pass each exact child
argv value after it. That first separator belongs to apoc; every later --
belongs to the child. Structured MCP and Code Mode calls use the same arg
array. If apoc reports an unknown child flag, do not retry with --arg; move
apoc options before -- and the complete child argv after it. Use --shell
only when the program intentionally requires zsh parsing.
apoc execution start /usr/bin/python3 \
--name docs \
--purpose 'serve documentation for review' \
--idempotency-key docs/server-v1 \
--max-attempts 3 \
--retry-backoff-ms 500 \
--timeout-ms 300000 \
-- -m http.server 8000An execution records its versioned specification, working directory, repository and worktree state, attempts, exact process identities, output paths, parent, session, lease, progress time, and terminal result.
- An omitted working directory inherits the caller’s current directory through the CLI, MCP, and Code Mode.
- A relative
--cwdresolves from that directory. apoc validates and canonicalizes it before accepting the execution. command,batch, andpipelinereturn a verdict, or{ execution, replayed, logs }at--verbosity trace.- The CLI exit status matches the managed result while structured stdout remains available to the caller.
- Inline stdout and stderr are bounded 32 KiB tails with explicit truncation
flags. Full logs remain available through
execution logs. - Launch failures, nonzero exits, timeouts, and cancellations are terminal execution results after acceptance. They are not transport failures.
- A progress timeout advances when retained stdout or stderr grows or the
execution lifecycle advances. If it stalls, apoc preserves
last_progress_atand records both that timestamp andstalled_atin the terminal result. - Reusing an idempotency key for a different normalized request fails before launching work.
Use execution list --error-code CODE to find executions by their canonical
terminal cause, including launch failures, timeouts, stalls, and cancellations.
§Opt-in execution telemetry
Execution resource telemetry is off by default. Add --telemetry to execution command, start,
batch, pipeline, either poll target, or code run/start when a task needs
measurements. The default interval is 250 ms and the default retained raw-data
cap is 64 MiB; override them with --telemetry-interval-ms and
--telemetry-max-bytes.
apoc execution command cargo \
--telemetry \
--purpose 'Measure the package test execution.' \
--idempotency-key tests/telemetry-v1 \
--verbosity trace \
-- test -p package-nameOne capture follows the selected execution, every recursively owned apoc child execution, and every live OS descendant of their stable process identities. A sample contains wall time, current and accumulated CPU, resident and virtual memory, disk reads and writes, and process count. It excludes command lines, environment values, and log contents. When the byte cap is reached, apoc removes the oldest complete samples and preserves stable sequence numbers for the newest ones.
Attach to work that is already running with a keyed mutation. get returns a
compact newest-and-peaks summary unless the caller addresses raw NDJSON lines:
apoc execution telemetry start EXECUTION_ID \
--idempotency-key incident-42/telemetry-start \
--purpose 'Attach telemetry to the active execution.' --format json
apoc execution telemetry get EXECUTION_ID --grep '"memory_bytes"' --context 1 \
--purpose 'Find memory measurements before expanding a range.' --format json
apoc execution telemetry get EXECUTION_ID --lines 40-80 \
--purpose 'Read the selected telemetry sequence range.' --format json
apoc execution telemetry stop EXECUTION_ID \
--idempotency-key incident-42/telemetry-stop \
--purpose 'Stop sampling while preserving retained measurements.' --format jsonActive captures resume after daemon recovery. A telemetry collection or storage
fault marks only the capture degraded; it never changes the execution verdict.
With telemetry disabled, apoc starts no sampler and writes no capture or sample
records.
Secret environment values use NAME=env:VARIABLE. apoc stores the reference
and resolves the value only when the process launches. Literal environment
values are part of the durable execution specification and are stored locally.
§Local error tracking
apoc automatically records local error metadata in
<apoc state directory>/telemetry/errors.jsonl. On macOS the default is
~/Library/Application Support/apoc/telemetry/errors.jsonl; APOC_HOME selects
a different state directory. Nothing is uploaded.
The log covers CLI and parser failures, MCP tool errors, typed-command failures, daemon RPC faults, failed execution transitions, Code Mode errors, history storage failures, and Rust panics. Records contain a timestamp, build and execution-schema versions, OS and architecture, PID, operation, error code, available invocation and execution IDs, and a SHA-256 error fingerprint. Panic records also identify the source location. Arguments, environment values, purpose text, output logs, and raw error messages are excluded. Use the IDs to inspect existing durable history and execution records when the complete diagnostic is needed.
Each log retains at most 1 MiB and rotates to errors.previous.jsonl, keeping
at most 2 MiB across the pair. The directory is private (0700), and files are
0600. Recording is best effort: unavailable storage or a contended nonblocking
lock skips the event without changing a command’s output, exit status, or
verdict. Set APOC_ERROR_TELEMETRY=off before launching apoc to disable it;
restart an existing daemon for that daemon to inherit the setting.
This error log is separate from the opt-in execution resource sampler described above. Successful executions and allowed nonzero exits do not generate execution-failure events.
§Debug a managed Node execution
Use debugger run to launch Node as a durable execution and return its linked
debugger session in one typed call. apoc adds --inspect-brk=HOST:PORT when the
Node argv does not already declare an inspector option. Every other argument
remains exact argv.
apoc code run '
return await apoc.debugger_run({
executable: "node",
arg: ["app.js"],
port: 9231,
id: "s0",
purpose: "Launch Node and open its debugger.",
idempotency_key: "debug/app/run-v1"
});
' --purpose 'Launch Node and open its debugger.' \
--idempotency-key debug/app/run-outer-v1 --format jsonUse debugger open when the target already exists. debugger targets returns
Node and page target identities, titles, URLs, and WebSocket endpoints.
Debugger source locations are one-based. Breakpoints use a source suffix and
survive script reloads because apoc sends Debugger.setBreakpointByUrl.
apoc code run '
return await apoc.debugger_breakpoint_set({
id: "s0", file: "src/app.js", line: 42,
purpose: "Break before the failing statement.",
idempotency_key: "debug/app/break-42-v1"
});
' --purpose 'Break before the failing statement.' \
--idempotency-key debug/app/break-outer-v1 --format json
apoc code run 'return await apoc.debugger_status({id:"s0", purpose:"Read the debugger state."});' \
--idempotency-key debug/app/status-outer-v1 \
--purpose 'Read the debugger state.' --format json
apoc code run 'return await apoc.debugger_stack({id:"s0", purpose:"Read the paused stack."});' \
--idempotency-key debug/app/stack-outer-v1 \
--purpose 'Read the paused stack.' --format json
apoc code run 'return await apoc.debugger_evaluate({id:"s0", expression:"value", idempotency_key:"debug/app/eval-1", purpose:"Inspect the paused value."});' \
--idempotency-key debug/app/eval-outer-v1 \
--purpose 'Inspect the paused value.' --format json
apoc code run 'return await apoc.debugger_step({id:"s0", kind:"over", idempotency_key:"debug/app/step-1", purpose:"Step over once."});' \
--idempotency-key debug/app/step-outer-v1 \
--purpose 'Step over once.' --format jsonstep accepts over, into, or out. continue waits for the next pause,
exit, or disconnect; resume returns the observed running state. Source,
scopes, variables, this, properties, prototypes, scripts, listeners, console,
exceptions, health, Chrome DevTools Protocol (CDP) trace, and durable event reads are separate typed
commands. Evaluation retains object IDs, unserializable values, descriptions,
and exception details. If a CLI object ID begins with -, put the positional
arguments after the first literal --.
Every debugger mutation requires an idempotency key. Sessions, actor-scoped
selection, breakpoints, hit counts, events, diagnostics, and replay receipts
are durable. On daemon restart, apoc reconnects an open Node session and
restores its breakpoints. debugger restart cancels and relaunches the linked
execution while preserving the session and breakpoint identities. debugger close disconnects CDP but does not cancel the linked execution; cancel that
execution explicitly when the program should stop.
§Capture taps and expression watches
A tap is a conditional CDP logpoint that captures one JavaScript expression
without pausing the target. The source line is one-based. By default, apoc
escapes the source suffix into a URL regular expression; url_regex overrides
that match for bundles and generated scripts.
apoc code run '
return await apoc.debugger_tap_add({
id: "s0", file: "src/cart.js", line: 42,
expression: "cart.total",
idempotency_key: "debug/cart/tap-total-v1",
purpose: "Capture the cart total without pausing."
});
' --purpose 'Capture the cart total without pausing.' \
--idempotency-key debug/cart/tap-total-outer-v1 --format jsondebugger_tap_list reports whether each tap resolved against a loaded script.
An unresolved tap remains pending and resolves when CDP reports its eventual
script location. debugger_tap_hits returns retained hits in chronological
order. Tap sentinel messages are routed into hit storage at the protocol-event
boundary and never enter user console, recorder after, timeline, or why
evidence. debugger_tap_remove disables the adapter breakpoint but preserves
its hit history.
An expression watch samples a running or paused JavaScript runtime every 250
milliseconds and stores only value or evaluation-error transitions. The target
is both its label and default expression; use expression when the label and
JavaScript differ. The access value records the evidence intent as read,
write, or rw.
apoc code run '
return await apoc.debugger_watch_add({
id: "s0", target: "cart total", expression: "cart.total",
access: "write",
idempotency_key: "debug/cart/watch-total-v1",
purpose: "Retain cart total changes."
});
' --purpose 'Retain cart total changes.' \
--idempotency-key debug/cart/watch-total-outer-v1 --format jsondebugger_watch_list, debugger_watch_hits, and debugger_watch_remove read,
inspect, and disable watches. apoc retains the newest 1,000 hits per tap or
watch while preserving total observed hit counts. Enabled taps and watch
workers restore when an open debugger session reconnects or restarts. Every add
or remove requires an idempotency key.
§Control a browser page
Launch Chrome through execution start, discover its page target with
debugger targets, and attach it with debugger open --target-id. The session
view reports browser_cdp, the stable page target ID, and any linked execution.
The browser subgroup then uses that named durable session.
For headless automation, launch Chrome for Testing rather than branded Google
Chrome. Branded Chrome 153 quits --headless=new on its own about thirty
seconds after launch, with a clean exit and no message, which ends the debugger
session midway; the session error then reads Debugger connection closed: the connection failed: .... Chrome for Testing stays up. Install it with
npx @puppeteer/browsers install chrome@stable.
apoc code run '
const page = await apoc.debugger_browser_navigate({
id: "browser-main", action: "url", target: "http://127.0.0.1:3000",
timeout_ms: 30000,
idempotency_key: "browser/app/navigate-v1",
purpose: "Open the local application."
});
const button = await apoc.debugger_browser_dom({
id: "browser-main", selector: "button[type=submit]",
purpose: "Inspect the submit button."
});
return {page, button};
' --purpose 'Open and inspect the local application.' \
--idempotency-key browser/app/navigate-outer-v1 --format jsondebugger browser navigate supports URL, reload, back, and forward. click
and type dispatch trusted input; select updates the element and dispatches
input and change events. DOM, computed styles, cookies, local and session
storage, performance metrics, network requests and bodies, WebSocket frames,
and page lifecycle events are addressed reads.
debugger browser screenshot stores a content-addressed PNG artifact. It can
capture the viewport, full page, or one selector; optional viewport overrides
and forced hover, active, focus, or visited state are restored before
the command returns. Inline base64 PNG bytes require --inline.
Mocks, device emulation, throttling, and JavaScript and CSS coverage are durable browser-session state. Mocks restore after daemon restart. Every navigation, interaction, capture, mock, emulation, throttling, and coverage command requires an idempotency key.
§Record a browser session
Start a flight recording on an attached page session. apoc captures the current page immediately, captures later frame navigations, and resumes the capture worker when the daemon reconnects the session.
apoc code run '
return await apoc.debugger_recording_start({
id: "browser-main",
max_frames: 200,
max_bytes: 104857600,
idempotency_key: "record/app/start-v1",
purpose: "Start the browser flight recording."
});
' --purpose 'Start the browser flight recording.' \
--idempotency-key record/app/start-outer-v1 --format jsoncapture adds a reasoned manual frame. shoot is the deliberate-capture
variant. mark captures a frame and protects it with a named timeline mark.
captures and marks read one recording by its durable ID. replay restores
one retained capture URL and vertical scroll position. stop captures a final
frame and terminalizes the recording.
after captures current browser state and compares it with --at capture:ID
or --at mark:NAME; without --at, it uses the latest retained capture. The
durable result includes changed pixels and their bounding region, new console
entries, exceptions and failed requests, storage and computed-style changes,
new accessibility findings, performance changes, explicit probe warnings, and
a content-addressed self-contained HTML report. after-get reads one analysis
by ID, and afters lists analyses for a recording.
timeline joins captures, marks, console errors, exceptions, network failures,
after diffs, debugger events, invocation purposes, workspace commit and dirty
digests, executions, and correlated apoc causal events by epoch millisecond. It
returns bounded structured items and a content-addressed, self-contained HTML
filmstrip. Timeline trimming retains every mark, error, exception, and diff and
at least the newest item of every joined evidence kind. The report mutation
requires an idempotency key.
why selects the latest recorded error or exception, optionally restricted by
a case-insensitive substring, then ranks edits with explicit causal path
evidence, diffs, executions, and causal events inside a configurable lookback
window. Stack-file matches receive a deterministic boost. The result includes
the nearest mark, invocation purpose, commit, diff, and execution plus explicit
limitations when apoc did not record file-level edit or commit evidence.
The first, latest, and marked captures are protected from count and logical-byte
retention trimming. If those protected frames exceed a configured bound, status
reports retention_overflow instead of claiming that apoc discarded evidence.
Every recorder mutation requires an idempotency key.
§Record and replay a browser flow
A flow records user actions while a browser flight recording is running. It preserves a stable selector and structural fallback for clicks, changed inputs, and selected key presses, plus scroll positions and top-level navigations. An active flow resumes after the daemon reconnects its browser session.
apoc code run '
const flow = await apoc.debugger_flow_record({
id: "browser-main",
name: "checkout",
idempotency_key: "flow/checkout/record-v1",
purpose: "Record the checkout browser flow."
});
return flow;
' --purpose 'Record the checkout browser flow.' \
--idempotency-key flow/checkout/record-outer-v1 --format jsonPerform the browser actions, then call debugger_flow_stop. debugger_flow_run
opens the recorded start URL and replays the ordered steps. Before each element
action, it waits until the primary selector or structural fallback is visible
and hit-testable. Every attempted step stores a browser capture. New console
errors or exceptions fail that step and skip the remaining steps. Starting with
the second run, each step reports its screenshot difference from the matching
step in the preceding run.
debugger_flow_list returns compact durable flow records.
debugger_flow_show returns one named flow with its ordered steps and prior run
evidence. Record, stop, and run are mutations and require idempotency keys. A
flow remains tied to its browser session and the active flight recording that
owns its captures.
§Preserve and replay a debugger evidence trace
An evidence trace binds a named interval to an existing debugger session and its apoc-owned execution. If a browser flight recording is active when the trace starts, the trace also binds that recording. Starting a trace does not launch or own another process.
apoc code run '
return await apoc.trace_start({
id: "s0",
name: "checkout failure",
idempotency_key: "trace/checkout/start-v1",
purpose: "Start checkout failure evidence."
});
' --purpose 'Start checkout failure evidence.' \
--idempotency-key trace/checkout/start-outer-v1 --format jsontrace_stop closes the interval. trace_show joins debugger events, recording
captures and marks, after analyses, tap hits, watch transitions, and flow steps
into one bounded chronological timeline. trace_list returns compact durable
trace records.
trace_use selects a trace for the invoking actor. trace_replay selects the
latest item or an explicit KIND:ID anchor and restores a browser capture when
that item is replayable. trace_cursor reads the current anchor. trace_move
moves backward or forward through the timeline, optionally filtered by kind;
trace_jump moves to the previous or next item of a required kind. Unknown and
malformed anchors fail instead of silently selecting different evidence.
trace_export writes a versioned JSON bundle into apoc’s content-addressed
artifact store. trace_import validates a bundle from an explicit path,
preserves its trace identity and items, marks it imported, and stores its exact
bytes in the receiving artifact store. trace_gc keeps the requested newest
terminal traces plus every active recording trace. All trace state mutations,
including cursor movement, require idempotency keys.
§Record and replay an rr trace
rr_record launches rr as a durable apoc execution and passes the target as
exact argv. It defaults to the built-in isolated VZ backend on macOS and the
native backend elsewhere. Select either path explicitly with backend: "isolated"
or backend: "native"; isolated calls accept image: "local", an absolute
bundle path, or a canonical image digest. apoc owns the recording execution,
logs, lease, terminal verdict, export artifact, and resulting trace identity.
The local macOS image pins the software-counter rr fork at Git revision
c93b27695e2bed5ceec7770a568379452cbf55c5. The bundle verifier exposes that
revision as build.rr_software_counters_revision. Isolated recording uses rr’s
-W -n software-counter mode because Apple Silicon VMs do not expose the
hardware performance counters required by upstream rr.
apoc code run '
return await apoc.rr_record({
executable: "./app",
arg: ["--fixture", "failing.json"],
name: "native-crash",
backend: "isolated",
image: "local",
idempotency_key: "rr/native-crash/record-v1",
purpose: "Record the native crash with rr."
});
' --purpose 'Record the native crash with rr.' \
--idempotency-key rr/native-crash/record-outer-v1 --format jsonThe CLI equivalent places apoc options before the first literal separator and the exact target argv after it:
apoc rr record --name native-crash \
--backend isolated --image local \
--idempotency-key rr/native-crash/record-v1 \
--purpose 'Record the native crash with rr.' \
-- ./app --fixture failing.jsonAfter a successful isolated recording, the provider exports the workspace-bound trace as a digest-verified execution artifact. apoc copies it into the debugger CAS, materializes a sandbox-readable replay copy, and removes the uniquely named temporary workspace directory. Native recording uses the same final artifact and materialized trace contract. apoc does not infer success from a directory alone: if the managed execution reaches no successful verdict, the trace fails and no partial directory is promoted as a replay artifact.
rr_replay starts interactive rr replay as a durable PTY execution. Use its
execution ID with execution_attach, execution_input, execution_signal, and
execution_cancel; replay does not introduce a second lifecycle. Event, process
ID, and end-of-trace selection map to rr -g, -p, and -e. rr_ps runs rr
process inspection as a one-shot durable execution and returns its bounded
logs.
rr_import accepts an explicit rr trace directory without requiring rr to be
installed on the importing host. It archives without following symlinks,
validates extraction through the tar reader, normalizes replay permissions, and
stores both the CAS artifact and an apoc-owned materialized directory. rr_list
and rr_show return the
durable trace, execution, replay, artifact, failure, and timestamp links. Only
rr-backed traces claim instruction-level replay; debugger evidence traces do
not.
§Every call is an assertion
Agent context is the scarcest resource in an execution loop, so an execution answers with a verdict and nothing else. Silence is safe because the caller declares what a correct result looks like before the command runs.
apoc execution command npm \
--expect-stdout-regex 'All tests passed' \
--purpose 'Verify the worker suite passes before touching the API.' \
--idempotency-key tests/worker-suite-v1 \
-- test{"id": "01a00c9e-46c6-7b20-b68b-951987567f62", "outcome": "failed"}That is the entire response, for a success and a failure alike. outcome uses
the JUnit and TAP vocabulary:
outcome | Meaning |
|---|---|
passed | Exited zero and any declared expectation held |
failed | The assertion did not hold: a nonzero exit, or a missed expectation |
error | A fault reached no verdict: launch failure, stall, or cancellation |
skipped | Declared but never launched |
pending | Durably owned and not yet terminal |
- Expectations are the predicates a poll already evaluates:
--expect-exit-code,--expect-stdout-regex,--expect-stderr-regex,--expect-json-pointerwith--expect-json-equals, and--expect-js. A poll evaluates one repeatedly; a command evaluates it once. - The CLI exit status mirrors the verdict, so a shell caller needs no payload at all. A missed expectation exits nonzero even when the program exited zero.
- The expectation is stored in the durable spec, so invocation history records what each call asserted, not merely what it ran.
- A batch or pipeline has no single output to assert against, so every declared
command carries its own
expect. A child whose assertion did not hold fails that child and its parent, even when the program exited zero.
apoc execution batch --max-parallel 2 \
--purpose 'Assert both suites before merging.' \
--idempotency-key verify/assert-suites-v1 \
--commands '[
{"id":"unit","argv":["npm","test"],
"expect":{"kind":"stdout_regex","pattern":"0 failing"}},
{"id":"types","argv":["npx","tsc","--noEmit"],
"expect":{"kind":"exit_code","codes":[0]}}
]'§Reveal output progressively
Output is never returned unless it is asked for. Search the durable log, then expand around what you find:
apoc execution logs EXECUTION_ID --grep 'AssertionError' --context 2 \
--purpose 'Locate the failing assertion.' --format json
apoc execution logs EXECUTION_ID --lines 340-420 \
--purpose 'Read the failure in context.' --format jsonMatching runs inside the daemon, so a 500 KB log is never shipped to a caller
that wants one line. Every slice reports total_matches, stdout_lines, and
stderr_lines, so a caller always knows how much it has not read.
§Verbosity
--verbosity off|error|warn|info|debug|trace, following syslog and tracing.
The default is error, the verdict above. -v reaches info (status, exit
code, withheld sizes, follow-up reads) and -vv reaches debug (bounded log
tails); each of those only adds to the level below it. -q lowers the level, and
off returns no payload at all.
trace is the exception to that ladder: it answers with the complete durable
record rather than the verdict envelope, so a typed consumer addresses the record
by the JSON Pointer it already uses. It still carries outcome, so no level
costs you the verdict.
APOC_VERBOSITY sets a session default and reaches nested Code Mode calls
through the invoking process. --view outcome|full and APOC_VIEW remain as
deprecated aliases, each keeping the contract it named: outcome is the
collapsed verdict, full is the complete record.
execution logs, attach, tree, and poll iterations always return their own
detail because they are the drill-down. Poll conditions and recipe output
validation always evaluate the complete record, so their pointers, regexes, and
schemas address every field.
§Poll commands and typed apoc operations
Use poll run when one observation must be repeated until it matches or reaches
a bound. Use poll start to return the durable parent execution immediately.
Both forms use the existing execution get, wait, and cancel lifecycle.
apoc poll run command curl \
--interval-mode fixed-delay \
--interval-ms 1000 \
--until-stdout-regex '"status":"ready"' \
--duration-ms 300000 \
--purpose 'Wait for the local health endpoint to report ready.' \
--format json \
-- http://localhost:3000/healthPoll options are named arguments and have no ordering requirement before --.
The separator preserves exact command argv. Interval behavior uses these request
arguments; it does not use interval subcommands.
--interval-mode | Arguments | Behavior |
|---|---|---|
fixed-delay | --interval-ms | Wait after each unmatched observation. |
backoff | --initial-interval-ms, --multiplier, --max-interval-ms | Increase the delay to the cap. |
fixed-rate | --interval-ms | Use acceptance-based ticks, skip missed ticks, and never overlap. |
Conditions include repeated --until-exit-code, stdout or stderr regex,
--until-json-pointer with --until-json-equals, and a pure boolean
--until-js expression over observation. Select one condition family. A poll
without a condition must include --max-iterations or --duration-ms and
completes as bounded sampling. A condition that reaches a bound fails with
POLL_CONDITION_NOT_MET.
Poll the shared typed graph with apoc as the target. This does not spawn a
nested apoc CLI process:
apoc poll start apoc process.ports \
--arguments '{"port":3000}' \
--until-js 'observation.result.length > 0' \
--interval-mode fixed-rate \
--interval-ms 5000 \
--duration-ms 600000 \
--purpose 'Wait for a process to own port 3000.' \
--format jsonThe parent result stays compact. Expand only the evidence needed for diagnosis:
apoc poll iterations POLL_ID --limit 20 --purpose 'List recent poll observations.' --format json
apoc poll iteration POLL_ID ITERATION_ID --purpose 'Read one poll observation.' --format json
apoc execution logs CHILD_EXECUTION_ID --tail-bytes 65536 --purpose 'Read the command iteration logs.' --format json§Run independent commands concurrently
Use one batch when the agent already knows the independent commands. apoc bounds
concurrency, records each child, and returns a compact failure-oriented parent.
max_parallel defaults to the logical CPU count and is limited to 256.
{
"commands": [
{ "id": "unit", "argv": ["cargo", "test", "--lib"] },
{ "id": "types", "argv": ["cargo", "check", "--all-targets"] },
{ "id": "format", "argv": ["cargo", "fmt", "--", "--check"] }
],
"max_parallel": 3,
"fail_fast": false
}apoc execution batch \
--commands '[{"id":"unit","argv":["cargo","test","--lib"]},{"id":"types","argv":["cargo","check","--all-targets"]}]' \
--purpose 'verify the worktree concurrently' \
--idempotency-key verify-91/batch \
--format jsonCLI callers may pass --commands once with a JSON array, or repeat it with one
JSON command object per occurrence. Use --file commands.json for larger or
reusable definitions. MCP and Code Mode pass the structured array directly.
Use a pipeline only when stdout must flow between stages. apoc creates native pipes, starts every stage before waiting, keeps each child’s stderr separate, captures final stdout on the parent, and enables pipefail by default.
[
{ "id": "produce", "argv": ["/usr/bin/printf", "apocalypse"] },
{ "id": "uppercase", "argv": ["/usr/bin/tr", "[:lower:]", "[:upper:]"] }
]apoc execution pipeline \
--commands '[{"id":"produce","argv":["/usr/bin/printf","apocalypse"]},{"id":"uppercase","argv":["/usr/bin/tr","[:lower:]","[:upper:]"]}]' \
--purpose 'Uppercase the generated release text.' \
--idempotency-key release-91/pipeline \
--format json§Compose heterogeneous work in Code Mode
Code Mode runs generated JavaScript in isolated QuickJS actors. The worker pool
defaults to min(logical CPUs, 8); set APOC_CODE_WORKERS to override it.
Separate programs use separate actors, and one program can issue independent
host calls concurrently with Promise.all.
Use the typed apoc.wait({ ms, purpose }) host call for a short delay when no
observable poll condition exists. It is capped at 60,000 milliseconds and does
not start a managed process; JavaScript setTimeout is not part of the QuickJS
contract.
apoc code run '
const [processes, sockets, tests] = await Promise.all([
apoc.process_list({ selector: "match:node", limit: 20, purpose: "List relevant Node processes." }),
apoc.process_sockets({ listening: true, protocol: "tcp", limit: 100, purpose: "List listening TCP sockets." }),
apoc.execution_command({
executable: "cargo",
arg: ["test"],
idempotency_key: "verify/current-worktree-v1",
purpose: "Verify the current worktree."
})
]);
return { processes, sockets, tests };
' --purpose 'Inspect processes and verify the current worktree.' \
--idempotency-key verify/current-worktree-outer-v1 --format jsonCode Mode persists source, immutable capabilities, ordered calls, replay state, result, events, and oversized artifacts. Provider mutations record intent before dispatch. Replay skips operations that already have a durable applied receipt.
Do not fan out shell strings that each invoke apoc through a host tool’s
Promise.all. Use one execution batch for known commands or one Code Mode
program with typed apoc.* calls. Avoid concatenating large source trees with
cat; use targeted searches, bounded reads, or a compact Code Mode synthesis.
After apoc accepts a managed execution, an unsuccessful terminal status resolves
normally inside JavaScript. Inspect execution.status and throw explicitly when
the surrounding program must fail.
apoc code start 'return await apoc.execution_list({ purpose: "List recent executions." });' \
--purpose 'Start an execution inventory query.' \
--idempotency-key inventory/outer-v1 --format json
apoc code get EXECUTION_ID --purpose 'Check the Code Mode execution.' --format json
apoc code cancel EXECUTION_ID --purpose 'Cancel the Code Mode execution.' --idempotency-key inventory/cancel-v1 --format json
apoc code artifact EXECUTION_ID ARTIFACT_ID --purpose 'Read the Code Mode artifact.' --format jsonIf an outer Code Mode execution ends before its accepted child work is summarized, recover the direct children without replaying the whole program:
apoc code run '
return await apoc.execution_list({
parent: "OUTER_EXECUTION_ID",
status: "completed",
limit: 100,
purpose: "Recover completed direct child executions."
});
' --purpose 'Recover direct child executions after an interrupted outer program.' \
--idempotency-key recovery/direct-children-outer-v1 --format jsonThe parent filter returns direct children only and composes with status and
cursor pagination. Use execution_get or execution_logs only for selected
IDs. Provider-action receipts are separate from command lifecycle records, so
receipt_get is not a command recovery API.
The local executor’s 300-second limit measures uninterrupted JavaScript. It is
renewed immediately before and after every host tool call, so connector and
managed-command wait time does not consume the runaway-loop budget. The outer
code run --timeout-ms value controls how long that client waits; accepted work
remains durable. A runaway loop fails with CODE_EXECUTION_TIMEOUT.
§Coordinate agents and resources
A session groups one agent’s executions under a heartbeat. Its root lease is
session/SESSION_ID. When the heartbeat expires, the daemon releases the lease,
cancels session-owned executions, and releases their reservations.
apoc session open --actor release-agent --ttl-ms 60000 --purpose 'Open a release-agent ownership session.' --idempotency-key release-session/open-v1
apoc session heartbeat SESSION_ID --ttl-ms 60000 --purpose 'Renew the release-agent session.' --idempotency-key release-session/heartbeat-v1
apoc reservation acquire port tcp/5173 session/SESSION_ID --purpose 'Reserve the development port.' --idempotency-key release-session/reserve-port-v1
apoc reservation acquire path /absolute/worktree session/SESSION_ID --purpose 'Reserve the release worktree.' --idempotency-key release-session/reserve-worktree-v1
apoc execution start cargo \
--owner session \
--session SESSION_ID \
--purpose 'Start tests owned by the release session.' \
--idempotency-key release-session/tests-v1 \
-- test
apoc session close SESSION_ID --timeout-ms 2000 --purpose 'Close the release-agent session.' --idempotency-key release-session/close-v1Reservations provide atomic apoc-local ownership for ports, paths, exact
processes, devices, and custom keys. Port reservations also report native socket
conflicts. reservation wait waits for up to 30 seconds.
§Extend the capability graph
Providers add Streamable HTTP MCP, supervised MCP stdio, or OpenAPI operations
to the same graph. Their names become Code Mode namespaces. Secret configuration
uses PROVIDER:REFERENCE and resolves only when a client connects or a child
starts.
From an unpacked apoc source package, build and sign the native Rust VZ provider and build the verified Linux arm64 VM bundle. Isolated execution resolves the provider internally and does not require registration.
build-provider.sh builds apoc-macos-vz, signs it, and verifies the
com.apple.security.virtualization entitlement. Run it whenever Cargo replaces
the provider binary; an unsigned provider cannot start a virtual machine.
extensions/macos-native/scripts/build-provider.sh
extensions/macos-native/scripts/build-vm-bundle.sh extensions/macos-native/.build/vm-bundle
apoc execution image import extensions/macos-native/.build/vm-bundle \
--idempotency-key image/import-v1 \
--purpose 'Import the verified isolated VM image.' \
--format json
apoc execution command /bin/echo \
--isolated \
--image sha256:IMPORTED_IMAGE_DIGEST \
--workspace-mode none \
--idempotency-key isolated-echo-v1 \
--purpose 'Run echo in the built-in VZ guest.' \
-- 'hello from VZ'
apoc execution image verify local \
--purpose 'Verify the configured isolated VM image.' \
--format json
apoc execution isolation status \
--purpose 'Read the isolated VM pool without booting a VM.'
apoc execution isolation warmup \
--vm-bundle "$PWD/extensions/macos-native/.build/vm-bundle" \
--idempotency-key isolation-warmup-v1 \
--purpose 'Wait for one usable isolated VM.'
apoc execution isolation drain \
--idempotency-key isolation-drain-v1 \
--purpose 'Tear down every pooled isolated VM.'
apoc provider add-mcp-http github https://example.test/mcp \
--profile-mode required \
--profile-header authorization=GITHUB_AUTHORIZATION \
--idempotency-key provider-github-v1 \
--purpose 'Register the GitHub MCP provider.'
apoc provider add-openapi logistics https://example.test/openapi.json \
--base-url https://example.test/api \
--idempotency-key provider-logistics-v1 \
--purpose 'Register the logistics OpenAPI provider.'action run and action start use the durable Code Mode lifecycle. Calls with
the same stable resource identity are ordered. Independent resources can run
concurrently. Every mutation stores an intent followed by an applied, failed, or
unknown receipt.
The packaged native macOS VZ provider contains the Rust provider, Linux guest, versioned wire protocol, build scripts, and signing entitlement. The image format is verified in Rust without starting the daemon, provider, or a VM.
§Use apoc through MCP
The built-in command graph serves MCP stdio with apoc --mcp. Register the
absolute installed path so the agent host does not depend on shell startup
configuration:
APOC_BIN=$(command -v apoc)
codex mcp add apoc -- "$APOC_BIN" --mcp
codex mcp get apocThe MCP, CLI, and Code Mode surfaces share command schemas, execution state, idempotency behavior, and output contracts.
apoc --mcp serves the five Code Mode lifecycle tools — codemode_search,
codemode_execute, codemode_execution, codemode_decide, codemode_cancel —
and nothing else. The surface stays five tools however many commands apoc grows
and however many MCP servers you configure, so adding either never costs the
model another tool schema.
A program reaches apoc’s own commands under apoc.*, and every MCP server already
configured on this machine, each under its own namespace: servers registered with Claude
Code, Codex, Cursor, VS Code, Copilot, Amp, Gemini, Windsurf or OpenCode are discovered
without anything to switch on. A namespace is named without being contacted and connects
on its first call, so a server that is slow, unreachable or removed costs nothing until a
program uses it, and cannot fail an execution that never names it. One
program can therefore read a repository, ask a downstream server about it, and
join both in JavaScript without returning to the model in between; only what it
returns crosses back.
apoc mcp check reports what was discovered without starting anything, and names the
reason a namespace is empty — an unsupported transport, a placeholder only a person can
supply, a rejected credential. apoc mcp refresh is the one command that contacts
servers and caches their schemas.
Two consequences worth knowing. The administrative command groups — daemon,
code, profile, env, recipe, recording, receipt, capability, action,
provider, connector, skill, mcp, decider — are reachable from the CLI but not from a
program, because each either cannot run safely from inside an execution or is a
human-at-a-terminal operation. And codemode_decide always reports that there is
nothing to decide: apoc runs every tool without pausing.
§Embed apoc in a Rust program
The same core the daemon runs can live inside another Rust process, with no
daemon and no socket. It answers the daemon’s own requests by method name, and
Code Mode programs it runs reach apoc.* in-process.
use serde_json::json;
fn main() -> Result<(), String> {
let apoc = apoc::Apoc::open("/absolute/path/to/app-state")?;
let state = apoc.call(
"code.run",
json!({
"code": "return (await apoc.execution_command({executable: '/bin/echo', \
arg: ['ready'], idempotency_key: 'ready', purpose: 'Check.'})).outcome;",
"timeout_ms": 60_000,
"purpose": "Run one command from an embedded core.",
}),
)?;
assert_eq!(state["result"], "passed");
Ok(())
}Apoc blocks the calling thread and owns its own runtime; from async code, use
apoc::CoreHandle::open(apoc::CoreConfig::new(path)).await instead. Calling the
blocking API inside an async runtime returns BLOCKING_FROM_ASYNC rather than
deadlocking.
An embedded core owns its state root exclusively. Opening a root that another
core or the per-user daemon already owns fails with STATE_ROOT_BUSY, because
two owners would cancel each other’s work. To work with the daemon’s state,
talk to the daemon.
No daemon does not mean no threads. An open core runs process monitors, a maintenance loop for hooks and lease expiry, and a pool of JavaScript workers, and commands it starts keep running under their own budgets after a call returns.
§Configure isolated profiles
Profiles are exclusive durable environments. A command selects one explicit
--profile, otherwise the longest matching canonical workspace root, otherwise
the nearest canonical cwd ancestor whose directory name exactly matches an
existing profile, otherwise the per-user default. Durable root mappings take
precedence over directory-name recognition. An explicit profile that disagrees
with either workspace selection fails instead of merging credentials. apoc never
creates a profile from a directory name; with no existing match and no default,
it runs without a profile. Secret values remain unresolved references and
resolve only when apoc constructs a process or provider transport.
apoc profile create personal --purpose 'Create the personal profile.' --idempotency-key profile-personal
# From /work/personal/project, cwd recognition now selects personal automatically.
apoc profile resolve --purpose 'Resolve this workspace profile.' --format json
# Use an explicit root mapping when the directory name differs from the profile.
apoc profile root add personal /work/client-alias \
--purpose 'Map the client alias to the personal profile.' \
--idempotency-key profile-personal-alias
apoc profile default personal --purpose 'Set the default profile.' --idempotency-key profile-default
apoc env set --profile personal RUST_LOG=debug \
--purpose 'Set durable Rust logging.' --idempotency-key env-rust-log
apoc env secret --profile personal OPENAI_API_KEY env:OPENAI_API_KEY \
--purpose 'Register the OpenAI key reference.' \
--idempotency-key env-openai-key
apoc env doctor --profile personal --purpose 'Check whether the profile can resolve.' --format jsonEach accepted execution pins the selected profile generation for its complete
child graph. Profile-controlled names are removed from daemon inheritance before
that generation is applied, and explicit command or command-unit overrides are
rejected. env list, env doctor, and profile show never return literal
values or secret references. The deprecated env --global form targets the
current default profile and creates legacy-default only when a compatible
mutation needs one. Every profile and environment mutation requires an
--idempotency-key.
§Search invocation history
apoc records each typed CLI, MCP, and Code Mode invocation in its local SQLite
database. Queries are local by default: every directory in one Git worktree
shares a scope, while a directory outside Git has its own exact canonical scope.
Use --global only when the task needs history from every recorded workspace.
Normalized arguments and options are stored and searchable. Secret-bearing
fields keep only their destination names; values, providers, and references are
removed before normalized input, search text, and pattern signatures are
written. Literal environment and header values remain recordable, so use
structured secret options for credentials.
apoc history list --limit 50 --purpose 'List recent local apoc activity.' --format json
apoc history list --error-code EXECUTION_PROGRESS_TIMEOUT --purpose 'List progress-timeout activity.' --format json
apoc history search 'process stop' --purpose 'Find earlier process stops.' --format json
apoc history search 'execution command' --global --purpose 'Find executions across workspaces.' --format json
apoc history list --cwd ../another-worktree --purpose 'List activity in the other worktree.' --format json
apoc history get INVOCATION_ID --purpose 'Read the complete invocation record.' --format json
apoc history patterns --min-count 3 --purpose 'Find repeated apoc workflows.' --format json
apoc history timeline --limit 100 --purpose 'Read apoc activity in event order.' --format json
apoc history query 'SELECT id, purpose FROM history ORDER BY started_at DESC LIMIT 20' --purpose 'Scan recent work narratives.' --format jsonlist and search return bounded reverse-chronological pages with
invocations and next_cursor. They accept exact filters for source,
surface, command, status, actor, linked execution, and error-code,
plus since-ms and until-ms. --global and --cwd cannot be combined. A local query does
not include imported records whose original working directory is unknown.
timeline returns complete sanitized records oldest-first. Its opaque cursor
holds a stable acceptance snapshot, so calls accepted after the first page do
not appear later in the same traversal. The default limit is 100 and the
maximum is 500.
history query runs one read-only SQL statement against an isolated in-memory
history table, never against apoc’s durable database. The table exposes
id, purpose, started_at, updated_at, status, command_path, source,
surface, actor, execution_id, and error_code for filtering and ordering,
but results may contain only id and purpose. The CLI returns compact
columns plus positional rows, defaults to 20 rows, and hard-caps at 100 even
when the SQL asks for more. Use history get ID only after a purpose identifies
something worth expanding.
Native capture is automatic and does not call DevSQL. Historical shell and agent transcripts can contain literal credentials, so inspect their retention and access before importing them. The following explicit command runs DevSQL once, imports only shell segments that invoke apoc, redacts recognized secret flags, preserves source provenance, and skips records already imported:
apoc history import-devsql --purpose 'Import earlier apoc shell observations.' --format jsonImported records have source: "devsql". Ordinary capture and every later
history query remain independent of DevSQL.
§React to typed apoc calls
Hooks run Code Mode JavaScript after an exact typed command starts, succeeds, or
fails. Configure the dotted method identity shown by Code Mode, such as
execution.command; apoc normalizes the command graph’s display path before
matching. A hook is local to the current worktree or canonical directory unless
you pass --global. A local hook shadows a global hook with the same name, while
differently named hooks stack.
apoc hook put build-followups execution.command \
--on-success 'return await apoc.action_start({provider: "notify", method: "send", input: JSON.stringify({source_invocation: hook.invocation.id}), idempotency_key: hook.delivery.id, purpose: "Send the successful execution notification."});' \
--on-failure 'return await apoc.execution_start({executable: "collect-diagnostics", arg: [hook.invocation.id], idempotency_key: hook.delivery.id, purpose: "Collect diagnostics for the failed apoc call."});' \
--max-attempts 3 \
--purpose 'Install build follow-up automation.' \
--idempotency-key build-followups-v1
apoc hook deliveries --hook build-followups \
--purpose 'Inspect build follow-up deliveries.' --format jsonThe hook program receives a frozen hook object. hook.delivery contains
id, hook, generation, phase, attempt, and max_attempts;
hook.invocation is the source invocation snapshot with normalized input and
terminal status when applicable. Use hook.delivery.id in nested mutation
idempotency keys so a daemon-interrupted attempt can replay safely.
When invocation history reaches a configured lifecycle transition, matching
deliveries are persisted and run asynchronously in the daemon. Hook success or failure never
changes the source call’s verdict. Failed programs retry with bounded exponential
backoff and become durably failed after max_attempts. Daemon recovery returns
interrupted deliveries to pending. Calls made by a hook carry hook depth and do
not create more hook deliveries, preventing accidental recursion. Each attempt
also emits hook.delivery.started and hook.delivery.result causal events.
Use hook get, list, remove, delivery, and deliveries to manage and
inspect definitions and outcomes. At least one of --on-start, --on-success,
or --on-failure is required.
§Ask a decider before commands run
A decider is a Code Mode program you register. Before apoc launches a command,
it runs every enabled decider that covers the command’s verb, with a frozen
intent describing the launch in scope, and waits for
{decision: "allow" | "refuse" | "pending", reason}. Any refusal stops the
launch, which fails with INTENT_REFUSED and the decider’s own reason.
apoc decider put no-rm \
--program 'const argv = intent.body.argv || [];
return argv[0] === "/bin/rm"
? {decision: "refuse", reason: "rm is not allowed here"}
: {decision: "allow"};' \
--verb execution.command \
--on-unavailable refuse \
--timeout-ms 2000 \
--purpose 'Refuse rm in this workspace.' \
--idempotency-key decider/no-rm-v1
apoc decider list --purpose 'List registered deciders.' --format json
apoc intent list --purpose 'Read what deciders were asked.' --format json
apoc decider remove no-rm --purpose 'Remove the rm decider.' --idempotency-key decider/no-rm-remove-v1--on-unavailable is required: you decide whether a decider that times out,
fails, or returns something malformed lets the command through or refuses it.
Such an intent is recorded as unchecked, never as ruled. The decider group is
available on the CLI but not inside Code Mode programs.
What is checked today is every command launch: execution command and
start, each batch child and pipeline stage, poll command iterations, and
commands run from Code Mode programs, hooks, and recipes. Not yet checked:
process signals and stops, calls into MCP servers and providers, isolated and
provider-backed executions, and debugger sessions.
What an intent can and cannot tell a decider:
- Its targets are only what apoc itself resolved: for a command, the executable
on the path it will launch. apoc does not parse arguments, so
rm -rf $TMPDIR/xnames/bin/rmand nothing else. - A shell string is not analysable:
analysableis false and its only target isopaque:.analysable: truemeans apoc did not have to give up on the request’s form, not that it understood the effect. - A decider’s own commands are not offered back to deciders.
pendingcurrently refuses; nothing yet holds a command open until someone answers.
intent list records an entry only when at least one decider was asked.
§Build a temporary command namespace
Use recipes when repeated commands should become a small composable interface
without creating a standalone binary. Dotted names form the namespace. A recipe
is local to the current Git worktree, or the exact current directory outside
Git, unless you pass --global. Local definitions shadow global definitions
with the same name.
apoc recipe put release.logs \
'return await apoc.execution_command({ executable: "tail", arg: ["-n", "100", input.file], purpose: "Read the latest release log.", idempotency_key: input.key });' \
--input-schema '{"type":"object","required":["file","key"]}' \
--ttl-ms 86400000 \
--purpose 'Define the temporary release-log command.' \
--idempotency-key release-logs-v1
apoc recipe put release.verify \
'return await recipes.run("release.logs", input);' \
--dependency release.logs \
--purpose 'Define the composed release verification command.' \
--idempotency-key release-verify-v1
apoc recipe run release.verify \
--input '{"file":"/tmp/release.log","key":"release-log-read"}' \
--purpose 'Run the temporary release verification command.' \
--idempotency-key release-verify-run-1 \
--format jsonapoc resolves the complete declared dependency graph before execution. Missing,
expired, cyclic, deeper-than-16, and larger-than-64 graphs fail before Code Mode
runs. The resolved functions execute inside one Code Mode program. Draft
2020-12 input and output schemas validate the top-level recipe boundary. Repeat
--require-env NAME on recipe put when a recipe must fail before Code Mode if
a literal or secret value cannot resolve. Portable bundles include required key
names, never values or references.
The caller LLM can propose a recipe from exact chronological evidence without making it executable. apoc stores the candidate and rationale; it does not run an embedded model or infer candidates with built-in heuristics.
apoc recipe suggest release.verify 'return input;' \
--positive FIRST_ID..SECOND_ID \
--positive THIRD_ID..FOURTH_ID \
--rationale 'The same verified sequence was repeated.' \
--require-env RELEASE_TOKEN \
--purpose 'Suggest a temporary release verification command.' \
--format json
apoc recipe suggestions --purpose 'List pending recipe suggestions.' --format json
apoc recipe suggestion SUGGESTION_ID --purpose 'Read the selected recipe suggestion.' --format json
apoc recipe adopt SUGGESTION_ID \
--purpose 'Adopt the selected recipe suggestion.' \
--idempotency-key adopt-release-verify --format jsonSuggestions remain separate from lookup, dependency resolution, execution
tools, and bundles. Adoption atomically creates the exact candidate and links
the suggestion. The default adopted lifetime is 604800000 ms (7 days); pass a
positive --ttl-ms to override it. A different existing generation is a
conflict unless you pass --replace.
Expired recipes remain durable but are hidden and cannot run. recipe pin
clears one expiry, and recipe prune deletes expired recipes in the selected
scope. Both commands require --idempotency-key.
apoc recipe list --prefix release. --include-expired --purpose 'List release recipes including expired entries.' --format json
apoc recipe pin release.verify --purpose 'Keep the release verification recipe.' --idempotency-key release-verify-pin
apoc recipe prune --purpose 'Remove expired local recipes.' --idempotency-key release-prune
apoc recipe export release. --file ./release-recipes.json \
--purpose 'Export the release recipe namespace.' \
--idempotency-key release-export
apoc recipe import ./release-recipes.json --ttl-ms 86400000 \
--purpose 'Import the release recipe namespace.' \
--idempotency-key release-importrecipe export writes RecipeBundleV1 and includes transitive dependencies.
The bundle excludes scope, expiry, timestamps, receipts, and resolved secrets.
recipe import validates the whole bundle before one atomic database write and
rejects conflicts unless you pass --replace.
§Record ordinary work into a command
Use recordings when the work that should become a recipe is work you are about to do anyway. Bracket it, run apoc normally, and stop with the name it should take. apoc transcribes the captured invocations into one Code Mode program and writes it into the recipe namespace described above.
apoc recording start deploy.verify \
--purpose 'Record the deploy verification procedure.' \
--idempotency-key deploy-record-1
apoc recording param sha=abc123 --purpose 'Pin the commit as a recipe input.'
apoc execution command ./deploy.sh --purpose 'Deploy the recorded commit.' \
--idempotency-key deploy-1 --expect-exit-code 0 -- --sha abc123
apoc execution command curl --purpose 'Verify the deployed health endpoint.' \
--idempotency-key health-1 --expect-stdout-regex '"ok"' -- -sf https://example.test/health
apoc recording stop deploy.verify \
--purpose 'Promote the recorded procedure to a recipe.' \
--idempotency-key deploy-record-stop-1 --format json
apoc recipe run deploy.verify --input '{"sha":"def456","runKey":"verify-1"}' \
--purpose 'Verify the newly deployed commit.' --idempotency-key verify-1A recording is local to the current Git worktree, or the exact current directory
outside Git, unless you pass --global. One recording is active per scope at a
time. Every typed invocation in that scope joins the recording, reads included,
except the recording commands themselves and the nested host calls inside a
code run program, which would otherwise emit twice.
Transcription is exact. Each call site is the recorded command_path and its
stored normalized input, so execution command becomes apoc.execution_command.
Options left unset or left at their declared default are omitted, because
omitting them resolves to the same value when the recipe runs. apoc does not run
an embedded model and does not invent steps.
Three sources decide which recorded literals become recipe inputs. Earlier sources win.
| Source | Declared by | Result |
|---|---|---|
| Explicit holder | recording param NAME=VALUE | Required input, substituted wherever that exact value appears. |
| Take difference | A second recording start with the same name | Required input for every path whose value changed between takes. |
| Recorded variation | The same normalizer behind history patterns | Optional input that falls back to the recorded literal. |
recording param compares values as JSON strings; pass --json when the holder
should match an exact number, array, or object. recording literal '$.timeout_ms'
forces one step-relative path to stay literal in every step.
Recorded idempotency keys never become literals. Each one is rebuilt from a
single required runKey input, so rerunning a recipe performs real work instead
of replaying the original receipts. Recorded secret references are redacted in
history and cannot be transcribed, so each redacted destination becomes a
required input holding its PROVIDER:REFERENCE.
apoc recording status --purpose 'Read what the recording would emit.' --format json
apoc recording list --purpose 'List recordings in this scope.' --format json
apoc recording get RECORDING_ID --purpose 'Read one recording and its call sites.' --format json
apoc recording discard --purpose 'Abandon the active recording.' --idempotency-key deploy-record-drop-1Read recording status before stopping to see the exact ordered call sites, then
repeat --skip INVOCATION_ID on recording stop to drop the ones that were
incidental. Adding a take requires the same call sequence; a different length or
a different command at the same position fails with RECORDING_TAKES_DIVERGED
and writes nothing.
Stop with --suggest instead of a plain stop when the candidate should stay
non-executable. That path stores a recipe suggestion with each take as
positive evidence and leaves adoption to recipe adopt. It requires at least two
takes, matching the evidence rule for suggestions.
Recorded parallelism is emitted sequentially. A recording captures the order
calls were accepted, not their concurrency, so rewrite the emitted body with
Promise.all through recipe put when the steps are independent.
§Inspect events and state
apoc appends monotonically ordered lifecycle events. Repeated large payloads are content-addressed and deduplicated; event metadata remains after payload pruning.
apoc event query --after 0 --limit 100 --purpose 'List recent lifecycle events.'
apoc event watch --after CURSOR --timeout-ms 30000 --purpose 'Wait for new lifecycle events.'
apoc event export --after 0 --format jsonl --purpose 'Export lifecycle events as JSON lines.'
apoc event payload PAYLOAD_ID --purpose 'Read the selected event payload.'
apoc event pin PAYLOAD_ID --purpose 'Keep the selected event payload.'
apoc event prune-payloads --max-age-ms 2592000000 --purpose 'Remove old unpinned event payloads.'Commands that need durable ownership automatically start one detached daemon per user.
apoc daemon start --purpose 'Start the durable apoc daemon.' --idempotency-key daemon/start-v1 --format json
apoc daemon status --purpose 'Check the durable apoc daemon.' --format json
apoc daemon stop --purpose 'Stop the durable apoc daemon.' --idempotency-key daemon/stop-v1 --format json| State | Default macOS path |
|---|---|
| Database | ~/Library/Application Support/apoc/apoc.sqlite3 |
| Execution logs | ~/Library/Application Support/apoc/runs/ |
| Daemon log | ~/Library/Application Support/apoc/daemon.log |
| Socket | $TMPDIR/apoc-<effective-user-id>/apoc.sock |
Ordinary consumer work uses the installed per-user controller without setting
APOC_HOME or APOC_RUNTIME_DIR. Set both only for apoc tests and integration
fixtures, or for an explicitly bounded isolation task. Return to the default
controller after a temporary compatibility workaround is no longer needed;
never carry a dated temporary runtime into later ordinary work.
Set both APOC_HOME and APOC_RUNTIME_DIR to run a bounded isolated instance. apoc
backs up a non-empty database before each schema migration. The runtime directory
uses mode 0700; the Unix socket uses mode 0600. $TMPDIR represents the
platform temporary directory returned to the process and is commonly under
/var/folders/.../T on macOS. <effective-user-id> is the numeric effective
user ID returned by the operating system.
§Cleanup
The daemon runs one cleanup pass every 10 minutes. apoc gc runs the same pass
on demand. Without --apply it only reports counts and a sample of up to 10 IDs
per category.
apoc gc --purpose 'Preview stale apoc state.' --idempotency-key gc/preview-1 --format json
apoc gc --apply --purpose 'Clean up stale apoc state.' --idempotency-key gc/apply-1 --format json- Orphans. apoc closes a running execution when its process identity (boot ID,
PID, and start time) is gone and no supervisor owns it. The run becomes
interrupted. The execution becomesfailedwithEXECUTION_INTERRUPTEDand the cause. It is never markedcompleted, and nothing is signaled. A Code Mode program that no actor owns any longer is closed the same way. First, its execution-owned children are canceled. Work whose owning execution finished or vanished, or whose session closed or expired, is canceled withEXECUTION_OWNER_GONE. Cancellation goes through typed cancellation, which re-verifies process identity before it sends a signal. The check skips work touched within the lastAPOC_GC_ORPHAN_GRACE_MS(default 60000). - Unowned background work.
execution startwith no parent and no session gets a lifetime of 24 hours (APOC_GC_UNOWNED_LIFETIME_MS). The clock restarts on every get, tree, wait, attach, input, signal, or log read. Set--lifetime-ms Nto change it, or--keep-aliveto opt out.APOC_GC_UNOWNED=report(the default) lists expired work.stopcancels it through typed cancellation withEXECUTION_EXPIRED.offskips the check. - History retention. apoc deletes terminal executions older than
APOC_GC_RETENTION_DAYS(default 30;0disables) in batches of 200. Deletion includes their events, unpinned payloads, process events, leases, invocation records, search rows, observation versions, and run logs. It also deletes older terminal invocation records and process events that belong to no execution. To keep an execution, its children, and its invocations, label it--label apoc.keep=true. Recording invocations are always kept. - Space. New databases use incremental auto-vacuum, so deleted pages go back
to the operating system. An older database reuses its free pages and keeps its
file size. apoc never runs a full
VACUUMon its own.
A daemon with a non-default APOC_HOME or APOC_RUNTIME_DIR exits once it has
had no connected client and no nonterminal work for APOC_DAEMON_IDLE_EXIT_MS
(default 1800000; 0 disables). It also exits soon after its APOC_HOME is
deleted. The default per-user daemon never exits on its own.
APOC_GC_INTERVAL_MS sets the pass period, and 0 disables the periodic pass.
apoc daemon status reports gc with the last pass’s counts and pending
counts.
§Upgrade and verify
cargo install apoc --version 0.9.1 --locked --force
apoc skill install --purpose 'Install the updated apoc operator skill.' --idempotency-key skill/install-updated-v1
apoc version --purpose 'Check the upgraded apoc version.' --format json
apoc skill status --purpose 'Check the updated apoc skill installation.' --format json
apoc daemon stop --purpose 'Stop the older durable apoc daemon.' --idempotency-key daemon/stop-upgrade-v1 --format jsonThe next durable command starts the current daemon build. apoc version reports
the client version and public execution schema. apoc daemon status reports the
daemon build and schema when it is running.
§Reference
There is no public issue tracker or support channel. The structured CLI help, JSON Schemas, embedded operator skill, and packaged source are the public product contract.
§License
apoc is available under the MIT License.
Re-exports§
pub use cli::build_cli;pub use daemon::CoreConfig;pub use embed::Apoc;pub use embed::CoreHandle;
Modules§
- benchmark
- Reproducible process-workflow performance comparisons.
- cli
- Incurs command graph shared by CLI, MCP, and Code Mode.
- code
- Durable Incurs Code Mode integration.
- daemon
- Per-user daemon and length-framed Unix socket RPC.
- debugger
- Native Chrome DevTools Protocol sessions owned by the apoc daemon.
- embed
- apoc inside another process, with no daemon and no socket.
- error_
telemetry - Best-effort local error metadata, independent of the durable database.
- execution
- Durable agent execution lifecycle over local processes.
- history
- Native invocation-history recording and workspace scoping.
- hook
- Durable command hooks and delivery matching.
- image
- Offline verification for isolated VM image bundles.
- intent
- One shape for everything apoc is about to do to the machine.
- mcp_
surface - Serving Code Mode as apoc’s MCP surface.
- model
- Shared process, run, and action contracts.
- observe
- Read-only projections of durable apoc activity.
- operation
- Shared typed contracts for requests crossing the local daemon transport.
- poll
- Durable polling over exact commands and the shared typed apoc graph.
- process
- Native process discovery, selection, port ownership, and control.
- provider_
execution - Registered provider transport for durable execution backends.
- skill
- Embedded apoc skill distribution.
- store
- SQLite-backed durable state.
Structs§
- RunLogs
- Tail of one managed run’s output.