Install ORCA on Ubuntu.

Hardware

Single-node reference stack on one Ubuntu host.

LLM inference uses your configured model provider — no GPU required on the host.

How secrets work

Before you start

• Ubuntu 22.04+ (or current LTS)
• ~4 GB RAM for the Compose stack
• Outbound HTTPS (Slack, model APIs)
• Public repo clone works over HTTPS — no GitHub SSH key required

0 Pick your org slug

Pick a kebab-case org slug — your Instance identifier (one org per host). Use the same slug in every --org flag, instance path, and database name:

• --org {slug}
• ~/.orca/instances/{slug}/
• orca_{slug_with_underscores} (Postgres database)

Example (fictional): Acme Corp → slug acmecorp. Steps 5–8 walk through that example — replace acmecorp with your slug if you picked a different one.

1 System packages

sudo apt update
sudo apt install -y git curl ca-certificates postgresql-client \
  python3-venv python3-pip docker.io docker-compose-v2

python3 --version   # need 3.12+

If python3 -m venv fails later: sudo apt install -y python3.14-venv (or python3-venv).

2 Docker (non-root)

Required before docker compose or orca install Docker checks.

sudo systemctl enable --now docker

sudo usermod -aG docker $USER
newgrp docker
# or log out and SSH back in

docker ps

An empty container list is fine. Permission denied → re-login or newgrp docker.

3 Clone and install ORCA

Public repo — HTTPS works without a GitHub SSH key. Stop if clone fails — do not create a venv outside the repo.

Option A — Clone + venv (lab / development)

mkdir -p ~/Projects && cd ~/Projects

git clone https://github.com/orca-core/orca.git
cd orca
ls pyproject.toml   # must exist

python3 -m venv .venv
.venv/bin/pip install -U pip
.venv/bin/pip install -e ".[dev]"

.venv/bin/orca install
.venv/bin/orca version

On Ubuntu, use .venv/bin/orca — not /usr/bin/orca (GNOME screen reader).

Option B — install.sh (CLI only)

curl -fsSL https://raw.githubusercontent.com/orca-core/orca/main/install.sh | bash
orca install
orca version

Installs the CLI via pipx or uv. Does not start Compose or create an Instance — continue with Steps 4–8.

4 Compose stack (Postgres + Qdrant)

From repo root. Greenfield Postgres listens on host port 5433.

4a — Start stack

cd ~/Projects/orca

docker compose -f templates/compose/docker-compose.yml --profile full up -d
docker compose -f templates/compose/docker-compose.yml ps

4b — Health check

curl -s http://127.0.0.1:6333/healthz

4c — Admin URL for instance create

export ORCA_POSTGRES_ADMIN_URL='postgresql://orca:orca@127.0.0.1:5433/orca'

This export lasts for your current shell only — re-run after a new SSH session. Reusing host Postgres on :5432? Use the qdrant-only profile — Compose README.

5 Create instance

Using the Acme Corp example (acmecorp) from Step 0. Creates ~/.orca/instances/acmecorp/, database orca_acmecorp, Qdrant collection acmecorp_memory_v1, scaffolds config/secrets.env.example, and sets secrets.backend: local in config/instance.yaml. Gitignore is seeded on create.

cd ~/Projects/orca

.venv/bin/orca instance create --org acmecorp \
  --postgres-admin-url "$ORCA_POSTGRES_ADMIN_URL" \
  --qdrant-url http://127.0.0.1:6333

A Qdrant client vs server version warning is harmless for MVP smoke tests.

6 Copy and fill secrets file

cd ~/.orca/instances/acmecorp/config

cp secrets.env.example secrets.env
chmod 600 secrets.env

Open secrets.env in your editor and set the required Postgres URL:

POSTGRES_DATABASE_URL=postgresql://orca:orca@127.0.0.1:5433/orca_acmecorp

Value must be only the URL — no key= prefix. Leave optional slots (Slack, Git deploy key, LLM key) empty until you enable those features.

6a — Validate

cd ~/Projects/orca

.venv/bin/orca secrets validate --org acmecorp
.venv/bin/orca secrets doctor --org acmecorp

Expected: [OK] POSTGRES_DATABASE_URL. Validate prints slot names only — never secret values.

7 Smoke tests

cd ~/Projects/orca

.venv/bin/orca upgrade --org acmecorp
.venv/bin/orca instance backup --org acmecorp
.venv/bin/orca doctor --org acmecorp
ls -la ~/.orca/instances/acmecorp/backups/

upgrade applies workflow migrations on first run. backup writes manifest, git bundle, SQL dump, and config under backups/.

8 Run and connect Slack

Add Slack tokens to ~/.orca/instances/acmecorp/config/secrets.env (SLACK_BOT_TOKEN, SLACK_APP_TOKEN, SLACK_SIGNING_SECRET). Configure operator and approval channels in instance config, then:

.venv/bin/orca serve --org acmecorp

Send a message in the operator channel — AVA should respond with capture or Q&A routed through the governance gateway.

Documentation