Configuration
Skep keeps local state under one home directory and resolves runtime knobs at the
process edge. The default home is ~/.skep.
The Vocabulary: Policy, Scope, Gate, Template, Audit
Skep's user-facing language is administrative (v40, executing the v36 policy-first plan; internal names — Queen, worker, honeycomb — stay in code and dev docs):
- Policy — the rules: one unified document (
skep setup --template, the settings key) plus the legacy knobs it compiles into. - Scope — where a rule applies:
coding,shell,filesystem,network,mcp,email(live since v41-F3: an email-bound MCP server's tools decide asemail/readoremail/send). - Gate — a
require_approvalverdict made visible: the approval queue, confirm cards, andskep review. - Template — a named, inspectable policy layer (
builder,operator,assistant;skep policy explain NAMErenders it), diffable on switch. The ADR 0022 nameslocked-down,personal-dev,homelab-opsare accepted as aliases until 1.3.0. - Audit — always on: every decision skep makes records
decided_by, the rule that produced it. An external engine's own tool calls inside the sandbox are not decisions and are not recorded one by one; its run, patch, re-verification and approval are.
Home Directory
Choose a home with either the global flag or environment variable:
skep --home ~/.skep-dev status
SKEP_HOME=~/.skep-dev skep status
The top-level home stores personal setup and serve-level assets:
~/.skep/
profile.json
memory/
runs/
artifacts/
repos/
supervisor/
supervisor.sqlite3
audit/
policy/ # the approved baseline: baseline.json + baseline.lock
results/
worktrees/
llm-secret
skep setup --personal writes profile.json and the basic local directories.
The supervisor database, audit records, worker results, and worktrees live under
<home>/supervisor.
Personal Provider Profile
Configure the personal profile from the CLI:
skep setup --personal \
--provider ollama \
--model llama3.2 \
--endpoint http://localhost:11434
For providers that need a credential, store only the environment variable name:
skep setup --personal \
--provider openai-compatible \
--model gpt-4.1-mini \
--endpoint https://api.example.com/v1 \
--api-key-env EXAMPLE_API_KEY
profile.json stores the provider name, model, endpoint, and credential
environment variable name. It does not store the credential value.
Worker Command
The worker command decides which coding agent Skep supervises. For an
external agent (Claude Code, Codex, Aider, pi), prefer the project's
coding_engine (skep project setup --engine claude_code). A worker command
that runs an engine's module is that engine all the same: it needs the
agent's auth env and a pinned verify_command, exactly as --engine does.
Per run:
skep run --worker-cmd "python -m skep.workers.claude_code" /path/to/repo "fix the bug" --execution-mode sandbox
An external agent's commands skip skep's capability layer, so the sandbox is
its only wall: a worker command that runs one (an engine's worker module, or
the generic shell worker) is forced into sandbox mode whatever
--execution-mode says, and the run's record notes the change. Its built-in
verify is only git diff --check, so it also requires the project's pinned
verify_command (skep project setup <repo> --verify-command "<command>").
For the current shell:
export SKEP_WORKER_CMD="python -m skep.workers.claude_code"
For the serve UI, edit the worker command in Settings. The setting is persisted in the supervisor database and used for later dashboard runs.
The Claude Code adapter also supports:
export SKEP_CLAUDE_CODE_CMD="/path/to/claude"
Allow it on runs that need the custom executable:
skep run \
--worker-cmd "python -m skep.workers.claude_code" \
--env-allow SKEP_CLAUDE_CODE_CMD \
/path/to/repo \
"fix the bug" \
--execution-mode sandbox
Execution Mode
Runs can execute in either mode:
sandbox: run the worker through the host sandbox backend.workspace: run without the host sandbox, still in Skep's disposable worktree and approval/re-verification pipeline. Skep's own worker only: an external agent always runs insandbox.
Choose per run:
skep run /path/to/repo "fix the bug" --execution-mode sandbox
The serve Settings page also has default_execution_mode:
ask: require each run request to choose.workspace: default dashboard/API runs to workspace mode.sandbox: default dashboard/API runs to sandbox mode.
Sandbox mode fails closed if the requested host backend cannot be applied.
A project's own default_execution_mode (v127-F8, ADR 0066): project setup
gives a NEW project sandbox when this host can sandbox, else workspace with
the probe's reason. An existing project keeps its stored mode through
re-setup and phase changes; skep doctor lists the ones still on workspace,
and skep project setup <repo> --execution-mode sandbox moves one.
Permission Defaults
Per-run flags override defaults:
skep run /path/to/repo "update dependencies" \
--execution-mode workspace \
--network pypi.org \
--env-allow EXAMPLE_API_KEY
The serve Settings page can persist these policy defaults:
default_network: network hosts granted to every run; a dispatch's explicit network list adds to them, and only an explicit empty list drops themdefault_env_allowlist: environment variables passed to workers by defaultallowed_shell_commands: argv prefixes that can be approved by policyallowed_plugin_risks: plugin risk classes allowed by policytrusted_workspace_roots: host roots considered trusted for workspace-mode decisionssandbox_required_for: risk labels that force sandbox mode
Use explicit run flags when you want one run to differ from the stored policy.
Shell allowlist and remembered commands
git push, git pull, and git fetch can never be allowlisted or remembered
(v19-F3). The worker denies them outright, and Skep lands changes as a patch on
a skep/<task_id> branch after approval — a worker never touches your remotes.
The one-click git preset therefore no longer includes push, and a store that
still carries a poisoned ["git","push"] entry (from an older grant) has it
filtered from every read and swept out on daemon startup with a logged warning.
Approving a pending shell command with Allow & remember persists the exact
normalized command, not a broad prefix (v19-F4): a leading git -C <path> is
stripped so a dead absolute worktree path can never be stored, and the command
runs through the same too-broad guard as the policy editor. When the run's repo
is bound to a project (skep project), the remembered command lands in that
project policy's allowed_shell_commands rather than the global setting, so
remembering one repo's command does not widen every other repo's allowlist.
Remembering falls back to the global setting only when the repo is not bound.
The Policy Baseline
skep policy approve --template builder (or operator, assistant, or
--file PATH for a layer file in the same format) locks one template as
your policy (first-run O2, ADR 0056 D1/D2). It prints the
skep policy explain table of what it is about to lock, asks for a typed
yes (--yes for scripts), and writes three things:
<home>/supervisor/policy/baseline.json the layer
<home>/supervisor/policy/baseline.lock the approval row + the approved layer
<home>/supervisor/audit/policy/baseline-approvals.jsonl one row per approval
The ledger row is
{"kind":"baseline_approved","sha256":…,"template":…,"approved_by":…,"approved_at":…,"skep_version":…,"schema_version":…}.
The hash is over the loaded layer as sorted-key JSON, so reformatting the
file is not a change; editing a setting or a rule is.
The baseline is the registry's template layer
(floor → global → template → phase → group → project → session → dispatch),
and every setting it sets is enforced: a project overlay, a group or a
dispatch argument can no longer change it (RSoP shows their statements as
refused: enforced at template:<name>); a setting the baseline leaves unset
passes through as before. Its rules join the same slot. Like every layer it
answers in the scopes routed to engine v2.
Before every outside decision (skep policy decide, the Claude Code hook,
skep acp govern) and at serve startup, skep re-checks the file against the
lock and the lock against the ledger (cached until a file's mtime changes).
If they disagree — a hand edit, a deleted lock, both files deleted while the
ledger holds an approval — every decision fails closed with reason
baseline_tampered: ask where a human answers (the hook, the ACP
permission hop, the Queen's own tools), deny where none does (the
governor's hard ring), and dispatch refuses. One card per tamper event lands
in the "policy baseline" chat; skep policy why prints
baseline: TAMPERED since <time>. The floor stays above the baseline either
way.
skep policy baseline status # one line (+ the diff); exits 1 when tampered
skep policy baseline diff # what changed against the locked layer
skep policy explain baseline # the locked layer as a table
skep policy approve --reapprove [--template NAME | --file PATH] [--yes]
--reapprove shows the diff against the locked layer first, then re-locks
(the current baseline.json when no source is named). A baseline approved
under an older layer schema whose content is unchanged keeps applying and
cards a re-approval instead of tripping. baseline.json is also set
0444, but that is a courtesy: workers and the operator are the same Unix
user, so mode bits are not the enforcement — the hash and the ledger are.
With no baseline at all, decisions are exactly what they were before O2.
Budgets
Templates, schedules, and serve policy can set default budgets:
- wall-clock seconds
- max iterations
- max actions
- max provider calls
Per-run or per-template budgets should be narrow enough to bound a stuck worker, but large enough for the expected task.
Auto-Approval
A patch lands without a click only when the project turns on
auto_apply_verified_patch (the maintain phase and unlocked mode turn it on)
and pins a real check. Auto-approval still requires successful
worker verification, successful supervisor re-verification, and the project's
policy conditions. Every auto-landing rule needs the re-verification to have
re-run the project's pinned verify_command (never the command the worker
chose for itself) and that pin must not be known-vacuous (see
verification.md). --auto-approve on skep run, tick
and serve is retired: it is still accepted for one release, prints a note,
and has no effect. The serve Settings auto-approve toggle is inert too.
If re-verification is missing or disagrees with the worker, auto-approval does not apply.
Assistant Settings
The browser dashboard can store assistant model settings for chat and for the default in-repo coding worker when no explicit worker profile exists.
- base URL, protocol, and default model are stored in the supervisor database
- API key is stored in
<home>/supervisor/llm-secretwith0600permissions SKEP_LLM_API_KEYoverrides the saved key when set- registry profiles (v108) each hold their own key in
<home>/supervisor/llm-secret-<provider_id>(skep provider set-key); resolution is the profile's named env var, then its own file, then the legacyllm-secret— the last only for a profile on the endpoint it was saved for (the saved base URL; v119-F1). A profile elsewhere with no key of its own is called without one, andskep doctornames it
Useful Environment Variables
| Variable | Purpose |
|---|---|
SKEP_HOME |
Default top-level Skep home when --home is not passed. |
SKEP_WORKER_CMD |
Default worker command for CLI and serve startup. |
SKEP_PROVIDER |
Default setup --personal --provider value. |
SKEP_MODEL |
Default setup --personal --model value. |
SKEP_PROVIDER_ENDPOINT |
Default provider endpoint for setup. |
SKEP_PROVIDER_API_KEY_ENV |
Default provider credential env-var name for setup. |
SKEP_LLM_API_KEY |
Dashboard assistant API key override. |
SKEP_CLAUDE_CODE_CMD |
Claude Code adapter executable path. |
For first-run commands, see quickstart.md. For sandbox
details, see sandboxing.md.