Operation
corb run ~/Code/packet-loss --trust-config
Corb boots a VM, mounts the project at /work/packet-loss, and starts Pi in your terminal. Writable mounts write back to the host directory. The first run requires explicit acceptance of the effective configuration.
host guest micro-VM
------------------------ -------------------
workspace directories <---> /work/<name>
filesystem + network rules Pi + its processes
command policy <---> image-installed shims
credentials + audit log secret placeholders
A denied write
Attached guest shell; captured 9 October 2026.
/work/project $ printf 'overwrite\n' >> frozen.txt
/bin/sh: can't create frozen.txt: Permission denied
/work/project $ printf 'write exit: %s\n' "$?"
write exit: 1
/work/project $ cat frozen.txt
Original fixture.
The file stayed unchanged on the host. Read the policy and its audit record.
Boundaries
| Control | Enforcement | Limits |
|---|---|---|
| Filesystem | Host filesystem providers enforce mount access and per-path rules for all guest processes. | Writable mounts change real host files. Choose what to expose; host directories outside the mounts stay unavailable. |
| HTTP and credentials | Host mediation checks destinations and substitutes credentials only for their configured hosts. | The optional GitHub API gate needs configuration. Enabled WebSockets are opaque after upgrade. |
| Configured SSH / smart-HTTP Git | Host checks allowed hosts, repositories and push access independently of command shims. | Pushes are disabled by default. Checks cover configured SSH and recognized smart-HTTP routes, not all traffic to a Git host. |
Guest git / gh shims | Guest wrappers check arguments against fixed, host-generated tool policies. | Calling real binaries directly bypasses the shims. Other tools have no command filter. |
| Commit / push checks | Shim-collected payloads go to a host checker for selected secret patterns, file counts and path rules. | Direct binaries skip collection. Guest collection or transport failures proceed; fail-open = false covers internal host-checker errors only. |
Configure a writable project and a read-only reference. The security guide explains each control and its limits.
Documentation
| Document | Contents |
|---|---|
| Getting started | Requirements, build, credentials, first run. |
| Development walkthrough | Start a workspace, develop with Pi, review edits, keep history. |
| Workspaces | Named workspaces, sources, mounts, selection and trust. |
| Configuration | Global and workspace TOML, merge rules, credentials and trust. |
| Command reference | Run, inspect, attach, stop, and diagnose sessions. |
| Security and policy | Process, filesystem, network, and command controls. |
| Workspace layers | Pin, compose and share authenticated image inputs. |
| Planned improvements | Mandatory arguments and extensible command shims. |
Implementation status
Corb is not yet published to npm. The current runtime launches Pi with global and named workspace configuration.
Named workspaces and shareable image layers are implemented. Agent extensions and configured system-prompt append files are not implemented. The documentation describes the working commands and labels planned behavior explicitly.