How to Use ActantOS at Work

Who this is for

You have (or want) coding agents — Pi, Cursor-style tools, MCP clients — that can read files, run shell, and call external systems. You need a deterministic gate before those tools run, not another prompt filter.

ActantOS is that gate: in-path, fail-closed, out-of-process. Stage 1 is the Enforcement Kernel. Stage 2 is day-2 ops on top of it.

What “using the platform” means day to day

A normal workday (by role)

Developer — Start your coding agent as usual. Safe reads and local edits pass through as allow. If you hit .env or secrets paths, the agent gets a hard deny (not a soft warning). If you ask it to git push or similar remote side effects, it pauses with approval_required until someone on the approval rota decides.

Approver — Open /dashboard Pending Approvals (or Slack / your webhook bot). Review the tool name, args summary, risk class, and session. Approve once (one-use token) or deny. You are not rewriting policy mid-flight; you are deciding exceptions policy already flagged.

Security / platform — Morning check on /dashboard/metrics: allow vs deny vs approval rates, kill-switch state, budget headroom. Before a policy change, dry-run a real tool-call JSON against a candidate Cedar bundle. Promote only when the dry-run matches intent. Export evidence when audit asks.

1. Prove the loop on your machine (15 minutes)

If you only do one thing first, do this. Node.js 22+ is enough for the portable test:

git clone https://github.com/kotobuki09/actantos-releases.git
cd actantos-releases/actantosd
npm run quickstart

You should see allow on a safe read, deny on .env, approval_required on a side-effect command, and audit IDs for evidence.

Deep dive: How to Test an AI Agent Through ActantOS on Any Computer.

2. Run a persistent control plane (team use)

For shared work, use Docker Compose so Postgres and the daemon stay up:

cd actantos-releases
cp actantosd/.env.example actantosd/.env
docker compose -f actantosd/docker-compose.yml up -d --build
curl -sf http://127.0.0.1:3100/health/ready

Default API port is 3100. Health endpoints:

• GET /health/live — process up
• GET /health/ready — ready when the database is connected

Hosted/single-tenant notes live in the product repo as docs/HOSTED.md.

3. Put real work behind the gate (coding agent path)

Primary path for work: Pi (or Pi-compatible) tools wrapped so every file/shell call hits:

POST /v1/intercept/tool-call

Conceptually:

1. Agent requests a tool action
2. ActantOS evaluates kill switch → budgets → Cedar → risk → approval state
3. Returns allow, deny, or approval_required
4. Only then may execution proceed (sandbox when configured)
5. Tool result and decision land on the hash-chained audit trail

If actantosd is down, adapters fail closed — tools do not silently run.

Optional path: route MCP clients through the ActantOS MCP gateway for list filtering, call intercept, manifest drift, and SSRF controls.

See also: /docs, /mvp, /docs/integrations.

4. Set policy for your workflow (not generic AI safety)

Start with the shipped Balanced coding template; move to Strict only if your team accepts more friction.

Typical work rules:

Stage 2 practice: upload a candidate Cedar bundle, dry-run a real tool-call JSON against it without activating, then promote when green.

• API: POST /v1/policy-bundles/:id/test
• UI: /dashboard/policy

5. Approve risky work without blocking the whole team

When policy returns approval_required:

1. Agent pauses with an approval_id
2. Approver decides approved or denied
3. Approved path resumes with a one-use token

Channels you can use today:

Configure channels via GET/PUT /v1/approvals/channels. Microsoft Teams is not the current default path.

6. Day-2 operations (what you open every morning)

Product pages on this site: /platform/operator-visibility, /platform/policy-engine, /platform/approval-workflow.

7. Optional: lock down operator access

Runtime intercept stays available for agents. For operator APIs and dashboards you can enable:

Without a valid key/token, ops routes return 401. Intercept/tool-result stay on the agent path.

8. A one-week rollout pattern that works

Optional Success Package is install help only — not a prerequisite for “done.”

What not to expect yet (honest)

• Multi-tenant commercial SaaS control plane
• Firecracker/gVisor isolation tiers
• WORM storage or productized SIEM destinations
• “We are battle-tested at 100 enterprises” claims without your own production evidence

Those are Stage 3 / commercial paths. Self-host Stage 1–2 is what you run for work today.

Checklist

• Portable quickstart or Compose install is green
• At least one real agent path hits /v1/intercept/tool-call
• Credential read is deny; one high-risk action is approval_required
• Someone on the team completed an approval
• Policy dry-run used before a bundle promote
• Metrics home and audit timeline reviewed once
• Kill switch owner named

Links

• Stage 2 announcement: /blog/actantos-stage-2-control-plane
• Portable test guide: /blog/test-an-ai-agent-on-any-computer
• v1 kernel story: /v1
• Docs quickstart: /docs
• Roadmap: /roadmap
• GitHub: actantos-releases

Govern the tool call. Approve the exceptions. Operate from evidence.