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.
$ pipx install skep && skep onboard skep --version skep 1.6.0 (worker contract 0.3.8)
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.
# 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.
# 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.
$ 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.
$ 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.
# Debian, Ubuntu
$ sudo apt install bubblewrap
# Fedora
$ sudo dnf install bubblewrap
# the last line reports the sandbox
$ skep doctor 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.
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.
$ 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-slimwith git, bubblewrap and the GitHub CLI, and it runsskep serveon port 8765. - Everything skep writes lives under
/data, a named volume (skep-data). The container itself is disposable. - The compose file passes
ANTHROPIC_API_KEYandGH_TOKENthrough from your shell when they are set.
Upgrade
Upgrading
Upgrade with the tool you installed with, then restart the daemon.
| Installed with | Upgrade |
|---|---|
| pipx | pipx upgrade skep |
| uv | uv tool upgrade skep |
| pip | pip install --upgrade skep, in the same environment |
| Source | git pull, then uv sync --frozen |
- A running
skep servekeeps 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 --checkshows 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.
$ skep onboard
Something broken? Open an issue and paste your
skep doctor output. It prints variable names and paths, never a key.