Install

Install skep

skep is a Python package for macOS and Linux. It needs Python 3.12 or newer and Git. Install it, check the sandbox, then let the guided first run do the rest.

Install and first run
$ pipx install skep && skep onboard

What skep onboard does

check the install
skep --version
skep 1.6.0 (worker contract 0.3.8)
captured: skep --version; the two numbers are filled in from this release's sources

Install paths

Four ways to get the package

All four install the same package from PyPI or from the repository. Pick one.

pipx (recommended)

An isolated app with skep on your PATH. On Debian and Ubuntu the system Python refuses a bare pip install (PEP 668); pipx is the way around it. On macOS, install pipx as its own guide says.

pipx
# Debian, Ubuntu (Fedora: sudo dnf install pipx)
$ sudo apt install pipx
# puts ~/.local/bin on PATH; open a new shell afterwards
$ pipx ensurepath
$ pipx install skep
$ skep --version

uv

uv tool install does the same job as pipx. uvx runs one command from a temporary environment; it needs a subcommand, because skep alone only prints its usage.

uv
# installed, on PATH
$ uv tool install skep
# or run one command without installing
$ uvx skep --version

pip, inside a virtual environment

Fine when you manage the environment yourself. skep is on PATH only while that environment is active.

pip
$ python3 -m venv .venv && . .venv/bin/activate
$ pip install skep

From source

What contributors use. It needs uv, and every command becomes uv run skep …. bash scripts/install.sh --dry-run prints what the installer script would do (sync, the bubblewrap reminder on Linux, the first commands) without doing it.

source checkout
$ git clone https://github.com/Anmolnoor/skep.git
$ cd skep
$ uv sync --frozen
$ uv run skep --version

Sandbox prerequisite

What each platform needs

A sandbox-mode run needs an OS backend. skep probes it before every launch and refuses to start the worker when none can be applied.

Linux: bubblewrap

Install the bubblewrap package. User namespaces must be allowed by the host, or the probe fails.

Landlock is applied inside the sandbox when the kernel has it: abstract unix sockets from ABI 6 (Linux 6.12), path sockets from ABI 9. On an older kernel that step is skipped and skep doctor says so.

macOS: Seatbelt

Nothing to install: sandbox-exec ships with macOS.

It is usable when the host process is allowed to apply sandbox profiles.

Linux, opt-in: podman

Chosen with skep onboard --sandbox podman. It is never picked automatically.

Windows and others: none

There is no backend, and skep is not built or tested for these platforms.

Linux: install bubblewrap
# Debian, Ubuntu
$ sudo apt install bubblewrap
# Fedora
$ sudo dnf install bubblewrap
# the last line reports the sandbox
$ skep doctor
skep doctor, before onboarding
skep doctor
Skep: blocked

Required checks:
- profile: blocked - Personal profile is missing. Next step: run setup --personal

Personal surface:
- provider: unconfigured model=unconfigured
- coding_worker: no worker provider configured
- engine aider: MISSING — 'aider' not on PATH (sandbox-confined; needs verify_command)
- engine builtin: ok — …/bin/python (skep's own worker)
- engine claude_code: NO AUTH ENV — set one of CLAUDE_CODE_OAUTH_TOKEN/ANTHROPIC_API_KEY — …/bin/claude (sandbox-confined; needs verify_command)
- engine codex: NO AUTH ENV — set one of OPENAI_API_KEY — …/bin/codex (sandbox-confined; needs verify_command)
  ChatGPT login: none (no Codex login on this machine (`codex login`))
- engine pi: MISSING — 'pi' not on PATH (sandbox-confined; needs verify_command)
- provider key relay: off — builtin workers hold the provider key (set provider_key_relay to relay it); claude_code, codex, aider and pi authenticate from their own auth env (not relayed)
- approvals: 0 pending
- memory: blocked at ~/.skep/supervisor/supervisor.sqlite3

Runtime checks:
- 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: skep doctor on a fresh throwaway SKEP_HOME, Fedora, 2026-11-18; paths shortened

blocked is expected here: no profile exists until skep onboard creates one. The engine lines show which agent binaries were found and whether their sign-in variables are set.

Container

The container image

The repository carries a Dockerfile and a compose file. This is what they do, read from the files themselves.

docker compose
$ git clone https://github.com/Anmolnoor/skep.git && cd skep
$ docker compose up -d
# the access token (kept out of the log)
$ docker compose exec skep cat /data/skep/supervisor/serve-token
  • The image is python:3.12-slim with git, bubblewrap and the GitHub CLI, and it runs skep serve on port 8765.
  • Everything skep writes lives under /data, a named volume (skep-data). The container itself is disposable.
  • The compose file passes ANTHROPIC_API_KEY and GH_TOKEN through from your shell when they are set.

Upgrade

Upgrading

Upgrade with the tool you installed with, then restart the daemon.

Upgrade commands
Installed withUpgrade
pipxpipx upgrade skep
uvuv tool upgrade skep
pippip install --upgrade skep, in the same environment
Sourcegit pull, then uv sync --frozen
  • A running skep serve keeps the old code until you restart it.
  • Your home (~/.skep) is kept. A home from an earlier release keeps deciding as it did.
  • A home with no approved policy baseline asks before every governed action until you approve one. skep onboard --check shows where a home stands.
  • What changed in each release is in the changelog.

Next

The first command

skep onboard connects a model, registers a work directory, records the sandbox, locks a policy baseline and opens the chat.

guided first run
$ skep onboard

Something broken? Open an issue and paste your skep doctor output. It prints variable names and paths, never a key.