Quick Start

Prerequisites

Docker Desktop 4.x or later (Linux: Docker Engine + Compose v2)
Bun 1.1.40+ — curl -fsSL https://bun.sh/install | bash
A PostgreSQL 16 compatible connection (included in compose)
An LLM provider API key (Anthropic, OpenAI, or Azure OpenAI)

1. Clone and install

git clone https://github.com/your-org/orginabox
cd orginabox
bun install

2. Copy environment config

cp .env.example .env

Edit .env and set at minimum:

# PostgreSQL (defaults work with compose)
POSTGRES_PASSWORD=your-password

# LLM provider — at least one required
ANTHROPIC_API_KEY=sk-ant-...
# or
OPENAI_API_KEY=sk-...

# API security token
ORGINABOX_API_KEY=change-me-in-production

# opencode sandbox password (optional but recommended)
OPENCODE_SERVER_PASSWORD=sandbox-secret

3. Start the stack

bun compose:up
# or equivalently:
docker compose up -d

This starts:

postgres — PostgreSQL 16 + pgvector on port 5432
sandbox — Ubuntu VM with opencode + noVNC on ports 4096 / 6080
orginabox-worker — job drainer (runs migrations on boot, seeds templates)

Migrations run automatically on first boot.

4. Run the setup wizard

bun orginabox setup

Follow the prompts to configure your LLM provider. The wizard writes credentials encrypted with AES-256-GCM into the database.

5. Open the TUI

bun orginabox chat

You're in. Type a message and your agent responds. Type /help to see all commands.

6. (Optional) Start the web dashboard

cd packages/web && bun dev
# open http://localhost:3000

7. (Optional) Start the docs site

cd packages/docs && bun dev
# open http://localhost:3001/docs

Next steps

Configuration — All environment variables and their defaults.
First Agent — Walk through your first agent task end-to-end.
Gateways — Connect Slack, Teams, Telegram, Discord, or Email.