Docker (community-maintained)

You can run Orbi in Docker with the community-maintained wrapper when the host cannot provide a systemd user session. The Docker deployment under 3rd/docker/ in the repository is a community-maintained, unofficial wrapper: one Linux container that runs the unmodified official deployment — systemd as PID 1 with a real user manager, the official systemd/[email protected] + [email protected] user units, the editable CLI install and the idempotent orbi setup. It is not a second deployment model: on a Linux host with a systemd user session, always prefer the official path (see Getting started) — pick one of the two, never both for the same task pool.

When to use it

The host has no user systemd session (a NAS, a container platform, a restricted cloud box) but can run Docker.
You want the runner isolated from the host user session.

Quick start

Pull the published image, then start the runner with one docker run. Both registries carry the same tags: latest and the release number without the v prefix (e.g. 0.5.17).

docker pull ghcr.io/orbi-build/orbi:latest
# the same image on Docker Hub:
docker pull docker.io/orbibuild/orbi:latest

One docker run reaches a real delivery: the GitHub token, the task pool and the model provider all come from environment variables, and the entrypoint turns them into the deploy-home env file, the generated orbi.toml and the generated pi-providers.json on first start (existing files are never overwritten). Substitute the three quoted values — token, repo, key; the DeepSeek endpoint is an example, any OpenAI-compatible endpoint works through the same four variables (ORBI_PI_PROVIDER, ORBI_PI_MODEL, ORBI_PI_BASE_URL, ORBI_PI_API_KEY). If you pulled from Docker Hub, use the docker.io/orbibuild/orbi:latest image reference instead.

# Optional model limits with their defaults — add them as -e lines to the
# command below (before the image reference) only to override:
#   -e ORBI_PI_API=openai-completions
#   -e ORBI_PI_CONTEXT_WINDOW=128000
#   -e ORBI_PI_MAX_TOKENS=16384
docker run -d --name orbi \
  --stop-signal SIGRTMIN+3 \
  --tmpfs /run --tmpfs /tmp \
  --cgroupns=host -v /sys/fs/cgroup:/sys/fs/cgroup:rw \
  -v orbi-deploy:/orbi \
  -v orbi-work:/work \
  -e GH_TOKEN="github_pat_xxx" \
  -e ORBI_SOURCE_REPO="OWNER/REPO" \
  -e ORBI_PI_PROVIDER=deepseek \
  -e ORBI_PI_MODEL=deepseek-flash \
  -e ORBI_PI_BASE_URL=https://api.deepseek.com \
  -e ORBI_PI_API_KEY="sk-xxx" \
  ghcr.io/orbi-build/orbi:latest

One docker run, no compose (the runner is a single service). --cgroupns=host plus the read-write /sys/fs/cgroup bind is what lets systemd run as PID 1 inside the container — without them /init.scope creation fails under the default private cgroup namespace (verified; no --privileged needed). All state (the orbi checkout, the config, the runtime state, the delivery checkout and its worktrees) lives in the two volumes, so a container rebuild keeps everything and the idempotent setup re-converges on the next start.

How configuration reaches the runner

You provide	How it reaches the runner
`ORBI_SOURCE_REPO`	The task pool repo. On first start the entrypoint clones it into the `/work` volume and writes it into the generated `orbi.toml`. Alternative: bind-mount an existing checkout (`-v ~/projects/myrepo:/work`) — the host uid must match the container’s `orbi` user (uid 1000), or git fails with dubious ownership.
`GH_TOKEN`	The entrypoint writes it to `/orbi/.orbi/env` (the systemd `EnvironmentFile`, mode 600), regenerated from the injected variables on every start. At tick time gh reads it there and the gh credential helper supplies git over HTTPS — no SSH key anywhere; the token is never baked into an image layer. It needs write access to the task-pool repo: a classic token with the `repo` scope, or a fine-grained token with Issues, pull requests and contents read+write (the runner creates labels, branches and PRs with it).
`ORBI_PI_PROVIDER`, `ORBI_PI_MODEL`, `ORBI_PI_BASE_URL`, `ORBI_PI_API_KEY`	The four model-provider values (set all four or none — a partial set fails the start, naming the missing ones). On every start the entrypoint regenerates `/orbi/.orbi/env` from the injected variables, writing `PI_API_KEY` into it — a changed `ORBI_PI_API_KEY` takes effect on the next `docker run`/`docker restart` with no manual edit; `/orbi/.orbi/pi-providers.json` (one provider and one model whose `apiKey` references `$PI_API_KEY` — the key value never lands in the JSON) and the `pi_provider`, `pi_model`, `pi_providers` lines in `orbi.toml` are generated on first start only and never overwritten.
`ORBI_PI_API`, `ORBI_PI_CONTEXT_WINDOW`, `ORBI_PI_MAX_TOKENS`	Optional limits for the generated `pi-providers.json`; defaults `openai-completions`, `128000`, `16384`.
`ORBI_BASE_BRANCH`	Optional delivery base branch (default `main`).
`ORBI_ENV_<NAME>`	Optional, repeatable: forwarded to `/orbi/.orbi/env` as `<NAME>=<value>` (e.g. `ORBI_ENV_GROQ_API_KEY` lands as `GROQ_API_KEY`) so a provider file can reference it — see Advanced: several providers below.
`orbi-deploy` volume → `/orbi`	The deploy-home volume: the orbi source checkout (`engine_source_track = "release"` follows the latest release automatically), the generated `orbi.toml`, the `.orbi/env` credential file and the `.orbi/` runtime state.
`orbi-work` volume → `/work`	The delivery-checkout volume: the task-pool clone, the task worktrees under `/work/.worktrees/` and the slot locks under `/work/.orbi/`.

The full contract — the generated config, daily operations, and the failure/repair table — lives in 3rd/docker/README.md.

First delivery

With the runner up, deliver a real task:

In the task pool repo, open an Issue stating ONE runtime outcome in one of the two shapes: a fix (when X, should Y, actually Z) or a change (when X, the user should be able to Y; today they cannot because Z).
Add the ai-ready label (the first start created the twelve platform labels).
Follow the tick log:

docker exec -u orbi -e XDG_RUNTIME_DIR=/run/user/1000 orbi \
  journalctl --user -u [email protected] -f

Within two ticks (the timer fires every 5 minutes) the Issue walks ai-ready → ai-in-progress → ai-pr-opened and a PR opens; it merges (ai-merged) after the independent review round. No docker exec configuration step is needed anywhere in this path — one that is required is a docs or entrypoint defect.

Orbi quick guide

The delivery vocabulary in one place; each link goes to the full reference instead of duplicating it.

The task — an Issue stating ONE runtime outcome in one of the two shapes: a fix (when X, should Y, actually Z) or a change (when X, the user should be able to Y; today they cannot because Z), plus a short acceptance list: the user journey as precondition → command/configuration → the success the user sees → the failure path with its repair.
The labels — ai-ready is the execution switch: the runner only picks up labelled Issues (pickup order: p0 first, then bug, then plain). A claimed Issue walks ai-in-progress → ai-pr-opened → ai-merged (terminal; the PR body’s Fixes #N closes the Issue) or ai-fix-needed (the next review round fixes the finding); ai-blocked (terminal) needs a human decision. ai-epic marks a coordination-only Issue the runner never claims, and ai-release marks a release task (below). The runner manages the delivery states; ai-ready, ai-epic, ai-release, p0 and bug are yours to add and remove.
Watching — the run keeps exactly one progress comment on the Issue, updated in place at every milestone, and the tick log streams through the journalctl command above.
What to expect — within two ticks the branch and PR exist (Fixes #N in the body), an independent review session runs (at most 5 rounds), and the merge lands exactly the reviewed head — GitHub then closes the Issue.
Releases — a release is its own Issue labelled ai-ready + ai-release whose body declares a ## Release block: version, base_branch, and a scope (a list of #N items) or scope_from_milestone. The Runner’s release state machine freezes the base, waits for green CI, bumps the version, tags, publishes the GitHub Release and closes the matching Milestone — no PR; any failure stops at ai-blocked for a human decision.

Full reference: Workflow (labels, review loop, release state machine) and Operations (observability, journal).

Operations

Command	What it does
`docker logs -f orbi`	setup result (`setup=ok` or `setup_failed ...`) + systemd console
`docker exec -u orbi -e XDG_RUNTIME_DIR=/run/user/1000 orbi journalctl --user -u [email protected] -n 50 --no-pager`	the runner tick logs
`docker exec -u orbi -w /orbi orbi bash -c '~/.local/bin/orbi status'`	queue and current task (a debug attachment)
`docker exec -u orbi -w /orbi -e XDG_RUNTIME_DIR=/run/user/1000 orbi bash -c '~/.local/bin/orbi doctor'`	deployment health check
`docker exec -u orbi -e XDG_RUNTIME_DIR=/run/user/1000 orbi systemctl --user list-timers`	the next tick time
`docker exec -u orbi -e XDG_RUNTIME_DIR=/run/user/1000 orbi systemctl --user start [email protected]`	trigger a tick immediately
`docker stop -t 30 orbi && docker rm orbi`	stop and remove (the two volumes keep all state)
`docker volume rm orbi-deploy orbi-work`	wipe all state

In-container commands run as -u orbi (the user the runner runs as); systemctl --user / journalctl --user need the user session bus, which docker exec does not carry automatically — hence -e XDG_RUNTIME_DIR=/run/user/1000. The orbi CLI installs into the orbi user’s ~/.local/bin, which is not on the docker exec PATH — hence the bash -c wrapper (docker exec sets HOME for the -u user). Upgrading: docker pull the newer tag and recreate the container with the same volumes and variables — state survives in the volumes and the entrypoint plus orbi setup re-converge.

Build from source

When you need to change the wrapper itself (the entrypoint, the setup oneshot, the Dockerfile), build the image from a repository checkout instead of pulling:

git clone https://github.com/orbi-build/orbi.git
cd orbi
docker build -t orbi-docker 3rd/docker

Then run the same docker run as in the Quick start with orbi-docker as the image name. The image contains no credentials — configuration is injected per the table above at docker run time.

Advanced: several providers

The Quick start configures ONE provider from environment variables. To serve several (e.g. deepseek plus groq):

Pass the extra keys at docker run time via ORBI_ENV_<NAME> (repeatable): -e ORBI_ENV_GROQ_API_KEY="gsk-xxx" lands in /orbi/.orbi/env as GROQ_API_KEY.
Edit /orbi/.orbi/pi-providers.json — the entrypoint generated it with one provider and never overwrites an existing file — and add the other providers, each apiKey referencing its env variable ("$GROQ_API_KEY").
Point pi_provider / pi_model in /orbi/orbi.toml at the provider and model to use, then restart the container: docker restart orbi (both files are yours — the entrypoint never overwrites an existing config).

If the first start had no provider variables at all, no pi-providers.json was generated; orbi setup scaffolds a starter file to fill in instead. Verify the endpoint before relying on it:

docker exec -u orbi orbi bash -c '. /orbi/.orbi/env && pi --provider deepseek \
  --model deepseek-flash --api-key "$PI_API_KEY" \
  --print "reply with the single word: ok"'

A real API reply means endpoint and key work; 401 or a timeout is a key or network problem.

Boundaries

Thin wrapper only: src/orbi/ core code is untouched, and a blocker hit inside the container is filed as its own core Issue.
Linux only; no compose, no multi-container orchestration, no automatic image updates; not part of the PyPI release or the getting-started main path.
Community-maintained: official Issues prioritize the core systemd path.

Start here

Concepts

Model providers

Configure & run

Contribute

Reference

Releases

Docker (community-maintained)

When to use it

Quick start

How configuration reaches the runner

First delivery

Orbi quick guide

Operations

Build from source

Advanced: several providers

Boundaries

​When to use it

​Quick start

​How configuration reaches the runner

​First delivery

​Orbi quick guide

​Operations

​Build from source

​Advanced: several providers

​Boundaries

When to use it

Quick start

How configuration reaches the runner

First delivery

Orbi quick guide

Operations

Build from source

Advanced: several providers

Boundaries