corb a small tool / a real boundary

Run Pi in a restricted micro-VM.

Choose which directories Pi can read or write, and which network hosts it can contact. Corb runs the agent in a Gondolin micro-VM and keeps model credentials on the host.

Build Corb and run Pi

Experimental. Build from source on Linux or macOS.

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

ControlEnforcementLimits
FilesystemHost 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 credentialsHost 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 GitHost 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 shimsGuest wrappers check arguments against fixed, host-generated tool policies.Calling real binaries directly bypasses the shims. Other tools have no command filter.
Commit / push checksShim-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

DocumentContents
Getting startedRequirements, build, credentials, first run.
Development walkthroughStart a workspace, develop with Pi, review edits, keep history.
WorkspacesNamed workspaces, sources, mounts, selection and trust.
ConfigurationGlobal and workspace TOML, merge rules, credentials and trust.
Command referenceRun, inspect, attach, stop, and diagnose sessions.
Security and policyProcess, filesystem, network, and command controls.
Workspace layersPin, compose and share authenticated image inputs.
Planned improvementsMandatory 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.