apoc
Local process control and durable command orchestration 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.
apoc is designed for agentic workloads: many independent operations issued in one pass, long-running work that survives the initiating call, and later agents that must inspect what happened without reconstructing state from terminal text.
Status and scope
| Property | Current contract |
|---|---|
| Release | 0.3.1 |
| Platform | Supported: macOS |
| Minimum Rust version | 1.95 |
| Interfaces | CLI, MCP stdio, and Code Mode JavaScript |
| State | Local SQLite database, execution logs, and content-addressed artifacts |
| Authority | The operating-system permissions of the user who starts apoc |
| License | MIT |
apoc does not provide a sandbox, policy engine, confirmation layer, or embedded model. It exposes destructive operations and their metadata directly. The calling agent is responsible for selecting the correct target and action.
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.
Install
apoc 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:
The response has one stable envelope. This abridged example omits timestamps, the full execution specification, attempts, and log-tail metadata:
Use the returned execution ID to inspect or control the work later:
Choose the smallest execution surface
| Work | Preferred surface |
|---|---|
| One process query or mutation | apoc process ... |
| One managed command | apoc execution command 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 ... |
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 and providers
All 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.
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.
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:
The causal journal answers relationship questions from recorded evidence:
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.
Durable execution contract
execution is the public lifecycle abstraction. Direct argv is the default;
repeat --arg to preserve argument boundaries. Use --shell only when the
program intentionally requires /bin/zsh -lc parsing.
An 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{ execution, replayed, logs }.- 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.
- Reusing an idempotency key for a different normalized request fails before launching work.
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.
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.
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.
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.
Code 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.
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.
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.
Reservations 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 the standalone macOS provider before registering its release binary.
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 macOS provider covers app, window, Accessibility, input, pasteboard, capture, Shortcuts, URL, AppleScript, and JXA operations without adding platform dependencies to apoc core.
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=
The MCP, CLI, and Code Mode surfaces share command schemas, execution state, idempotency behavior, and output contracts.
Inspect events and state
apoc appends monotonically ordered lifecycle events. Repeated large payloads are content-addressed and deduplicated; event metadata remains after payload pruning.
Commands that need durable ownership automatically start one detached daemon per user.
| 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 |
Set both APOC_HOME and APOC_RUNTIME_DIR to run an 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.
Upgrade and verify
The 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.