Repository Public
1# Agent OS — agent.spboucher.ai23A from-scratch agentic platform: you give an agent a **mission** in a project (a git repository on the4host), it works in a sandbox, journals every step durably, asks before anything with an outside effect,5and you follow and steer it from a web console (desktop and phone). No agent framework: its own6orchestration, its own durable-execution kernel on PostgreSQL, the official Anthropic and OpenAI SDKs.78Scope today = **phases 0–2**: foundations, durable kernel, one agent per mission, two providers,9file / shell / git tools in a Seatbelt sandbox, policy + durable approvals, live console. See10[What is not built](#what-is-not-built).1112## Architecture1314```15browser ──HTTPS/WSS──▶ Caddy (MacLustr Tunnel) ──▶ apps/server :8640 auth, REST, events WebSocket, static console16 apps/worker claims runs, executes the engine, journals steps (no listener)17 PostgreSQL 17 the only shared state: journal, queue, waits, events18```1920- The **server never runs agent code**; the **worker never serves HTTP**. They meet only in Postgres21 (tables + `LISTEN/NOTIFY` as a doorbell, slow-poll fallback).22- **Kernel** (`@aos/kernel`): deterministic replay over a step journal. Run logic is re-run from the top on23 every claim; steps with a recorded result return it, execution resumes at the first step without one.24 Leases with fencing tokens, durable waits (approvals, questions, timers), budgets, events, artifacts.25- **Engine** (`@aos/engine`): the agent loop as kernel run logic — model turn → tool batch → policy gate →26 journaled tool steps; done-criteria protocol; stall, budget and context governors; mission git branch.27- **Tools** (`@aos/tools`): read / list / search / edit / write, `shell` (macOS Seatbelt, fail closed),28 git status / diff / commit / push, control tools (`ask_owner`, `propose_criteria`, `update_criteria`, `finish`).29- **Providers** (`@aos/providers`): Anthropic Messages and OpenAI Responses adapters, native transcripts kept30 opaque and replayed verbatim, price table.31- **Server** (`apps/server`): Fastify, password + mandatory second factor (TOTP or passkey), CSRF, CSP with32 per-document script hashes, REST `/api/v1`, events WebSocket with cursor replay. Every kernel write goes33 through `kernel-adapter.ts`.34- **Web** (`apps/web`): Next.js static export served by the server; live timeline merged by step `seq`.3536Design rationale (French): `docs/ARCHITECTURE.md`. Interface contract: `docs/CONTRACT.md`.3738## Repository layout3940| Path | What |41|---|---|42| `packages/shared` | frozen vocabulary and browser DTOs (zod) |43| `packages/kernel` | durable execution on Postgres, `migrate`, `migrate-cli` |44| `packages/providers` | Anthropic / OpenAI adapters, catalogue, prices |45| `packages/tools` | tools, path safety, Seatbelt sandbox |46| `packages/engine` | agent loop, policy, approvals, criteria, governors |47| `apps/worker` | worker process (`dist/main.js`) |48| `apps/server` | HTTP/WS server (`dist/main.js`), see `apps/server/README.md` |49| `apps/web` | console (static export in `out/`), dev mock, Playwright suites `e2e/` (mock) and `e2e-real/` |50| `db/migrations` | SQL migrations, applied by the kernel's `migrate` |51| `scripts` | `dev-up.sh`, `dev-down.sh`, `ci.sh` |52| `deploy` | `make-manifest.py` (mld manifest), `backup.sh`, `restore.sh` |53| `docs` | `ARCHITECTURE.md`, `CONTRACT.md`, `deployment.md`, `operations.md`, `security.md` |5455## Development quick start5657Requirements: macOS, Node ≥ 24 (tested on 26), pnpm, PostgreSQL 17 on the `/tmp` socket, git, and58`~/.config/agent-os/dev.env` (mode 0600) with `ANTHROPIC_API_KEY=…` and/or `OPENAI_API_KEY=…`.5960```bash61scripts/dev-up.sh # build all, create/migrate agent_os_dev, start worker + server62cat /tmp/aos-dev-data/setup-token # one-time token for the first-run page (never printed by the scripts)63open http://localhost:8640 # create the administrator, enrol TOTP or a passkey64scripts/dev-down.sh # stop both (database and /tmp/aos-dev-data are kept)65```6667`dev-up.sh` refuses to start twice, never echoes a key (the processes read the file named by68`AOS_ENV_FILE` themselves), uses data dir `/tmp/aos-dev-data` and workspace root `/tmp/aos-dev-workspace`,69and serves `apps/web/out`. `scripts/dev-up.sh --worker` starts only a worker (after a crash).70Do not run plain `pnpm install`; dependency changes follow the lock procedure of `docs/CONTRACT.md` §0.7172## Tests7374```bash75scripts/ci.sh # build, typecheck, every unit suite (real Postgres, no model call), production web build76scripts/ci.sh --e2e # + Playwright against the dev mock, + the real end-to-end suite (real models, a few cents)77```7879- Unit suites create and drop their own `aos_test_<random>` databases.80- `apps/web/e2e/` runs the static export against `dev/mock-server.mjs`, a fixture that emits exactly the81 shapes of the real kernel / engine (build with `NEXT_PUBLIC_E2E=1`; `ci.sh` does it).82- `apps/web/e2e-real/` is the acceptance test of phases 0–2: real server + worker + Postgres + real models83 through the browser. Its global setup **resets** `agent_os_dev`, `/tmp/aos-dev-data` and84 `/tmp/aos-dev-workspace`. Results of the last run: `apps/web/e2e-real/last-run.json`, screenshots in85 `apps/web/e2e-real/screenshots/`.86- Opt-in live tests of single packages: `AOS_LIVE_TESTS=1 pnpm --filter @aos/providers test` (and engine).8788## Deploy8990Production runs on a MacLustr node through the cluster orchestrator `mld` (PM2, MacLustr Tunnel):91`docs/deployment.md`. First-run, updates, backup / restore, crash recovery: `docs/operations.md`.92Threat model, controls and known gaps: `docs/security.md`.9394## What is not built9596Sub-agent orchestration (the data model supports run trees; the engine runs one agent), context97compaction (a run that fills ~90 % of the context window ends `partial`), long-term memory, remote98runners, MCP, web browsing, an egress proxy for `network: open` missions, a dedicated OS user for the99worker, replay of `policy.decision` events over REST. See the "Known gaps" list of `docs/security.md`.100