apoc 0.4.0

Agentic process control for LLMs
Documentation

apoc

Unrestricted process control and durable execution for LLM agents.

crates.io docs.rs license MSRV

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.4.0
Platform Supported: macOS
Minimum Rust version 1.95
Interfaces CLI, MCP stdio, and Code Mode JavaScript
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 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.

Purpose and agent narration

Every executable apoc command requires a one-line purpose of at most 120 characters with no secrets. In an agentic thread, the LLM writes that exact sentence immediately before the call. The parameter itself has no ordering requirement.

A useful purpose states the intended decision or proof. Treat each purpose as one narrative beat. When prior evidence matters, carry forward the relevant observed state. Never invent an observation or result. For example, after identifying a port owner, prefer Port 5173 belongs to Vite; I’m reading its context before deciding whether to stop it. over Read process context. This is a content requirement, not a runtime grammar.

Purposes are stored with native invocation history and can be found with apoc history search. Framework discovery such as help, schema, and --llms does not execute a command and is exempt.

Install

cargo install apoc --version 0.4.0 --locked
apoc skill install --purpose 'Install the apoc operator skill.'
apoc version --purpose 'Check the installed apoc version.' --format json
apoc skill status --purpose 'Check the apoc skill installation.' --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 \
  --purpose 'verify the apoc installation' \
  --format json \
  -- '%s\n' 'hello from apoc'

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 --purpose 'Check the execution state.' --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 --purpose 'Cancel the active execution.' --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
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 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. 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.

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. Use --shell only when the program intentionally requires zsh parsing.

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

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.

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/health

Poll 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 json

The 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 \
  --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 \
  --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.

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"],
      purpose: "Verify the current worktree."
    })
  ]);
  return { processes, sockets, tests };
' --purpose 'Inspect processes and verify the current worktree.' --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.

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.' --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.' --format json
apoc code artifact EXECUTION_ID ARTIFACT_ID --purpose 'Read the Code Mode artifact.' --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 --purpose 'Open a release-agent ownership session.'
apoc session heartbeat SESSION_ID --ttl-ms 60000 --purpose 'Renew the release-agent session.'

apoc reservation acquire port tcp/5173 session/SESSION_ID --purpose 'Reserve the development port.'
apoc reservation acquire path /absolute/worktree session/SESSION_ID --purpose 'Reserve the release worktree.'

apoc execution start cargo \
  --owner session \
  --session SESSION_ID \
  --purpose 'Start tests owned by the release session.' \
  -- test

apoc session close SESSION_ID --timeout-ms 2000 --purpose 'Close the release-agent session.'

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 \
  --purpose 'Register the GitHub MCP provider.'
apoc provider add-openapi logistics https://example.test/openapi.json \
  --base-url https://example.test/api \
  --purpose 'Register the logistics OpenAPI provider.'
apoc provider add-mcp-stdio macos \
  "$PWD/extensions/macos/.build/release/apoc-macos" \
  --purpose 'Register the macOS MCP provider.'

apoc provider doctor macos --purpose 'Check the macOS provider connection.'
apoc provider refresh macos --purpose 'Refresh macOS provider capabilities.'
apoc capability search 'focus a macOS window' --purpose 'Find a macOS window-focus capability.'
apoc action run macos clipboard_read --purpose 'Read the macOS clipboard.'
apoc action run macos window_focus --input '{"pid":4242,"index":0}' \
  --purpose 'Focus the selected macOS window.'

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.

Configure a durable environment

Use one implicit environment per Git worktree or canonical directory. Pass --global for values that every workspace should inherit. Literal values are durable. Secret values are not: env secret stores an unresolved reference and resolves it only when apoc constructs a process or provider transport.

apoc env set RUST_LOG=debug --purpose 'Set durable Rust logging.' --idempotency-key env-rust-log
apoc env secret OPENAI_API_KEY env:OPENAI_API_KEY \
  --purpose 'Register the OpenAI key reference.' \
  --idempotency-key env-openai-key
apoc env list --purpose 'List effective environment names.' --format json
apoc env doctor --purpose 'Check whether the environment can resolve.' --format json
apoc env unset RUST_LOG --purpose 'Remove durable Rust logging.' --idempotency-key env-rust-log-unset

Precedence is daemon inheritance, global apoc environment, local apoc environment, execution --env or --secret-env, then a batch or pipeline unit's environment. env list and env doctor return destination names, scopes, generations, and resolution status. They never return literal secret values or provider references. Every environment mutation requires --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 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 json

list and search return bounded reverse-chronological pages with invocations and next_cursor. They accept exact filters for source, surface, command, status, actor, and linked execution, 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 json

Imported records have source: "devsql". Ordinary capture and every later history query remain independent of DevSQL.

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 json

apoc 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 json

Suggestions 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-import

recipe 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.

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.' --format json
apoc daemon status --purpose 'Check the durable apoc daemon.' --format json
apoc daemon stop --purpose 'Stop the durable apoc daemon.' --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.

Upgrade and verify

cargo install apoc --version 0.4.0 --locked --force
apoc skill install --purpose 'Install the updated apoc operator skill.'
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.' --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.