# CyberBrain26 v4.1

A local, security-first control layer that authorizes, gates and audits agent actions on a
single Linux workstation. Not an AI operating environment, and not a general-purpose
sandbox for hostile code.

**Positioning:** a narrow, fail-closed authorization and execution layer in front of code
an agent wants to run on your machine — identity -> policy -> permission -> approval ->
sandbox -> audit.

Current state: a tested Python prototype. 413 tests pass in this working tree
(`PYTHONPATH=src python3 -m pytest -q`, recorded 2026-10-02; the tree is uncommitted and
moving, so re-run it). It is not production-ready and carries no security certification. Read [SECURITY.md](SECURITY.md) before trusting it with anything you care
about.

## What it is

- One console command, `cyberbrain`, with a small, closed command surface (below).
- A fail-closed authorization chain on the `run` path. Every step is checked for agent
  identity, permission scope, policy and human approval before any process is started, and
  every outcome is written to a local audit log.
- A Linux Bubblewrap sandbox for the code that survives those gates. No Bubblewrap means no
  execution — there is no unsandboxed fallback.
- Local SQLite persistence for approval requests, approval decisions, audit events and
  durable step records.
- A read-only `doctor check` that self-reports the effective configuration. It is a
  configuration report, not a liveness probe, and it contacts no model provider.

## What it is NOT

- Not an agent framework, orchestrator platform, or "AI operating environment".
- Not an HTTP API, web UI, TUI, or MCP server. None exists. `control_plane/api` and
  `control_plane/registry` are unreachable skeleton code with zero routes and zero
  importers.
- Not a model gateway. No model call happens in `plan` or `run`, and the model layer is
  library-only and unreachable from the CLI.
- Not a container, VM or microVM runtime. Bubblewrap namespaces only.
- Not a git-change review tool. There is no worktree, no `git diff`, no merge step.
- Not a multi-user, team, or compliance product. No SSO, no central audit, no
  certification.
- Not a hostile-code sandbox. See the limits below and `EXECUTION_SECURITY_REVIEW.md`.

## Commands

The complete command surface. There is nothing else.

| Command | What it does |
|---|---|
| `cyberbrain version` | Print the installed package version. |
| `cyberbrain plan --goal <text>` | Build a roadmap from a goal and store it in `roadmaps.json`. Placeholder planner output; see the dead end below. |
| `cyberbrain run --id <id>` | Execute a roadmap's steps through identity -> policy -> permission -> approval -> sandbox -> audit. No model is called. |
| `cyberbrain approvals pending` | List pending human approval requests, oldest first. |
| `cyberbrain approvals show <id>` | Show one request in full, including the warning that an approval is not cryptographically bound to the code. |
| `cyberbrain approvals approve <id>` | Approve a pending request; unblocks an execution waiting in another process. |
| `cyberbrain approvals deny <id>` | Deny a pending request; the waiting execution fails. |
| `cyberbrain approvals history` | List recorded approval decisions, newest first. |
| `cyberbrain doctor check` | Read-only installation self-report (`--json`, `--strict`). |
| `cyberbrain doctor main` | Alias of `doctor check`. |

Exit codes are meaningful: a refused, failed or blocked run exits non-zero and prints no
success wording.

## Security chain and its honest limits

`run` dispatches each step through `InMemoryTaskDispatcher._authorize` and, for code,
`AuthorizedExecutionService`:

1. **Identity** — trust level; `UNTRUSTED` is denied.
2. **Scope** — the action must be in `ACTION_SCOPE_MAP` and the identity must hold the
   required scope. Built-in agents hold no scopes, so a code step stops here unless the
   operator passes `--scopes`.
3. **Policy** — `SAFE` mode, default deny, sensitive actions require approval.
4. **Approval** — a persisted request a human decides from a second terminal; timeout
   (300 s by default) and cancellation both close the action.
5. **Sandbox** — `bwrap --unshare-all --die-with-parent --new-session`, read-only `/usr`,
   fresh `/dev` and `/proc`, tmpfs `/tmp`, exactly one read-write workspace bind mount
   confined to `<data dir>/workspaces`, cleared environment, no network interface.
   Missing `bwrap` raises; nothing runs on the host.
6. **Audit** — 24 event types recorded at every step, allowed and refused alike.

What the sandbox does **not** do, stated by the project's own `EXECUTION_SECURITY_REVIEW.md`:
*"suitable for a constrained local prototype; NOT approved as a general-purpose
hostile-code sandbox."* Specifically: no seccomp filter, no Landlock/LSM, no cgroup, PID,
memory, disk or inode quotas; `RLIMIT_CPU/AS/FSIZE` are cooperative child-process limits,
not enforcement; no uid/gid pinning and no capability dropping; the full host `/usr`
(including site-packages) is readable and executable inside.

## Platform support

Linux only for execution. Bubblewrap is a hard runtime prerequisite — without it,
`cyberbrain run` refuses every step. On macOS and Windows you can install the package and
use `doctor` and `approvals`; `run` will not execute code there.

## Known limitations

1. **`plan` -> `run` is currently a dead end.** `plan` stores steps whose payload declares
   no `action`, and `run` refuses every step that has no declared action. No CLI command
   can currently produce a runnable roadmap; you must hand-write
   `<data-dir>/roadmaps.json`. The recipe is in [docs/quickstart.md](docs/quickstart.md).
   This is intentional — a step with no declared action has nothing to authorize — not a
   bug.
2. The planner produces a fixed placeholder plan; it does not reason about your goal.
3. Approvals are not cryptographically bound to the code that will run; nothing hashes the
   execution payload.
4. `AIFirewall` exists but is wired into nothing: it guards no runtime path.
5. `ModelGateway` / `ModelRouter` are library-only and unreachable from the CLI, and
   `ModelGatewayConfig` defaults to the cloud provider `litellm` with silent fallback,
   which contradicts the "never silently route local work to a cloud provider" promise if
   the library is ever called directly. Open risk.
6. Retention defaults to 90 days but pruning is never scheduled from the CLI. Deletion is
   logical, not secure erasure; the store is not encrypted at rest.
7. There is no audit query command. `AuditLog.query()` exists in the library only.
8. Configuration is a handful of environment variables, not a config file; `.env` files are
   never read.

A per-capability status table with file:line evidence is in
[docs/CAPABILITIES.md](docs/CAPABILITIES.md).

## Getting started

See [docs/quickstart.md](docs/quickstart.md): prerequisites, install, `doctor check`, a
runnable step, and the two-terminal approval flow.

## Configuration

Three store variables and one sandbox variable, documented in
[.env.example](.env.example). They are shell-exported values; the application never reads
`.env` files.

## Licence

Proprietary. See [LICENSE](LICENSE) — the licence text must still be supplied and legally
reviewed before any distribution.