Documentation menu
On this page

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 as email/read or email/send).
  • Gate — a require_approval verdict made visible: the approval queue, confirm cards, and skep review.
  • Template — a named, inspectable policy layer (builder, operator, assistant; skep policy explain NAME renders it), diffable on switch. The ADR 0022 names locked-down, personal-dev, homelab-ops are 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 in sandbox.

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 them
  • default_env_allowlist: environment variables passed to workers by default
  • allowed_shell_commands: argv prefixes that can be approved by policy
  • allowed_plugin_risks: plugin risk classes allowed by policy
  • trusted_workspace_roots: host roots considered trusted for workspace-mode decisions
  • sandbox_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-secret with 0600 permissions
  • SKEP_LLM_API_KEY overrides 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 legacy llm-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, and skep doctor names 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.