cplt

Sandbox for AI coding agents. Runs Copilot CLI, Claude Code, OpenCode, Gemini CLI, Antigravity, Pi, goose or a plain shell inside a kernel-level sandbox, with git and gh guards and sandbox policy committed to the repository.

Why cplt?

AI agents execute arbitrary code. A compromised agent, whether through prompt injection, a supply chain attack, or a malicious MCP server, can read ~/.ssh, push to main, merge PRs, or exfiltrate your code, unless the OS itself says no.

cplt gives you kernel-level enforcement with team-configurable policy:

• Per-repo policy in .cplt.toml, committed to version control, so it is tamper-proof and auditable
• Deny by default for credentials, secrets, and sensitive files
• Command-level git and gh interception: pushes to the default branch, force pushes, merges, and releases are blocked, feature branches stay open
• Outbound network filtering with an audit log
• No Docker, no VMs. One binary that runs on a locked-down laptop
• Zero-config start for developers, with escape hatches when a build genuinely needs one

Table of contents

• Quick start
• What it blocks
• How cplt compares
• Install
• Usage
• Configuration
• Architecture
• Security
• Network and proxy
• Command guards
• Known impacts
• Limitations
• Contributing
• References

Detailed docs: Configuration · Proxy & domain filtering · gh command guard · git command guard · Known impacts · Security details · Security model

Quick start

Other agents and sandbox commands:

Team rollout

What it blocks

The sandbox blocks access to credentials and secrets in the kernel. Command guards block destructive operations. Every restriction applies to the agent and to every process it spawns.

That table is a summary. The sandbox also allows access to system files (SSL certs, /etc/hosts), temp directories (read and write, no exec), and system tool paths (/usr/bin, /opt/homebrew). Run cplt --print-profile for the complete SBPL rules.

For the full security model, threat analysis, and test strategy, read SECURITY.md.

How cplt compares

Codex CLI's sandbox

cplt is not stronger everywhere. Codex CLI has Linux namespace isolation today, and it already exposes explicit sandbox modes such as read-only and workspace-write. cplt does not yet have that mode matrix.

Docker-based sandboxes

Docker still gives you stronger isolation in some environments, especially if you want a fully separate filesystem and process namespace. cplt trades that for lighter setup and tighter integration with the machine you already develop on.

VS Code agent mode permissions

Tools such as VS Code agent mode rely mainly on UI permissions. cplt enforces its restrictions in the kernel, so the agent cannot talk its way around them with a prompt or a modified instruction. That matters most for CLI agents and credential exposure:

• cplt works outside the IDE
• env vars are filtered before the agent starts
• sensitive files can be blocked even when they live inside the repo
• the same restrictions apply to child processes

Claude Code's sandbox (Anthropic Sandbox Runtime)

Anthropic Sandbox Runtime (srt) is the sandboxing layer used by Claude Code. Same high-level approach as cplt, macOS Seatbelt plus kernel-level Linux enforcement plus an HTTP proxy, different implementation.

cplt is more secure out of the box: env filtering, credential protection, DNS rebinding checks, lifecycle script blocking. srt is more flexible: SOCKS5, TLS inspection, per-request callbacks, library embedding. The Linux backend choice matters. bwrap needs workarounds on Ubuntu 24.04+ because of AppArmor userns restrictions, while Landlock requires kernel 5.13 or newer but has zero external dependencies.

GitHub Copilot CLI's own sandbox

Copilot CLI has shipped with a local sandbox since June 2026, included in the standard seat. It runs shell commands through Microsoft MXC with restricted filesystem, network and system access, on macOS, Linux and Windows. /sandbox enable turns it on.

If that covers you, use it. It costs nothing extra, and it runs on Windows, which cplt does not.

Two things it does not do.

Policy lives with the administrator, not the repository. Enterprises set sandbox policy through Intune or another MDM. Nothing sits next to the code, so a rule that matters for one repository cannot follow it to a contributor, to CI, or to a laptop the MDM does not manage. In cplt the policy is .cplt.toml in the repository. Reviewers see changes to it in the pull request, and the file can tighten a developer's own configuration but never loosen it.

It confines the process, not what the process does with credentials it holds. The /sandbox tabs cover the filesystem, the network and system capabilities, and inside a Git repository the agent is granted read and write on .git by default. A sandboxed agent still has your gh token and your push access. Pushing a branch, merging a pull request and deleting a repository are all well-formed API calls from an authorised client, and a filesystem or network rule has no opinion about them. cplt wraps git and gh instead. The agent commits, branches and rebases freely. gh pr merge, gh repo delete and gh release create are blocked by default. So is git push to main/master; feature-branch pushes still work, because protect_default_branch_only is on. Set it to false to block every push, or git_guard.mode = "warn" to only warn.

Running both is reasonable. MXC confines the process. The guards decide what the agent may do with the credentials it holds.

Honest gaps

• macOS has the strongest file-level enforcement today. Linux coverage is improving but not identical.
• cplt does not yet offer simple read-only / workspace-write / full-access policy presets.
• If you want full container isolation, cplt is not trying to replace Docker.

Install

Homebrew (recommended)

mise

mise picks the right release asset for your platform and verifies its build provenance attestation.

Pin the version. Our version strings are not comparable semver — they carry leading zeros and two hyphens — so mise latest can resolve to an older release than the newest one (navikt/copilot#818).

apt (Debian/Ubuntu, recommended on Linux)

navikt/apt is a signed archive served over GitHub Pages, carrying cplt and nav-pilot for amd64 and arm64:

It is a plain apt repository mirroring our releases, not a distribution package with its own maintainer. Its publish job runs hourly and pulls the newest .deb from each tool's latest release, so a release cut minutes ago takes up to an hour to become installable that way.

The package puts the binary at /usr/bin/cplt, and upgrades ride sudo apt upgrade from then on. cplt update refuses to touch an apt install and points at sudo apt upgrade instead: replacing the binary behind dpkg's back would be undone by the next apt run.

Without the archive, the same .deb is a release asset:

curl | bash

For distributions that are not Debian derivatives, and for CI:

Options:

Download from releases

Grab the latest build for your platform from GitHub Releases:

Every release binary carries a build provenance attestation. Verify it:

Build from source

Or with mise:

mise run install and manual builds put cplt in /usr/local/bin/cplt. If you also have the Homebrew build at /opt/homebrew/bin/cplt, put /usr/local/bin first in PATH so your development build wins:

Or just run /usr/local/bin/cplt explicitly and skip PATH resolution entirely.

Windows (WSL2)

cplt has no Windows sandbox backend. Enforcement is Apple Seatbelt on macOS and Landlock LSM on Linux, so there is nothing to run natively on Windows. The supported route is WSL2, where cplt is an ordinary Linux install and the sandbox is kernel-enforced. Every Microsoft kernel branch builds CONFIG_SECURITY_LANDLOCK=y and lists landlock first in CONFIG_LSM (config-wsl), shipped since kernel 5.15.57.1, and WSL's default kernel command line sets no lsm= override.

In PowerShell, once:

Everything below runs inside the distro (wsl, or the Ubuntu profile in Windows Terminal), not in PowerShell:

Do not install Copilot CLI on the Windows side. With interop on (the default), the Windows PATH is appended to the distro's, so a Windows-side npm install -g @github/copilot turns up inside the distro as /mnt/c/Users/<user>/AppData/Roaming/npm/copilot. That is a Windows install reached through interop. It cannot run in the Linux sandbox, and the npm shim execs a node that the distro will not have unless you installed one there too. The symptom used to be an unrelated runtime-extraction error. cplt now names the cause when it resolves an agent under /mnt/<drive>/ and it is running under WSL, and cplt doctor reports it as a failing check instead of passing (#188). WSL is detected from kernel-owned state, either /run/WSL or the kernel name in /proc/sys/kernel/osrelease and /proc/version, not from WSL_DISTRO_NAME, which is absent under sudo and in systemd units and which any process can set. On a plain Linux box /mnt/c is left alone. It is an ordinary mount point there.

That check has two limits, both deliberate. It keys on the default automount root, so if you have relocated it ([automount] root in /etc/wsl.conf) the Windows-side install is not recognised and you get the old, less helpful failure with the path in it. And turning interop off stops the Windows PATH from leaking in but does not unmount /mnt/c.

Kernel and Landlock ABI. Current WSL (2.7.x and later) ships Linux 6.18, which gives Landlock ABI 7 — everything cplt uses except the unix-socket connect() right, which needs ABI 9 (kernel 7.1). An install still on the 6.6 kernel line gets ABI 3: filesystem rules are enforced, but TCP port rules (ABI 4), ioctl restriction (ABI 5) and signal/abstract-socket scoping (ABI 6) are not available, and network filtering falls back to the CONNECT proxy. wsl --update moves you forward. cplt doctor prints the kernel version and the ABI it found, which is the check that matters on your machine.

Do not disable Landlock in .wslconfig. A [wsl2] kernelCommandLine with an lsm= list that omits landlock, or a custom [wsl2] kernel= built without CONFIG_SECURITY_LANDLOCK, removes the kernel enforcement cplt depends on, and cplt doctor will report Landlock as unavailable.

Keep the project in the Linux filesystem. Work in ~/src/... inside the distro rather than /mnt/c/Users/.... Microsoft's own guidance is that cross-OS file access is markedly slower, and /mnt/c is served over 9p by default as of WSL 2.9.x (virtiofs is opt-in via [wsl2] virtiofs=true). More to the point, we have not verified how Landlock enforces rules on that mount. The kernel documents no exclusion for network- or FUSE-backed filesystems, only pipes, sockets and nsfs, and Landlock's own test suite exercises 9p and FUSE, so we expect it to work. Nobody here has confirmed it. Treat a project under /mnt/c as unproven rather than supported.

Bubblewrap. Ubuntu 23.10+ blocks unprivileged user namespaces through kernel.apparmor_restrict_unprivileged_userns, which breaks bwrap. That sysctl comes from an Ubuntu kernel patch that is absent from the Microsoft kernel, so the optional Bubblewrap layer is expected to work on Ubuntu-under-WSL2. That is inference from the kernel source, not something we have run. If bwrap fails there, please say so in #189. cplt's own seccomp filter is a plain PR_SET_SECCOMP BPF program, which stacks on top of the filter WSL installs in every process.

Not yet verified on a real WSL2 install. Verified from source: Landlock is compiled in and first in CONFIG_LSM on the Microsoft kernel; the /mnt/<drive>/ detection, the WSL signals it uses, and their error text; that cplt doctor fails on such an agent and prints kernel + Landlock ABI; the 5.13+/6.7+ requirements; and that install.sh installs the Linux release binary. Still unverified by anyone here: how Landlock behaves on /mnt/c, whether Bubblewrap works under WSL2, the exact package versions your distro release ships, and the sequence above end to end. If you run it, please report what actually happened in #189.

Shell setup (recommended)

By default you get the sandbox by typing cplt. To make plain copilot run sandboxed too:

That detects your shell, appends the alias to your rc file, and prints what it did. Run it as many times as you like, it will not add duplicates.

--agent picks which command gets the alias, and every agent cplt can launch is available:

Each install adds to your rc file rather than replacing what is there, so you can sandbox as many agents as you use. Without --agent you get copilot, which is what the flag has always installed.

--agent antigravity installs aliases for both antigravity and agy, since either name starts the same agent.

Restart your shell or source the file to activate.

There is no alias for --agent shell: there is no shell binary to shadow. Type cplt --agent shell for a sandboxed shell, or cplt exec -- <command> for a single command.

Why each alias names its agent. alias opencode=cplt would not do what it looks like. Plain cplt picks its agent from --agent, then the config file, then whatever it finds in PATH — and PATH detection prefers copilot. Typing opencode would sandbox Copilot instead, with nothing on screen to say so. The alias passes --agent so the command you type is the agent you get.

Why an alias instead of a symlink? cplt and Copilot CLI install into the same Homebrew bin directory (/opt/homebrew/bin/), and only one file named copilot can live there, so a symlink would conflict. An alias sidesteps that. The real copilot binary stays in PATH where cplt can find and wrap it, and the alias redirects your command.

Note: cplt refuses to nest. If it detects that it is already running inside a sandbox (via the __CPLT_WRAPPED environment variable), it will not launch again. Read-only subcommands such as --print-profile and cplt doctor still work inside an existing sandbox.

Usage

Everything after -- goes straight to the agent process (copilot, opencode, gemini, antigravity, pi, claude, goose, dsh, or shell).

Policy presets

A preset sets a baseline for the five main sandbox toggles with one flag instead of a list of them. Individual flags still win over the preset, so --preset permissive --no-allow-tmp-exec does what it says. Also settable as [sandbox] preset = "..." in config.

Full preset matrix and resolution order: docs/configuration.md.

File access

The project directory is the writable workspace, plus a narrow allowlist needed for auth, runtime, and tooling (see the table above). The kernel blocks everything else, SSH keys and cloud credentials included.

Environment variables

cplt sanitizes the child environment by default. Only safe variables pass through, and cloud credentials, database URLs, and package tokens are stripped. It also injects hardening variables that block npm/yarn/pnpm lifecycle scripts (postinstall hooks, the number one supply chain attack vector), disable git commit and tag signing (since ~/.ssh and ~/.gnupg are unreachable inside the sandbox), and opt out of developer tooling telemetry (DO_NOT_TRACK=1, NEXT_TELEMETRY_DISABLED=1, TURBO_TELEMETRY_DISABLED=1, CHECKPOINT_DISABLE=1, and others).

What passes through:

Prefix allowlist with secret-suffix protection. A variable matching an allowed prefix such as COPILOT_* or YARN_* still gets dropped if it ends in a secret-bearing suffix: _TOKEN, _AUTH, _SECRET, _SECRET_KEY, _KEY, _PASSWORD, or _CREDENTIALS. So COPILOT_DEBUG passes and COPILOT_API_KEY does not.

Always blocked: AWS_*, AZURE_*, NPM_TOKEN, DATABASE_URL, VAULT_TOKEN, SSH_AUTH_SOCK, Docker vars, CI tokens, and anything not in the allowlist.

Sandbox toggles

Supported runtimes

cplt auto-discovers installed tools and writes sandbox rules to match. Generally only directories that exist on disk get rules, so there are no phantom paths. On macOS, writable app directories are included when discovered even if they do not exist yet, so they can be created on first use. Linux cannot allow a write to a non-existent path, so creation has to happen outside the sandbox there.

Run cplt doctor to see whether cplt will work here for your agent, and cplt doctor --verbose for everything it detected on your machine.

Debugging

Session flags

These translate into the agent's own session flags, so you do not need a -- separator.

--continue and --resume are mapped for OpenCode, Antigravity, and Claude Code too:

¹ Neither OpenCode nor Antigravity has an interactive session picker, so a bare --resume means "continue last session". Claude Code has one, so it maps straight across.

--remote and --name are Copilot-only. Pi and shell mode get no translation at all, so all four flags are dropped for them. Auto-resume is a separate mechanism: when you invoke cplt with no pass-through args and no session flags, it appends --resume for you, and that applies to Copilot only.

Combine them with sandbox flags and -- pass-through args:

Agents

Pick one with --agent <name>, or make it the default with cplt config set sandbox.agent <name>. Copilot, OpenCode, and Antigravity are auto-detected from PATH in that order when you do not name one.

• Pi, Claude Code, goose, and DeepSeek Harness are never auto-detected. pi and dsh are generic binary names that could collide with something else on your machine, and Claude Code has to be chosen on purpose.
• Third-party API keys are opt-in. ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN and the Bedrock/Vertex routing vars (CLAUDE_CODE_USE_BEDROCK, AWS_BEARER_TOKEN_BEDROCK, CLAUDE_CODE_USE_VERTEX, ANTHROPIC_VERTEX_PROJECT_ID, GOOGLE_CLOUD_PROJECT) never pass through unless you name them with --pass-env.
• Subscription auth needs no env var. OpenCode's /connect device flow stores its token in ~/.local/share/opencode/auth.json, and Claude Code's OAuth token lives in ~/.claude (.credentials.json on Linux) or the macOS Keychain. Both are reachable inside the sandbox, so cplt does not nag about a missing API key for either.
• OAuth browser flows need --allow-browser when a sign-in prompt appears. That covers Antigravity; every other agent here uses a device flow that prints a code and a URL and needs no browser. The flag lets the agent launch any application outside the sandbox and cannot be narrowed to URLs, so turn it on for the sign-in and off again — see the flag table and docs/security.md.
• Claude Code auto-update is disabled with DISABLE_AUTOUPDATER=1. Claude Code has no --no-auto-update flag, self-updating inside the sandbox is a persistence vector, and it would fail against read-only install paths anyway.
• CLAUDE_CONFIG_DIR is honored. When it is set, cplt grants that directory instead of ~/.claude and passes the variable through, so a relocated config root keeps working.
• OpenCode is an officially supported Copilot client, so your existing Copilot subscription works with /connect inside OpenCode.

Per-agent config dirs, Keychain use, exec permissions, and env isolation are in SECURITY.md.

goose support

cplt can sandbox goose, the open-source AI agent (binary goose). Verified against goose 1.48.0.

Security notes for goose:

• Not auto-detected: select explicitly with --agent goose or set sandbox.agent = "goose" in config
• Provider-agnostic: goose routes model traffic to a user-configured provider (Anthropic, OpenAI, Google, Databricks, OpenRouter, …). Common provider keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, AZURE_OPENAI_API_KEY, GOOGLE_API_KEY, DATABRICKS_HOST/DATABRICKS_TOKEN, GROQ_API_KEY, OPENROUTER_API_KEY, XAI_API_KEY, AWS_BEARER_TOKEN_BEDROCK) are recognized auth hints and must be passed via --pass-env. goose reads GOOGLE_API_KEY, not GEMINI_API_KEY. Any provider outside this subset still works: name its variable with --pass-env
• No default domains: goose contacted no host of its own in an --observe-domains capture, so its built-in allowlist is the shared package-registry base only. Add your provider's domain via allowed_domains before enabling --default-allowlist
• Keychain is granted, and you can avoid it: goose stores provider secrets in the macOS login Keychain by default, so cplt grants it — but that grant is broader than goose's own entry (#242). GOOSE_DISABLE_KEYRING=1 makes goose use a secrets.yaml in its config dir instead, and passing the key with --pass-env avoids stored secrets altogether. On Linux goose uses the D-Bus Secret Service, which the Keychain grant does not affect
• Config dir is read-only: ~/.config/goose/config.yaml declares extensions: entries whose cmd goose spawns on every session start, so a writable config dir is a host-persistence vector. Normal sessions do not write it; /mode changes and persisted tool permissions do not survive a sandboxed run. Reconfigure with goose configure outside cplt
• goose's data (~/.local/share/goose/) and state (~/.local/state/goose/) dirs are writable, with exec denied. goose uses these XDG paths on macOS too, and honours the XDG_* overrides there
• --continue and bare --resume map to goose session --resume; --resume=ID to goose session --resume --session-id ID; --name X to goose session --name X. These are subcommand flags, so cplt injects the session subcommand with them. --remote is ignored (no goose equivalent)

DeepSeek Harness support

cplt can sandbox DeepSeek Harness (binary dsh), the plugin-oriented agent harness from DeepSeek. Upstream ships it as a developer preview and its own SAFETY.md says not to rely on its controls as the only boundary, which is the case cplt exists for.

Security notes for DSH:

• Not auto-detected: select it with --agent dsh (aliases deepseek, deepseek-harness) or set sandbox.agent = "dsh". dsh is a short, generic command name that could belong to something else on your machine
• Turn DSH's own sandbox off inside cplt: DSH wraps every shell and file tool call in its own process sandbox — Seatbelt on macOS, bwrap or Landlock on Linux. Neither nests inside cplt. macOS does not support nested sandbox-exec calls (the same limitation that makes cplt turn Gradle's inner sandbox off, see Limitations), and bwrap builds its namespace with unshare, which cplt's seccomp filter denies. cplt is the enforcing boundary either way, so pick DSH's shipped danger-full-access permission preset for sandboxed sessions. Leave the inner runner on and tool calls fail with a sandbox runner error rather than a task error
• One home root, and cplt follows the override: DSH keeps sessions, settings, cache and profiles under $DSH_HOME (~/.dsh by default). DSH_HOME is on the env allowlist, so the child resolves the same root cplt grants. A value pointing at a system root or your home directory is refused before launch, the same veto CLAUDE_CONFIG_DIR goes through
• Host-persistence guard: $DSH_HOME/cordis.patch.yml, the home-level overlay the Loader reads at boot, is write-denied. $DSH_HOME/profiles/ stays writable because DSH rewrites each profile's cordis.yml include-root on every boot, so a per-profile cordis.patch.yml and installed plugins are a documented residual — do profile and dsh plugin edits outside cplt, and always launch dsh through cplt so anything planted still runs sandboxed
• Default domains: deepseek.com only. The shipped dsh-llm-deepseek adapter defaults to https://api.deepseek.com. Point DEEPSEEK_BASE_URL at a gateway and you have to add that gateway's domain via allowed_domains
• Auth: pass the key with --pass-env DEEPSEEK_API_KEY, or keep it in $DSH_HOME/.env. A key saved through DSH's own models UI lands in $DSH_HOME/.credentials.yaml, inside the same writable root. The macOS Keychain is denied, so git push over HTTPS needs gh's token in hosts.yml or --pass-env GH_TOKEN

Shell mode

Run a plain sandboxed shell with no AI agent and the same restrictions. Handy for testing build tools, debugging sandbox issues, or just working carefully by hand.

The same deny-by-default rules apply: filesystem isolation, network restrictions, env sanitization. Shell config directories (fish variables and history, zsh history) stay writable.

For a single command, cplt exec is cleaner than cplt --agent shell -- -c 'cmd'.

Exec mode

Run any command inside the sandbox without starting an agent. No startup banner, no confirmation prompt, so it suits scripts, pipes, and shell aliases.

Every top-level cplt flag applies: --project-dir, --allow-read, --deny-path, --with-proxy, --pass-env, and the rest. Add --no-quiet to see the full sandbox configuration summary before the command runs.

Examples

Configuration

Configuration happens at two levels: global, for developer preferences, and per-repo, for team policy.

cplt settings is the interactive editor, with Effective, Global, and Repository views, search, staged changes, and an explicit confirmation before it saves anything security-sensitive. cplt config stays the stable non-interactive interface for scripts and CI. Repository proposals are still committed and approved separately with cplt trust. The editor never commits or auto-approves them.

Precedence runs CLI flags, then the global config file at ~/.config/cplt/config.toml, then built-in defaults. Per-repo config in .cplt.toml is a separate layer rather than a rung on that ladder: [deny] tightens unconditionally, and approved permissions are additive only, so a repo can enable a feature but can never switch off something set by a CLI flag or global config.

A .cplt.toml in the repository root carries team policy:

cplt reads it from git HEAD, so the agent cannot tamper with its own policy mid-session, and trust approvals are pinned to the file's content. An uncommitted .cplt.toml grants nothing until it is committed, though its [deny] keys still apply. In CI and scripts, where nobody can answer a prompt, --accept-repo-config approves the committed file's proposals for that one run without persisting any trust. cplt init writes one for you by detecting the project's tooling:

It knows JVM (Gradle/Maven), Node.js, Docker, Python, Rust, Go, Playwright, Spring Boot, Ktor, TestContainers, Next.js, Vite, Flyway, Cypress, and environment secrets from .env.example. Dangerous permissions come out of the generator with a risk warning attached. --global looks at machine-level things instead: Playwright browsers, GPG signing, registry credentials, alternative agents.

Some keys are global-only and rejected from .cplt.toml because they are machine-specific or a local preference: sandbox.agent, sandbox.quiet, sandbox.yes, sandbox.validate, sandbox.scratch_dir, sandbox.pass_env, sandbox.inherit_env, sandbox.allow_cache_exec, sandbox.allow_cache_exec_any, proxy.enabled, proxy.port, proxy.log_file, proxy.log_level, proxy.blocked_domains, proxy.allowed_domains, and every [gh_guard] and [git_guard] key.

Full details, including the trust model, path expansion rules, and the complete config file reference: docs/configuration.md.

Architecture

The security model is a deny-by-default filesystem with kernel enforcement. On macOS, and on Linux with kernel 6.7+ (Landlock ABI v4), the network is restricted to port 443 by default, with --allow-port for extras. On older Linux kernels the CONNECT proxy provides that restriction instead, which is why it is enabled by default. SSH agent access and localhost outbound are blocked in the kernel on macOS. On Linux neither is: port-based Landlock rules cannot tell localhost from a remote host, and unix socket connect() is not gated by Landlock below kernel 7.1, so apart from the sockets bubblewrap masks the withheld SSH_AUTH_SOCK is the only thing standing between the agent and your loaded keys. The profile generator discovers your environment (cplt doctor --verbose shows the same probe results) and emits rules only for tool directories that actually exist on disk. Fewer rules, tighter sandbox.

• macOS: a Seatbelt/SBPL profile is generated and handed to sandbox-exec
• Linux: Landlock LSM rules plus a seccomp-BPF filter, applied via pre_exec (kernel 5.13+, TCP port filtering on 6.7+)

Internals and module layout: docs/architecture.md. Threat model, defense layers, and honest gaps: SECURITY.md.

Security

One binary, minimal dependencies, no runtime services, no telemetry. Three defense layers, with clear boundaries between them:

What cplt protects against:

• Secret exfiltration (SSH keys, cloud credentials, .env files): kernel-blocked
• Unauthorized code execution from temp dirs: kernel-blocked
• Persistence via cache-dir binaries: kernel-blocked, since those dirs are denied exec
• Persistence via git hooks in the project: .git/hooks is write-denied at the kernel on macOS. On Linux, with Landlock and no Bubblewrap, it stays writable, and cplt's own parent-side git then runs with core.hooksPath=/dev/null so it never executes a planted hook, though a git you run yourself still will
• Persistence via package-manager tool dirs that are both writable and executable (mise shims, PNPM_HOME, ~/.deno/bin, ~/.bun/bin): write is granted there so pnpm add -g and friends work in-sandbox, so an agent can leave a binary behind that a later shell picks up off your PATH
• A planted binary hijacking the agent cplt launches: at launch and audit, cplt resolves the helpers it runs itself (git, bwrap, sandbox-exec, mise, and the gh it reads a token from) from fixed system directories rather than PATH, but the agent binary itself runs from wherever it was discovered, which for an npm-global install is commonly under a writable mise or node tree. cplt cannot resolve it from a fixed directory — it legitimately lives where your version manager put it — so it checks the resolved path against the write rules the sandbox is about to apply and warns at launch, naming the binary and the writable tree, then proceeds
• cplt doctor: its --version probes run each agent binary it finds on your PATH, in the parent, so a planted one executes there — the same discovered-path exposure as the launch above, which is why doctor is a report and not a boundary. Its gh check is resolved from the trusted directories and its kernel-release read spawns nothing at all
• Data exfiltration to unauthorized domains: proxy-blocked
• Accidental pushes to main and PR merges without review: guard-blocked

What cplt does not protect against:

• Malicious code already inside the project directory. The agent has full read/write there
• Logic bugs the agent introduces. You still review the code
• A sophisticated adversary bypassing the command guard. Use server-side branch protection
• Network attacks on allowed domains. If github.com is allowed, the agent can read and write there
• macOS Keychain access, for agents that store auth there. Contents are password-protected, and sandbox.keychain_substitute can trade the grant away where an agent has another credential

Our priorities, in order: correct (every claim is tested, every edge case has a CVE or research reference), transparent (SECURITY.md hides nothing), simple (one binary, zero config required, sane defaults), and useful (get out of the way and let the agent work, safely).

More: docs/security.md · SECURITY.md

Network and proxy

The proxy is on by default. All outbound traffic from Copilot CLI, gh, and curl goes through a localhost CONNECT proxy via HTTP_PROXY/HTTPS_PROXY and NODE_USE_ENV_PROXY=1. It listens on an OS-assigned ephemeral port, so nothing collides. You get connection logging in real time, domain blocking, domain allowlisting, a persistent audit log, and the same port policy the sandbox enforces (443 plus anything in allow.ports).

--observe-domains-out <FILE> writes the observed set one domain per line, and --proxy-upstream-no-proxy <HOST> lists hosts to reach directly instead of through the upstream.

Proxy-forced mode is opt-in. It restricts kernel egress to the proxy port so a socket opened directly, or an env -u HTTPS_PROXY, cannot slip past. Enforcement is full on macOS, which pins to localhost:<proxy_port>. On Linux it blocks direct TCP :443, and a seccomp rule permits only SOCK_STREAM with protocol 0 or IPPROTO_TCP for AF_INET/AF_INET6, so UDP, raw, SCTP and DCCP are closed too — at the cost of anything that opens such a socket, not only code that sends UDP. What remains is a port-based residual, evil.com:<proxy_port>, until #114.

Outside proxy-forced, Linux does not restrict UDP. Landlock's network rights are TCP-only until ABI v10, cplt handles AccessNet::ConnectTcp alone, and the seccomp rule above is deliberately not applied — denying SOCK_DGRAM there would break getaddrinfo(3), and so all DNS, for every non-proxied tool. Outbound UDP to any host, inbound UDP bind, DNS tunnelling and QUIC/HTTP-3 are therefore unmediated in default mode, and the CONNECT proxy carries TCP only, so none of it appears in the proxy log. macOS restricts UDP in default mode but does not route it either: remote ip "*:443" covers UDP, so QUIC/HTTP-3 on 443 leaves without touching the proxy there as well. Under proxy.forced the proxy log is a complete record of egress on macOS. On Linux it is complete except for the evil.com:<proxy_port> residual above, which does not traverse the proxy and so does not appear in its log.

Both lists match the same way: example.com covers the exact domain and every subdomain, matching is case-insensitive, and trailing dots are stripped. Blocklist and allowlist files are re-read every five seconds, so you can edit them live. Localhost traffic bypasses the proxy via NO_PROXY and never appears in the audit log. --proxy-timeout <SECONDS> bounds request and header reads (default 60) and does not tear down established CONNECT tunnels, which may idle for up to an hour.

Every proxy flag, domain-filtering detail, upstream corporate-proxy chaining, and the connection log format: docs/proxy.md.

Command guards

Enable them and cplt intercepts gh and git through wrapper scripts in $PATH:

This is Layer 3, a soft barrier. It stops a compliant agent from doing something destructive by accident. For a hard boundary, lean on the kernel sandbox and server-side branch protection.

With the gh guard on, cplt also caches the GitHub token at launch and serves it once through the gh auth token callback, then deletes the cache. That cuts accidental and environment-based leakage. It is not a boundary against a hostile agent, because the cache lives in the agent's own TMPDIR and an agent that reads it before the legitimate consumer still gets the token. SECURITY.md has the full statement on block_auth_token.

Full behavior: docs/gh-guard.md · docs/git-guard.md

Known impacts

The sandbox blocks some workflows on purpose. The common ones and their fixes:

Playwright Chromium needs cplt config set sandbox.allow_cache_exec ms-playwright, and Chromium must run without its own nested sandbox. On macOS its helpers cannot initialize a second Seatbelt sandbox inside cplt (forbidden-sandbox-reinit); on Linux cplt's seccomp filter blocks the namespace syscalls that sandbox needs. Playwright as a library already launches with --no-sandbox, and that same opt-in sets PLAYWRIGHT_MCP_SANDBOX=false for Playwright MCP, which would otherwise turn it back on. Any other Chromium launcher needs --no-sandbox itself. cplt remains the enforcing kernel boundary, but a compromised renderer then receives the full cplt Playwright profile instead of Chromium's narrower child profile. See Cache exec and SECURITY.md.

Git commit works for every agent; whether git push works over HTTPS depends on the agent. Three prerequisites: use HTTPS remotes rather than SSH (git remote set-url origin https://github.com/org/repo.git, or rewrite globally with git config --global url."https://github.com/".insteadOf "[email protected]:"), run gh auth login once outside the sandbox, and run gh auth setup-git if the credential helper is not configured yet. Push then runs gh auth git-credential, which needs a token gh can reach from inside the sandbox — that differs per agent, see Git workflow. Pushes to the default branch and all force pushes are refused by the git guard by default; push a feature branch. The SSH agent socket is blocked because it unlocks every loaded key and can authenticate to any host, while the gh credential helper is scoped to GitHub.

The JVM is proxy-aware, so an internal Maven repository on a private IP now needs allowing. cplt injects http(s).proxyHost/proxyPort into JAVA_TOOL_OPTIONS, so Gradle and Maven dependency resolution goes through the CONNECT proxy and shows up in the proxy log instead of bypassing it. The proxy's SSRF guard then refuses an in-house Nexus or Artifactory that resolves into private address space, exactly as it already does for curl, npm and pip. Add its DNS name to proxy.allow_private_domains. A repository URL written as a bare IP literal (https://10.20.30.40/repository/maven-public/) cannot be allowed by any key — that check runs before the allow list is consulted — so such a repository needs a DNS name. WorkerExecutor plugin forks, and a Gradle daemon started outside cplt and reused inside, are not proxied. See Internal Maven/Gradle repositories on private IPs.

Gradle 9+ runs its own nested sandbox, and cplt turns it off. Since Gradle 8.8 the daemon wraps itself in sandbox-exec (controlled by GRADLE_MACOS_SANDBOX, previously the org.gradle.daemon.sandbox property). macOS does not support nested sandbox-exec calls, so the inner sandbox fails with "Operation not permitted" on socket operations. cplt injects GRADLE_MACOS_SANDBOX=off, since it already provides kernel-level sandboxing. This is a known upstream issue that hits any tool wrapping Gradle in an outer sandbox. Override with --pass-env GRADLE_MACOS_SANDBOX if you really want Gradle's own sandbox.

Copilot CLI 1.0.83 runs its own nested sandbox, and cplt turns it off. On Linux that sandbox builds a network namespace — slirp4netns, iptables, /dev/net/tun — and cplt's seccomp filter denies the unshare it takes. cplt also sets HTTP_PROXY/HTTPS_PROXY, which in 1.0.83 puts a Linux sandbox on the proxy-egress path whether or not you asked for it, so the two collide on every launch. Symptom: [cplt] Starting Copilot in sandbox... and then nothing. cplt injects Copilot's own opt-out, COPILOT_CLI_SANDBOX_SUPPORT_OVERRIDE=unsupported; Copilot stands down for the session, says so, and leaves your saved sandbox.enabled alone. cplt is the boundary, as it is for Gradle and Chromium. Override with --pass-env COPILOT_CLI_SANDBOX_SUPPORT_OVERRIDE. An enterprise managed policy that requires the sandbox overrides all of this — see Copilot CLI's own command sandbox.

Every impact, with the per-tool tables, JVM and Kotlin daemon notes, GPG troubleshooting, and the private-registry platform differences: docs/known-impacts.md.

Limitations

macOS

• sandbox-exec is deprecated. Apple has not removed it, but may in a future macOS version.
• SBPL has no domain-based filtering. The optional CONNECT proxy provides domain blocking instead.
• SBPL's lsopen has no filter either, so --allow-browser is all of Launch Services or none of it. With it on the agent can launch any application outside the sandbox, and no wrapper can narrow that — see docs/security.md.

Linux

• Kernel 5.13+ required, with Landlock LSM enabled.
• TCP port filtering needs kernel 6.7+. Older kernels get filesystem-only enforcement.
• Landlock cannot deny subpaths within allowed paths, so .env read/write/delete inside the project dir is not kernel-enforced. .git/hooks writes are blocked when Bubblewrap is active.
• --deny-path requires Bubblewrap. It is enforced through mount masks when bwrap is active. Without it, Landlock is allowlist-only and cplt warns about the deny instead of applying it.

More: docs/security.md

Contributing

Contributions are welcome.

Open an issue before starting a large change. Every PR has to pass CI (fmt, clippy, tests).

References

• SECURITY.md, the full security model, threat analysis, test strategy, and prior art
• Apple sandbox-exec(1)
• Chromium Seatbelt V2 Design
• Landlock LSM documentation
• seccomp-BPF documentation
• OWASP SSRF Prevention Cheat Sheet
• michaelneale/agent-seatbelt-sandbox

License

MIT