Quickstart — install and run oc8

Get a working oc8 instance on your own machine or server in about 10–15 minutes. No oc8.cloud account — you host everything yourself.

What you need

Requirement	Notes
Docker + Compose v2	docker compose version must work
4 GB+ free RAM	More if you run Ollama locally
Git	To clone the repository
Network	Images pull from public registries on first start

Alternative: Podman instead of Docker — see Deploy § Podman.

Windows: use PowerShell and .\scripts\quickstart.ps1 instead of the bash script below.

---

Step 1 — Get the code

git clone https://github.com/oc8/oc8.git
cd oc8

Or download and unpack a release tarball from GitHub if you prefer not to use git.

---

Step 2 — Start the stack

From the repository root:

./scripts/quickstart.sh

The script will:

1. Check that Docker (or Podman) is running
2. Create .env from .env.example if missing
3. Generate secrets (OC8_JWT_SECRET, OC8_SECRET_KEK, POSTGRES_PASSWORD)
4. Build and start all services (Postgres, Redis, API, workers, frontend, Caddy)
5. Wait until /health responds
6. Print the URL to open in your browser (usually http://localhost/ or a custom port if 80 is taken)

Manual alternative (same result, more control):

cp .env.example .env
# Set the three required secrets — see DEPLOY.md
docker compose up -d --build

→ Full details: Deploy

---

Step 3 — First login and welcome wizard

1. Open the URL printed by the script.
2. Complete the administrator setup wizard — organisation, first department, first agent, model, first tool, guardrails.
3. When you finish, you land in Office.

The wizard is the normal path. You do not need to edit .env or run extra Docker commands for a first try — configure the model in Settings → Models when the wizard asks (or right after in the UI).

→ Screen-by-screen: Welcome wizard

On a fresh demo install with docker-compose.dev.yml, dev-login may skip the wizard and show seeded demo data. Use that only on localhost, never on a network-reachable host.

---

Step 4 — Run your first task

If you completed the wizard, you already have a department, agent, and model.

1. Open Office or go to your agent.
2. Click Run (or use chat) and describe one clear outcome.
3. Watch the run in Live Log or Activity.
4. If something needs a human, check My work — not a separate Approvals menu.

---

Optional — finish setup in the UI later

Skipped a wizard step? Use the sidebar — no terminal required:

You still need…	Where in the UI
A model	Settings → Models
Tools / integrations	Capas
Team boundaries	Departments
Another agent	Agents or hire from a capa template
Pilot checklist	Settings → General

→ UI guide · How work moves

---

Advanced — configure models via .env or Ollama

Use this only if you prefer provider keys in the host environment, or you run Ollama as a Compose profile. The UI wizard and Settings → Models work without these steps.

Cloud provider key in .env

# One of:
OC8_ANTHROPIC_API_KEY=sk-ant-...
OC8_OPENAI_API_KEY=sk-...

docker compose up -d

Then in the UI: Settings → Models — pick the provider you configured.

Local Ollama (no cloud API key)

docker compose --profile ollama up -d
docker compose exec ollama ollama pull mistral

In Settings → Models, select the Ollama model you pulled.

---

Verify the stack (optional)

curl -s http://localhost/health
# -> {"status":"ok",...}

docker compose ps
# migrate = exited(0); backend, worker, frontend, caddy = running

---

Before you expose this to the internet

The default stack is for local evaluation. Before anyone else can reach it:

Must do	Why
Set OC8_ENV=prod	Disables unauthenticated dev-login
Configure real login	Wizard / local accounts — not dev-login on a public URL
Use TLS (reverse proxy)	Default is HTTP only
Rehearse backup/restore	BACKUP_RESTORE
Read scope & limits	SCOPE_AND_LIMITATIONS

---

Troubleshooting

Problem	Fix
Script says Docker not running	Start Docker Desktop / systemctl start docker
Port 80 in use	Set OC8_HTTP_PORT=8090 in .env, re-run docker compose up -d
Run stays queued	Check worker: docker compose ps worker — restart if needed
Model errors	Add or fix provider in Settings → Models (or wizard); for .env/Ollama see Advanced
Blank page after start	Wait for migrate to finish: docker compose logs migrate

---

What's next

Goal	Document
Understand vocabulary	Key concepts
Day-to-day operator work	Daily workflow
Approvals and autonomy	Governance and approvals
Deploy on a server	Install and maintain
Build an integration	Developer: first capa