How to Use skep on a New Machine
This guide is for getting a fresh machine from zero to a usable skep
supervisor. The normal source runtime and local image build are one-repo: the
default worker, dashboard, storage, and Docker build all live in this checkout.
Prerequisites
-
Git.
-
Python 3.12 or newer.
-
uv(Python package manager used by this repo):curl -LsSf https://astral.sh/uv/install.sh | sh -
Docker Desktop or Docker Engine, only if you want the container path.
-
An LLM/provider connection for real coding runs. You can configure this in the web Settings page after boot.
GH_TOKENis optional and only needed for GitHub PR actions.
Run from Source
git clone https://github.com/Anmolnoor/skep.git
cd skep
uv sync --frozen
export SKEP_HOME="$PWD/.skep-dev"
uv run skep serve --host 127.0.0.1 --port 8765
The server prints an access token at startup:
access token: ...
Open http://127.0.0.1:8765, paste that token, then go to Settings. Configure
the assistant connection, test it, and select the default model. The default
coding worker uses the saved assistant connection when no explicit worker
profile exists.
For a local CLI run:
uv run skep run /path/to/repo "Fix the failing test" --execution-mode workspace
uv run skep status --personal
uv run skep review <task_id>
uv run skep review <task_id> --approve
By default, skep dispatches its in-repo coding worker. To use another worker
explicitly, pass --worker-cmd or set SKEP_WORKER_CMD. See
docs/workers.md for the Claude Code adapter.
Run with Docker
If a published image is available, this is the simplest container path:
docker run -d --name skep -p 8765:8765 -v skep-data:/data \
-e GH_TOKEN="$GH_TOKEN" \
ghcr.io/anmolnoor/skep:latest
docker exec skep cat /data/skep/supervisor/serve-token
Copy that access token and open http://127.0.0.1:8765. skep prints the token
only to a terminal, so docker logs shows where it lives, not its value. Container state
lives in the skep-data volume.
The checked-in docker-compose.yml can also use the published image:
docker compose pull skep
docker compose up -d --no-build
docker compose exec skep cat /data/skep/supervisor/serve-token
Local image builds use this checkout as the build context.
make image
Optional Quality Gates
The default development gates run from this repo:
make all
The default smoke gate stays inside this repo:
make smoke
Common Checks
- If the browser rejects requests, use the latest access token printed by the running server or container logs.
- If Docker is already bound to
8765, stop it withdocker compose stop skepor use another source-run port such as--port 8766. - If coding runs cannot reach the model provider, check the Settings connection
test first. For a host-local provider from Docker on macOS/Windows, use
host.docker.internalinstead of127.0.0.1. - If you need a completely clean local source state, stop the server and remove
.skep-dev. For Docker, remove theskep-datavolume only if you deliberately want to delete all supervisor state.