Security model

The boundary

Each project gets its own Linux virtual machine (Apple Virtualization framework via Lima). The agent runs inside that VM as your user, with sudo unless network = "broker" or "offline" removed it (with the root-equivalent groups). The VM sees:

It does not see your home directory, Keychain, SSH keys, cloud credentials, other repositories, the host Docker socket or the host's processes. A kernel exploit inside the box lands in a throwaway Ubuntu VM.

Configuration trust

.corral.toml in a repository is written by whoever controls that repository — the code being sandboxed. The invariant is therefore:

Project configuration never runs on the host and never widens what the box can reach on the host.

Every config key has a trust class (internal/policy/trust.go; a test fails if a key is added without one):

The same test that enforces a trust class for every key is what keeps this table honest: a new key cannot ship without a decision about who may set it.

Per-project privilege has a legitimate home in ~/.corral/projects/<box>.toml — owned by you, outside the repository, so enabling the SSH agent for one project does not require enabling it for all.

A violation fails the load with every offending key listed — nothing is silently dropped, because a silently ignored ssh_agent = true is exactly what a hostile repository would hope for. A project file that is a symlink is refused. This closes the class of "the repo turns on its own privileges" completely for Corral, because unlike container-based tools there is no config key that executes anything on the host.

What the repository can make your Mac run

The project mount is a live view of the checkout on your Mac, so anything the agent writes there is also on your Mac. Most of it is harmless until you run it, and most of it shows up in a diff you review. Two places do neither:

Corral therefore shadows both inside the box (protect_git_metadata, default on, a project can only turn it on): at every boot and again before every session, a systemd unit bind-mounts a guest-local copy of .git/config and an empty, guest-owned .git/hooks over the mounted ones — for the top-level repository and each submodule under .git/modules. Commits, branches, fetches and pushes work as usual; hooks the agent installs run in the box only. If the shadow cannot be applied, the session refuses to start rather than run without it.

One visible cost: git rewrites .git/config atomically by rename, which cannot replace a mountpoint, so git config --local, git remote add/set-url, git branch -u and other commands that write the repository config fail inside the box with could not write config file .git/config: Device or resource busy. Make those changes on the host (they are yours to make), or use git config --global for box-local preferences. The config copy is refreshed from the host at every boot and session start.

What this does not cover — it is a mitigation for mount mode, not a boundary:

• Makefile, package.json scripts, .pre-commit-config.yaml, .vscode/tasks.json, .envrc and similar: they run on your Mac when you (or your editor) invoke them, and they are in the diff. Read the diff before running the build.
• A submodule added during a session: it is shadowed at the next session start.
• .gitattributes alone cannot execute anything; the drivers it names live in .git/config, which is shadowed.

The full answer is a checkout the host never runs from — source = "clone" — or readonly_project = true; both make the shadow unnecessary and it is skipped.

Known cross-boundary paths

These are the ways the box reaches the host today, by design, and what limits each. They are the items to weigh before running an untrusted repository.

What the agent can still do

• Modify or delete the project directory — that is the point of mounting it. Use git, readonly_project = true or corral snapshot for rollback of the VM disk.
• Use the network: by default the guest has outbound internet and can reach the Mac at host.lima.internal and the LAN, like a Docker container can. Nothing on the Mac is exposed unless a service listens on all interfaces. network = "offline" rejects all egress inside the guest except the Lima gateway subnet (192.168.5.0/24: the Mac and DNS) via nftables, and removes the box user's sudo and root-equivalent groups (docker, lxd, incus-admin, disk; the docker socket is made root-only too) so the agent cannot lift it — before any repository provision script runs; the rule is applied after provisioning finishes and re-applied before every session (the session refuses to start otherwise). This is enforced inside the boundary, so it is weaker than a host-side allow-list (planned) — but with sudo gone it takes a kernel or guest-agent bug to undo, not a shell command. Ubuntu's unattended apt timers are masked at provisioning: nothing installs packages into a box except provisioning and the agent, on purpose.
• Exfiltrate anything it can read: the project and any forwarded secret. Forward the narrowest token that works (env_from_host).
• Undo in-guest controls with sudo — the hide shadow and the git-metadata shadow included — unless network = "offline" or "broker", which remove it together with every group that is root by another name (docker: a container can mount /). The VM is the boundary; in-guest policy is hygiene against accidental exposure (an agent cat .env-ing into a prompt), not a defence against a hostile one.

Secrets

• Nothing is forwarded implicitly except the agent's own auth variables (ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN) and terminal variables (TERM, LANG, TZ). no_env_passthrough = true disables even that.
• env_from_host = ["GH_TOKEN=CORRAL_RO_TOKEN"] gives the box a narrower credential under the name tools expect. It fails closed: if CORRAL_RO_TOKEN is unset the box does not start, so the broader GH_TOKEN can never slip in.
• git_tokens = { "git.example.com" = "GITLAB_TOKEN" } installs a git credential helper that offers the token only to that host over HTTPS.
• Values travel inside the SSH channel (SendEnv/AcceptEnv); they are not on any command line and never written to disk by Corral. The audit log records variable names only.
• The Claude login created with /login inside a box is stored in ~/.corral/agents/claude/.credentials.json (mode 0600) on the Mac — outside ~/.claude, so the host Claude Code login is never read or modified. corral agents logout claude removes it.

Supply chain of the box itself

There is no Corral container image or download server.

Provision scripts (ours and a project's provision list) are re-run by Lima on every boot, not only at creation — that is what makes a golden clone's first boot cheap. Two consequences: every script must be idempotent, and a repository's provision scripts run again each time its box starts (as the box user; as root only if the script says # corral: system and the box is not offline). They still cannot touch the host — the box is the boundary — but review them as you would a Makefile.

npm inside the box is configured with min-release-age = 7 days to avoid freshly published packages (the window most hijacked releases live in) — override with CORRAL_NPM_MIN_RELEASE_AGE in a provision script if a project needs to.

Audit

Every launch, exit, create, stop, idle-stop, delete, golden-build and golden-prune is appended to ~/.corral/logs/sessions.jsonl with box, project, agent, argv, whether prompts were skipped, forwarded variable names, exit code and duration. corral audit renders it. Guest-side controls log to the box's journal (journalctl -u corral-git-shadow, -u corral-hide, -u corral-offline).

What a box tried to reach. Containment is not detection: a box running a compromised dependency may attempt an outbound connection that the broker refuses, and the refusal alone is the signal worth keeping. For every box with a broker (network = "broker", or api_brokers), the broker child on the Mac appends each attempted destination to ~/.corral/logs/egress-<box>.jsonl — host:port and whether it was allowed — together with every api_brokers call (method, path, upstream status) and a marker at each session start and end. Only corral sees attempts: a caller knows what it permitted, which is a different fact. corral egress <box> shows the destinations deduplicated with counts (denied first); --log prints the record in order; --json is for scripts. The log holds names only, never payloads or bodies; it is kept for 14 days after the box is deleted and removed by corral gc. Direct connections that bypass the proxy never reach the broker — they are rejected by the in-guest nftables rule and are therefore not in this log; that gap is the funnel's, not the record's (see the hardening tiers in ARCHITECTURE.md).

Reporting

Security issues: report privately via GitHub — Security → Report a vulnerability on https://github.com/corral-sh/corral (GitHub private vulnerability reporting). Please do not post exploits in public issues.