Security

The threat model, and its limits

skep assumes the coding agent is wrong, careless or steered by something it read. It confines the agent's process, checks its work without it, and keeps your default branch out of its reach. This page says exactly what that covers, and what it does not.

What skep defends against

Each control is described below with its limit
The agent tries toWhat stops it
Write outside its taskThe OS sandbox: a read-only root filesystem with the worktree and a few named directories writable.
Reach a host you did not allowThe sandbox network list, enforced by the OS and a filtering proxy.
Read your credentialsThe secret floor: credential paths are masked inside the sandbox and denied by policy.
Push, pull, fetch, or move your branchHard denies for the built-in worker; for an external engine, the sandbox, masked credentials and a git protocol pin.
Report tests passed when they do notRe-verification: skep re-runs the project’s pinned command on a clean worktree.
Land its own workThe patch is applied only on approval, on skep/<task_id> or a branch you name; the default branch is refused.
Widen its own permissionsA locked policy baseline with a hash check, read-only inside the sandbox.

What is out of scope

  • Confidentiality of ordinary files. Inside the sandbox, reads outside the worktree are mostly open. Only the listed credential paths are masked.
  • What the model provider sees. With a hosted model, prompts go to that provider, and they include your code.
  • A policy you made permissive. If you allow * for the network, the engine doing what you told it is working as designed.
  • A weak verify command. skep proves that your command passes. It cannot prove the command proves the work.
  • Other processes running as you. skep's records and its baseline belong to your Unix user. Malware or a compromised OS outside the sandbox is not something skep stops.
  • A flaw in the OS sandbox itself. skep relies on Seatbelt, bubblewrap, Landlock and user namespaces as the kernel provides them.
  • Packages from registries you allowed. A dependency the run installs executes inside the same sandbox, with the same network list.
  • More than one operator. skep supervises local processes for one person on one machine.
  • Windows. There is no backend.

The sandbox

An OS wall around the worker, when the run is in sandbox mode

Workspace mode has no OS wall: the worker runs as you, in a separate worktree, and nothing confines the process. Everything in this section is about sandbox mode, which every external engine is forced into.

Sandbox backends
PlatformBackendNotes
macOS Seatbelt (sandbox-exec) Used when the host process may apply profiles. Leaves most reads open.
Linux bubblewrap (bwrap) plus Landlock Used when bwrap is installed and its probe succeeds. Own PID and IPC namespaces, an empty /run and /tmp. Landlock scopes unix sockets by the kernel's ABI.
Linux, opt-in podman (sandbox_backend=podman) Runs the same Landlock step. The container runs with SELinux labelling disabled.
Windows, others none A sandbox run is refused.

Writable

  • the worktree, with a private TMPDIR inside it
  • the run's own results/<task_id>/
  • the worktree's git metadata and the repository's objects/
  • the per-project cache

Shared /tmp and /var/folders are not writable. The repository's hooks/, config and refs/ stay read-only.

Masked: the secret floor

  • credential stores: ~/.ssh, ~/.aws, ~/.gnupg, ~/.config/gh, ~/.netrc, ~/.git-credentials, ~/.kube, ~/.config/gcloud, ~/.azure, ~/.docker/config.json and more
  • engine logins: the macOS keychains, ~/.claude/.credentials.json, ~/.codex/auth.json
  • shell rc files and REPL histories
  • skep's own secrets: serve.env, the serve token, every *-secret file, the audit directory and chat attachments
  • on Linux, agent sockets: ssh-agent, gpg-agent, D-Bus, Docker and podman

Still readable

  • the rest of the filesystem, so the toolchain works
  • ~/.npmrc, so npm install works (policy still refuses read tools on it)
  • skep's store, supervisor.sqlite3
  • for a built-in worker that calls the model: its own provider key, unless the provider key relay is on

The full list of masked paths is in the sandboxing reference.

Network

The three network modes
The run’s listMeansEnforced by
emptyNo outbound network.macOS: the Seatbelt profile. Linux: a private network namespace.
named hostsOnly those hosts.The worker can reach nothing but the filtering proxy, and the proxy admits the listed hosts.
*All outbound network.Nothing. On Linux the run shares the host network namespace.
  • Defaults. With no list on the request, the policy's default_network applies. The builder and operator baselines allow package registries (pypi.org, files.pythonhosted.org, registry.npmjs.org, proxy.golang.org); the assistant baseline and a bare home allow none.
  • The model provider. A worker that calls a model always reaches that provider's host, whatever the list says.
  • Loopback is closed. A run reaches a port on this machine only when it is its own local model provider's port or one the project lists in loopback_ports. skep serve's port is never opened.
  • Git transports. Every worker gets GIT_ALLOW_PROTOCOL=file, and task worktrees carry the same rule as git config, read-only in the sandbox. A push, fetch or clone over https, ssh or git fails with “transport not allowed”.

Fail-closed

  • skep probes the backend before launch. If a sandbox run cannot be confined, the worker does not start: the run records sandbox_unavailable and is never retried unconfined.
  • If the kernel reports a Landlock ABI but applying it fails, the run fails. It never runs unscoped while skep doctor says scoped.
  • A run whose skep home lies inside a writable root is refused.
  • No sandbox nests inside skep's, so an engine's own sandbox is switched off and skep's is its only wall. The Codex, Aider and pi workers refuse to start outside it.
skep doctor
skep doctor
…
- sandbox: ready - bubblewrap backend is usable. Landlock ABI 10: a worker connects only to unix sockets in its own roots or ones it made itself.
captured: 2026-11-18, Linux (bubblewrap), throwaway SKEP_HOME; the sandbox line only
sandbox.profile.sb: the wall one run got
cat $SKEP_HOME/supervisor/audit/01a1f147-656d-7a10-81a4-4b42ba08e7bc/sandbox.profile.sb
# bubblewrap argv
"--ro-bind", "/", "/",
"--dev", "/dev", "--unshare-pid", "--unshare-ipc", "--proc", "/proc",
"--tmpfs", "/tmp", "--tmpfs", "/run", "--die-with-parent", "--new-session",
…
"--unshare-net",
"--ro-bind", "~/code/skep-demo/.git", "~/code/skep-demo/.git",
"--bind", "$SKEP_HOME/supervisor/worktrees/01a1f147-…", "$SKEP_HOME/supervisor/worktrees/01a1f147-…",
"--bind", "$SKEP_HOME/supervisor/results/01a1f147-…", "$SKEP_HOME/supervisor/results/01a1f147-…",
"--bind", "~/code/skep-demo/.git/worktrees/01a1f147-…", "~/code/skep-demo/.git/worktrees/01a1f147-…",
"--bind", "~/code/skep-demo/.git/objects", "~/code/skep-demo/.git/objects",
"--bind", "$SKEP_HOME/supervisor/cache/projects/skep-demo", "$SKEP_HOME/supervisor/cache/projects/skep-demo",
"--ro-bind", "~/code/skep-demo/.git/skep-protocol-pin", "~/code/skep-demo/.git/skep-protocol-pin",
"--tmpfs", "~/.ssh",
"--tmpfs", "~/.config/gh",
"--ro-bind", "/dev/null", "~/.docker/config.json",
"--ro-bind", "/dev/null", "~/.claude/.credentials.json",
"--ro-bind", "/dev/null", "~/.codex/auth.json",
"--ro-bind", "/dev/null", "~/.claude.json",
"--ro-bind", "/dev/null", "~/.bashrc",
…
"--ro-bind", "/dev/null", "~/.zsh_history",
"--tmpfs", "~/.docker/desktop",
"--tmpfs", "$SKEP_HOME/supervisor/audit",
"--ro-bind", "/dev/null", "$SKEP_HOME/supervisor/relay-secret",
…
"-m", "skep.landlock", "--scope-abstract",
"--unix-root", "$SKEP_HOME/supervisor/worktrees/01a1f147-…",
…
captured: 2026-11-18, Linux (bubblewrap), throwaway SKEP_HOME; an excerpt, regrouped onto fewer lines; home shown as ~, the repository as ~/code/skep-demo, task id shortened; only paths that exist on the host are masked

Git and remotes

What a worker can never do, and what can be granted

The answer is the same for every engine. The mechanism is not.

Never, and grantable
ActionVerdictDetail
git push, pull, fetch, clone, ls-remote, remote edits deny Never. No allowlist entry, grant, role or approval overrides it, and it cannot be remembered.
git checkout, git switch deny Never: a worker does not move a branch.
sudo, doas, su, pkexec, run0 deny Refused first, because every other deny reads the command's first word.
git add, git commit through shell.run deny Denied as shell commands.
The git.stage and git.commit capabilities ask Grantable, with approval. The commit lives in the disposable worktree, the repository's refs stay read-only, and the patch is still the diff against the starting commit.

The built-in worker

Every side effect is a capability call that the policy engine decides: shell.run, filesystem.write, network.fetch, network.read, network.connect, git.stage, git.commit. The denies above are checked before any allowlist or grant, and the same list binds the chat assistant's own tools.

An external engine

Claude Code, Codex, Aider and pi run their own tools, and those calls do not pass the capability layer. What stops a push is the sandbox: no route to a host outside the list, masked credentials, and the git protocol pin. skep also switches the agent's own guard off (bypassPermissions, danger-full-access): its sandbox replaces that layer.

Re-verification and landing

Two controls that do not depend on the agent

The sandbox limits what the agent can touch. These two limit what its output can become.

Re-verification (G10)

skep applies the patch to a clean worktree at the pinned baseline commit and runs the project's pinned verify_command there, in a sandbox with the network denied. Only the exit code is trusted. The result is recorded apart from the worker's claim, with the command and where it came from.

Landing

A finished run is a patch. It becomes a commit when it is approved, on skep/<task_id> or a branch you name. The repository's default branch is refused as a landing target, and it moves only through actions you confirm, such as merging a pull request. Approval is refused for a run with no re-verification record.

The four outcomes and a captured run are on the How it works page.

The policy engine

A floor, a locked baseline, and layers that only narrow

One function decides allow, ask or deny for the built-in worker, the chat assistant, the Claude Code hook and the ACP governor.

  • The floor is above every layer: remote git and branch switching, privilege escalation and credential reads are denied, and outbound posts always ask. No rule, grant, role or card lifts it.
  • The locked baseline. skep policy approve writes the approved template, a lock holding its SHA-256, and a row in an approvals ledger. Before every outside decision and at serve startup skep checks the file against the lock and the lock against the ledger. If they disagree, every decision asks, the ACP governor's hard ring denies, and dispatch is refused.
  • A fresh home with no approved baseline asks for everything until one is approved.
  • Layers. Any deny binds across layers, an unmatched action asks, a role or a delegation can only make an answer stricter, and taint turns an allow into an ask in a chat that has read private data or outside content.

Layers and precedence The policy baseline in the docs

a baseline edited by hand
skep policy baseline status
baseline: TAMPERED since now
  ~ rule shell-learnable: shell: require_approval run * -> shell: allow run *
# exit status 1
skep policy decide --repo skep-demo shell run "npm i left-pad"
{
  "action": "run",
  "actor": "cli",
  "at": "2026-11-19T00:51:35Z",
  "decided_by": "baseline/baseline_tampered",
  "layer": "baseline",
  "note": "baseline: TAMPERED since 2026-11-19T00:51:35Z",
  "repo": "skep-demo",
  "rule_id": "baseline_tampered",
  "scope": "shell",
  "source": "baseline",
  "value": "npm i left-pad",
  "verdict": "require_approval"
}
skep run ~/code/skep-demo "create a Python hello world script" --execution-mode sandbox
error: baseline_tampered: the approved policy baseline no longer matches its lock — `skep policy baseline diff` shows what changed; `skep policy approve --reapprove` re-locks it
captured: 2026-11-18, Linux (bubblewrap), throwaway SKEP_HOME; the repository shown as ~/code/skep-demo; the first line of the refused dispatch

Secrets

Where secrets are stored, and what a worker receives

skep does store secret values. They are files with mode 0600 under the home, never rows in the database.

Paths are for the default home, ~/.skep
SecretStored
Provider API key (web Settings)~/.skep/supervisor/llm-secret, mode 0600; one llm-secret-<id> per provider profile
Provider key (CLI setup)Not stored: profile.json holds the name of the environment variable
Serve token~/.skep/supervisor/serve-token
Messenger channel secrets*-secret files beside the serve token, write-only through the API
Engine auth for the daemon~/.skep/serve.env, read by skep serve at startup

What a worker receives

  • Environment variables are passed by name: the run's allowlist (--env-allow, or the policy's default_env_allowlist), plus the toolchain variables skep sets itself.
  • An external engine gets its own auth env (CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY; OPENAI_API_KEY). Its keychain and file logins are masked, and it sees no model key of skep's.
  • A built-in worker that calls the model can read its own provider key. With provider_key_relay on (off by default) the key stays masked and the run's proxy adds it to the request.
  • A Codex run on a ChatGPT plan login, opt-in per project, gets a read-only copy holding the access token and an empty refresh token, deleted when the run ends. How that works.

Known limits

What skep does not do

The same list as above, in one place. If your threat model needs one of these, skep is not enough by itself.

The sandbox

  • Workspace mode has no OS sandbox. Onboarding with --sandbox none does not switch the sandbox off for a run that asks for it; it tells the locked baseline not to count on one, so writes it would have allowed become asks.
  • Reads outside the worktree are mostly open. On macOS, Seatbelt leaves reads open apart from the secret floor.
  • The secret floor is a list. A secret at a path that is not on it is readable.
  • A secret file created while a run is in progress is not masked for that run.
  • ~/.npmrc stays readable inside the sandbox.
  • A * network run on Linux shares the host network namespace: its loopback is the host's, skep serve's port included.
  • On a kernel below Landlock ABI 9, a unix socket at an unlisted path outside /tmp and /run stays reachable. Below ABI 6, or with Landlock off, so does an abstract socket in a bubblewrap run with * network.
  • Neither the masks nor Landlock touch a descriptor the worker already holds when it starts.
  • The default network includes the model provider and, under the builder and operator baselines, package registries.
  • The podman backend runs with SELinux labelling disabled for the container.
  • There is no Windows backend.

Everything else

  • skep switches the agent's own guard off. Its sandbox replaces that layer; the two do not stack.
  • An external engine's tool calls do not pass the capability layer and are not logged one by one.
  • Re-verification is only as strong as the command. An unpinned project re-runs the worker's own choice.
  • Two auto-landing lanes exist. Both are opt-in, and neither can land on the default branch.
  • The records are not tamper-evident: no hash chain, files owned by your user. The decision log is rotated, never deleted, and its readers show only the newest two files.
  • The Claude Code hook and the ACP governor judge and record. Neither confines anything.
  • With a hosted model, your prompts and code go to that provider.
  • Agents still make logic mistakes that pass your tests. Approval is a person reading a diff.
  • A dependency a run installs from an allowed registry runs inside the sandbox with the run's network.
  • One operator, one machine, one maintainer: there is no multi-user separation.

Disclosure

Reporting a vulnerability

A hole in any of these layers is a security bug even if no data was touched.

Email anmolnoor59@gmail.com with [skep security] in the subject. Please do not open a public issue for anything exploitable.

Include what you can of:

  • the skep version (skep --version) and the OS and sandbox backend (skep doctor output)
  • the boundary affected: sandbox escape, network-allowlist bypass, worker git mutation, approval bypass, landing without approval, secret leakage
  • reproduction steps or a failing test

You will get an acknowledgment within a week. Fixes land as ordinary versioned fixes with a test that proves the failure path stays closed.

SECURITY.md Sandboxing reference The invariants