Getting started
Install oc8 yourself? Start with the step-by-step Quickstart — install and run.
This guide covers alternative paths and troubleshooting after you have a running instance.
Choose your path
| Path | Best for | Time |
|---|---|---|
| Quickstart script | Operators evaluating oc8 on a laptop or VM | ~10 min |
| Full Compose stack | Same, with explicit control over .env | ~15 min |
| Manual backend dev | Core contributors debugging the runtime | ~30 min |
Path A — Quickstart (recommended)
From the repository root:
./scripts/quickstart.sh # macOS / Linux
# Windows PowerShell:
.\scripts\quickstart.ps1
The script checks Docker, creates missing secrets in .env, builds and starts
the stack, waits for /health, and prints the local URL.
- Open the URL in your browser.
- Walk through the welcome wizard — organisation, department, agent, model, tool, and guardrails (all in the UI).
- Run a first task from Office or the agent page; approvals land in My work.
You only need Settings → Models or .env keys if you skipped the wizard or
want a provider configured outside the UI flow.
→ Welcome wizard · Quickstart (full steps)
For a demo stack with seeded tenants and dev-login (local only, never expose to a network):
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
Path B — Docker Compose (explicit)
cp .env.example .env
# Edit .env: set OC8_JWT_SECRET, OC8_SECRET_KEK, POSTGRES_PASSWORD (see DEPLOY.md)
docker compose up -d --build
Follow Deploy for ports and production hardening. Then use the welcome wizard in the browser (same as Path A).
Path C — Manual developer setup
For running the API and worker outside Compose (fast iteration on backend code):
- Read First run (API-level) — Postgres, migrate, seed, uvicorn, worker, curl-based agent + MCP filesystem demo.
- Read Contributing: architecture if you will change core code.
After your first run
| Next step | Document |
|---|---|
| Understand vocabulary (department, capa, frame, …) | Key concepts |
| Day-to-day operator workflow | Daily workflow |
| Approvals and autonomy | Governance and approvals |
| Install on a server | Install and maintain |
| Build an integration | Developer: first capa |
Troubleshooting
| Symptom | Likely cause |
|---|---|
Run stays queued | Worker not running — docker compose ps worker or start oc8 worker manually |
| Model errors / timeout | Provider key missing, or Ollama not running / wrong model tag |
| No tools available | MCP connection not configured, or capa not installed/enabled |
| 401 on API | Token expired — re-login; in dev use /auth/dev-login only on localhost |
More detail: Scope and limitations.