apoc 0.3.1

Agentic process control for LLMs
Documentation

apoc

Local process control and durable command orchestration for LLM agents.

crates.io docs.rs license

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

cargo install apoc --version 0.3.1 --locked
apoc skill install
apoc version --format json
apoc skill status --format json

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:

apoc execution command /usr/bin/printf \
  --arg '%s\n' \
  --arg 'hello from apoc' \
  --purpose 'verify the apoc installation' \
  --format json

The response has one stable envelope. This abridged example omits timestamps, the full execution specification, attempts, and log-tail metadata:

{
  "execution": {
    "id": "EXECUTION_ID",
    "status": "completed",
    "result": { "exit_code": 0 }
  },
  "replayed": false,
  "logs": {
    "stdout": "hello from apoc\n",
    "stderr": "",
    "stdout_truncated": false,
    "stderr_truncated": false
  }
}

Use the returned execution ID to inspect or control the work later:

apoc execution get EXECUTION_ID --format json
apoc execution logs EXECUTION_ID --tail-bytes 65536 --format json
apoc execution wait EXECUTION_ID --timeout-ms 30000 --format json
apoc execution cancel EXECUTION_ID --timeout-ms 2000 --format json

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.

apoc process list --selector match:node --sort memory --limit 20
apoc process select port:5173/tcp
apoc process tree name:vite
apoc process files pid:4242
apoc process sockets --listening --protocol tcp
apoc process probe pid:4242
apoc process sample --selector match:node --count 5 --interval-ms 250

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
}'

The causal journal answers relationship questions from recorded evidence:

apoc process why pid:4242
apoc process impact pid:4242
apoc process owner pid:4242
apoc process related pid:4242
apoc process changed pid:4242
apoc process context pid:4242 --events 50

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 --idempotency-key deploy-91/term
apoc process stop port:5173/tcp --timeout-ms 2000 --force \
  --idempotency-key deploy-91/free-port
apoc process pause pgid:4242 --idempotency-key debug-7/pause
apoc process resume pgid:4242 --idempotency-key debug-7/resume

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.

apoc execution start /usr/bin/python3 \
  --arg -m \
  --arg http.server \
  --arg 8000 \
  --name docs \
  --purpose 'serve documentation for review' \
  --max-attempts 3 \
  --retry-backoff-ms 500 \
  --timeout-ms 300000

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 --cwd resolves from that directory. apoc validates and canonicalizes it before accepting the execution.
  • command, batch, and pipeline return { 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.

{
  "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 \
  --file commands.json \
  --purpose 'verify the worktree concurrently' \
  --idempotency-key verify-91/batch \
  --format json

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 \
  --file pipeline.json \
  --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.

apoc code run '
  const [processes, sockets, tests] = await Promise.all([
    apoc.process_list({ selector: "match:node", limit: 20 }),
    apoc.process_sockets({ listening: true, protocol: "tcp", limit: 100 }),
    apoc.execution_command({
      executable: "cargo",
      arg: ["test"],
      purpose: "verify the current worktree"
    })
  ]);
  return { processes, sockets, tests };
' --format json

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.

apoc code start 'return await apoc.execution_list({});' --format json
apoc code get EXECUTION_ID --format json
apoc code cancel EXECUTION_ID --format json
apoc code artifact EXECUTION_ID ARTIFACT_ID --format json

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
apoc session heartbeat SESSION_ID --ttl-ms 60000

apoc reservation acquire port tcp/5173 session/SESSION_ID
apoc reservation acquire path /absolute/worktree session/SESSION_ID

apoc execution start cargo \
  --arg test \
  --owner session \
  --session SESSION_ID

apoc session close SESSION_ID --timeout-ms 2000

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.

swift build -c release --package-path extensions/macos

apoc provider add-mcp-http github https://example.test/mcp \
  --secret-header authorization=env:GITHUB_AUTHORIZATION
apoc provider add-openapi logistics https://example.test/openapi.json \
  --base-url https://example.test/api
apoc provider add-mcp-stdio macos \
  "$PWD/extensions/macos/.build/release/apoc-macos"

apoc provider doctor macos
apoc provider refresh macos
apoc capability search 'focus a macOS window'
apoc action run macos clipboard_read
apoc action run macos window_focus --input '{"pid":4242,"index":0}'

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=$(command -v apoc)
codex mcp add apoc -- "$APOC_BIN" --mcp
codex mcp get apoc

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.

apoc event query --after 0 --limit 100
apoc event watch --after CURSOR --timeout-ms 30000
apoc event export --after 0 --format jsonl
apoc event payload PAYLOAD_ID
apoc event pin PAYLOAD_ID
apoc event prune-payloads --max-age-ms 2592000000

Commands that need durable ownership automatically start one detached daemon per user.

apoc daemon start --format json
apoc daemon status --format json
apoc daemon stop --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

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

cargo install apoc --version 0.3.1 --locked --force
apoc skill install
apoc version --format json
apoc skill status --format json
apoc daemon stop --format json

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.