Documentation menu
On this page

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_TOKEN is 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 with docker compose stop skep or 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.internal instead of 127.0.0.1.
  • If you need a completely clean local source state, stop the server and remove .skep-dev. For Docker, remove the skep-data volume only if you deliberately want to delete all supervisor state.