cplt keeps your AI agent sandboxed.

Enable the CONNECT proxy for outbound HTTPS traffic logging and domain filtering.

Force all egress through the proxy: make the proxy mandatory and restrict kernel-level egress to the proxy port only (no direct *:443). Fails closed if the proxy cannot start.

Local port for the CONNECT proxy listener.

Path to a file listing domains to block through the proxy (one per line).

Path to a file listing the only domains allowed through the proxy (allowlist mode).

Fail-closed networking (opt-in): restrict egress to the agent's built-in default allowlist (e.g. GitHub Copilot infrastructure + package registries) merged with allowed_domains; block all other domains. Override for one run with --allow-all-domains.

Path to write proxy connection logs (CONNECT requests and outcomes).

Stderr verbosity for proxy events: "none" (silent), "error" (DNS/connect failures), "blocked" (errors + blocked connections), "all" (everything including CONNECTED). With an allowlist, an unset level shows blocked connections; an explicit "none" stays silent. The separate log_file records everything.

Timeout in seconds for proxy request/header reads. Established tunnels may idle up to 1h.

Upstream (corporate) proxy URL to forward CONNECT tunnels through, e.g. "http://corporate-proxy.example.com:8080". cplt still enforces all domain filtering, logging, and port checks before forwarding. Optional basic-auth userinfo is supported; only the http scheme is supported.

Hosts that BYPASS the upstream proxy and are connected to directly (like NO_PROXY). Only meaningful with proxy.upstream. Suffix matching: "example.com" covers all subdomains; CIDR/IP ranges are NOT honored. Merged additively with the ambient NO_PROXY/no_proxy environment. All of cplt's domain/port/SSRF filtering still applies, so an internal host that resolves to a private IP is BLOCKED (403) unless you ALSO add it to proxy.allow_private_domains.

Domains allowed to resolve to private/internal IPs (opt-in DNS-rebinding bypass). Use for corporate intranet services. Suffix matching: "intern.nav.no" covers all subdomains.

Extra directories to allow read access (e.g., shared libraries outside the project).

Extra directories to allow write access (use sparingly, the project dir is already writable).

\u{26a0}\u{fe0f} DANGEROUS: Trees the agent may execute binaries from (e.g. a relocated Homebrew prefix). Read + execute, never write. Refused for an unsafe root (/, /tmp, $HOME and its parents, the platform system dirs) and for any tree that overlaps a writable one \u{2014} writable + executable is a binary-drop path.

Unix socket paths to allow access to.

Domains to add to the proxy allowlist. Adds to an allowlist already in force; does not turn one on.

Additional outbound ports to allow (443 is always allowed).

Specific localhost ports to allow outbound connections to (e.g., local dev servers).

Extra paths to deny access to (overrides project-dir allows for sensitive subdirs). Each entry is one literal path: globs such as `**/*.pem` are not expanded.

Environment variables to strip from the sandbox (repo-local only: tightens env filtering).

Preferred AI coding agent (copilot, opencode, gemini, antigravity, pi, claude, goose, dsh, shell). Auto-detected from PATH if not set.

Security posture baseline: "standard" (the default: both guards on in block mode, the git guard scoped to the default branch), "strict" (all toggles off, every push blocked, proxy.forced and proxy.default_allowlist on), "permissive" or "full-trust" (both guards off, sandbox toggles loosened). Individual keys/flags override it.

Validate the sandbox profile with sandbox-exec before launching Copilot.

EXPERIMENTAL: Write the per-session agent-facing sandbox brief (CPLT_BRIEF.md) to the scratch dir. Unstable — may change or be removed in a future release.

EXPERIMENTAL: Also inject the managed cplt sandbox block into the project's AGENTS.md on launch (writes into the repo). Requires sandbox.brief. Unstable — may change or be removed in a future release.

Allow Copilot to read .env, .pem, .key files in the project directory.

Allow outbound connections to any localhost port (for local dev servers).

Extra environment variables to pass through to the sandbox (exact names).

Additional repositories this project spans (local config only: cplt config set --local). Relative paths are resolved when set; stored absolute and re-validated on every launch.

⚠️ DANGEROUS: Pass ALL environment variables instead of the safe allowlist. May leak secrets.

Allow npm/yarn/pnpm lifecycle scripts (postinstall, prepare, etc.) to run.

⚠️ DANGEROUS: Allow GPG commit/tag signing. Exposes the GPG agent socket for signature requests. Private keys stay protected.

⚠️ DANGEROUS: Allow executing binaries from /tmp and /var/folders. Weakens code-exec isolation.

Create a per-session scratch directory and redirect TMPDIR into it.

Print the post-session project-change and network audit reports (net file changes vs a pinned baseline commit). Suppressed by quiet.

Linux only: wrap the sandbox in Bubblewrap namespaces (PID/IPC/UTS/cgroup/user + private /tmp) for defense-in-depth. Unset = auto-detect with fallback to Landlock-only.

Hide the startup configuration summary (sandbox rules, network, env info).

Skip the confirmation prompt at startup (equivalent to --yes).

Deny the macOS clipboard (com.apple.pasteboard) to the agent, so `pbpaste` cannot read whatever was last copied. Override for one run with --allow-clipboard. No effect on Linux.

Allow JVM Attach API unix sockets for ByteBuddy/MockK/Mockito inline mocking.

Allow MSBuild worker-node unix sockets for `dotnet build` (not the persistent MSBuild Server).

Install a cplt-managed Gradle init script in the Gradle user home ($GRADLE_USER_HOME/init.d/ or ~/.gradle/init.d/cplt-sandbox.gradle) that applies the preferIPv4Stack workaround inside the sandbox. Inert outside sandbox builds.

macOS only: refuse to create a .git file, directory or symlink anywhere below a writable root, so a session cannot plant a repository whose config runs on the host (#576). Breaks `git worktree add` and fixtures that create a .git inside the project. No effect on Linux, where the session-end check is the only cover.

Linux only: refuse to launch when an allow_cache_exec entry reaches its directory through a symlink inside ~/.cache, instead of granting the link's target with a warning. The agent can write ~/.cache, so it can plant or re-point such a link for the next launch. A symlinked ~/.cache itself is not affected.

macOS only: inside the project and every granted tree (--repo-dir, allow.write, allow.read), deny .pem, .key, .p12, .pfx and .jks files by extension (server.pem, tls.key), not only files named exactly .pem. Breaks anything there that reads a key or certificate: a local HTTPS dev server, key fixtures in tests, a project virtualenv's certifi/cacert.pem (pip and requests fail TLS), and system CA bundles if a grant covers /etc or /opt/homebrew. No effect on Linux.

Keep pnpm's global config dir (~/.config/pnpm, or $XDG_CONFIG_HOME/pnpm) read-only and deny its token files, auth.ini (pnpm 11+) and rc (pnpm 10 and older). Breaks pnpm installs from a private registry whose token is only in those files, and `pnpm config set --global` / `pnpm login` inside the sandbox. config.yaml stays readable. Re-allow a token file with allow.read.

Refuse to launch when a repository's .cplt.toml cannot be loaded or has a [deny] key this cplt does not recognize, naming the problem, instead of warning and launching without those [deny] rules. Covers the launch repository and every named repository. Catches broken files, not an adversarial session.

Linux only: stop granting execute on ~/.copilot, so the writable directory Copilot keeps its config in is not also a place to run a dropped binary from (#324). Copilot runs its bundled tools from ~/.cache/copilot/pkg. Breaks a plugin, MCP server, LSP server or hook launched as a program stored under ~/.copilot. No effect on macOS, where the launch warns instead.

⚠️ DANGEROUS: Allow Docker/Colima/OrbStack access. Exposes daemon socket and ~/.docker config. Container mounts bypass sandbox.

~/Library/Caches subdirs to allow exec from (e.g. ["ms-playwright"] for Playwright browsers).

⚠️ DANGEROUS: Allow exec from ALL ~/Library/Caches subdirs. Prefer allow_cache_exec with specific subdirs.

⚠️ DANGEROUS: Launch Services grant for OAuth code flows. Lets the agent launch ANY application outside the sandbox, via launchd. Cannot be scoped.

Drop the macOS Keychain grant when the agent has a credential it can reach without it. Copilot uses `gh auth token`, Claude uses CLAUDE_CODE_OAUTH_TOKEN; both keep the grant without one.

\u{26a0}\u{fe0f} DANGEROUS: Let the agent read ~/.npmrc, ~/.gradle/gradle.properties and ~/.m2/settings.xml (the files only; read-only on macOS, while Linux leaves the Maven and Gradle files read/write either way). Exposes every registry token in them, not only the one the project uses.

Grant read, write and execute on a cplt-owned directory for this repository's sub-agent worktrees (~/.cplt-worktrees/<id>, exported as CPLT_WORKTREE_ROOT). Worktrees and branches there persist after the session. macOS only. User config only; .cplt.toml cannot propose it.

With allow_git_worktrees on: how many directories the check of the worktree root visits at launch and session end. Past it the launch refuses to start, since a .git beyond it would go unseen. Raise it for large dependency trees.

DEPRECATED: use [gh_guard] section instead. Enables gh CLI proxy.

DEPRECATED: use [git_guard] section instead. Enables git push prevention.

Enable gh CLI proxy that blocks destructive GitHub operations (delete repo, merge PR, etc.).

Enforcement mode: "block" (deny and exit), "warn" (print warning, allow), or "audit" (silent log).

Enforce same-repo check. Blocks operations targeting other repositories via the -R flag.

Block 'gh auth token' command to prevent credential exfiltration.

DEPRECATED on macOS: gh gets its token from the gh guard, Copilot from sandbox.keychain_substitute. Still needed on Linux when Copilot's login sits in the Secret Service. Pre-extracts GH_TOKEN into the agent env (Copilot only).

Policy for commands not in the classification table: "block" (default-deny) or "allow" (permissive).

Allow 'gh api' write operations (POST/PATCH/PUT and input flags). Writes are scope-checked to the current repo. GraphQL is always blocked.

Allow 'gh pr merge' of the account's own PRs, in scope, into a branch where an active ruleset the account cannot bypass requires an approving review that a new push dismisses. '--admin' is always refused.

Intercept git push, request-pull and send-pack. What happens to an intercepted command is `mode`: block (default) refuses it, warn prints and runs it.

Enforcement mode: "block" (default: deny and exit), "warn" (print warning, allow), or "audit" (silent log).

Treat git push, request-pull and send-pack as violations. `mode` decides what a violation costs.

Block force push (only meaningful when prevent_push is false).

Only block pushes to the default branch (main/master), the default outside --preset strict. Set false to block every push.

Structured push exceptions. Each entry specifies remote/branches/force conditions under which push is allowed.

Agents the PATH shim sync leaves out (e.g. ["goose"] when your goose is pressly/goose, the migration tool). Only matters after `cplt --shell-install --shims`.