Documentation

ActantOS Quickstart

Get started with ActantOS to govern, audit, and secure your autonomous AI agents. Quiet Open-Core v1.2.0 and Stage 2 control-plane ops are live — view on GitHub. For a full work playbook, see How to use ActantOS at work, then Stage 2 complete, v1.2.0 release, and the kernel deep-dive.

1. Prerequisites

Portable first test: Node.js 22+ and Git only. Persistent team install: also Docker Desktop. The marketing site runs on port 3000; actantosd defaults to port 3100 to avoid collisions.

2. Prove the loop (portable, ~15 minutes)

Before Compose, run the portable agent test. It starts an in-memory actantosd, exercises allow / deny / approval_required, and shuts down. Full work playbook: How to use ActantOS at work.

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

Details: How to test an AI agent through ActantOS on any computer.

3. Start a persistent control plane

For shared work, start the daemon and Postgres with Docker Compose. The daemon exposes the decision API at http://localhost:3100.

git clone https://github.com/kotobuki09/actantos-releases.git
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
cd actantosd && npm install
npm run demo -- --url http://localhost:3100

The demo script exercises the full enforcement story: credential reads denied, git push approval_required, manual approval, kill switch, and audit timeline. Day-2 ops live at /dashboard, /dashboard/metrics, and /dashboard/policy.

4. Integrate with Pi

Wrap Pi file and shell tools with the guarded adapter. Each call flows through POST /v1/intercept/tool-call before execution.

import { guardedRead, guardedBash } from "@actantos/pi-adapter";

// Blocked: credential path access
await guardedRead(".env");

// Approval required: destructive git push
await guardedBash("git push --dry-run origin main");

5. Route MCP clients through the gateway

Point MCP clients at ActantOS instead of upstream servers. The gateway authenticates agent identity, verifies tool manifest hashes, and intercepts tools/call before forwarding allowed requests.

Architecture overview

ActantOS operates as a middleware layer between your AI model and the external systems it interacts with — intercepting, evaluating, and pausing actions before they impact your infrastructure. The MVP separates the control plane (policy, approvals, budgets, audit) from the data plane (MCP gateway, Pi adapter, Docker sandbox). Adapters fail closed if the daemon is unreachable.