Quick Start

Demo Flow

flowchart LR
  A[Clone and install] --> B[Start postgres sandbox worker]
  B --> C[Run setup wizard]
  C --> D[Add provider credentials]
  D --> E[Apply runtime bundle]
  E --> F[Open browser chat]
  F --> G[Optional gateway pairing]

The quick-start path below gets you to a local demo with a real provider, an applied runtime, and a live chat session. Gateway pairing is optional for browser demos. If provider credentials change later, the sandbox does not see them until you apply the runtime again.

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/ruchit-p/orginabox-azure.git 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
# local `bun compose:up` auto-generates this if it is blank
# set it manually only if you use raw `docker compose`
OPENCODE_SERVER_PASSWORD=

3. Start the stack

bun compose:up
# equivalent:
OPENCODE_SERVER_PASSWORD=strong-random-secret docker compose -f docker-compose.yml --profile web --profile docs up -d

This starts:

postgres: PostgreSQL 16 + pgvector on port 5432
sandbox: Ubuntu VM with opencode + noVNC on ports 4096 / 6080
orginabox-api: Hono API on port 8787
orginabox-web: web dashboard on port 3000
orginabox-platform-web: platform admin app on port 3002
orginabox-tenant-web: tenant admin app on port 3003
docs: docs site on port 3001
orginabox-worker: job drainer (runs migrations on boot, seeds templates)

Migrations run automatically on first boot.

bun compose:up intentionally uses the stable demo stack from docker-compose.yml and auto-provisions the internal sandbox password the first time you run it. Contributor-only hot-reload development lives behind bun run compose:dev:up.

4. Finish setup in the browser or the CLI

You can complete setup entirely in the bundled web app or entirely in the CLI. Both paths stage the same provider/runtime state and both can take you all the way to a working agent.

Browser path

open http://localhost:3000

Use the onboarding flow to:

sign in or open the local workspace
add your provider credentials
skip channel pairing if you only need browser chat for the demo
apply the staged runtime if the UI says the new provider/model is not live yet

Once onboarding says the runtime is active, browser chat is ready immediately.

CLI path

bun orginabox setup

Follow the prompts to configure your LLM provider. The wizard writes credentials encrypted with AES-256-GCM into the database and stages a new runtime bundle.

Apply the runtime before opening chat:

bun orginabox runtime status
bun orginabox runtime apply

runtime status shows whether the sandbox is still running an older applied bundle. runtime apply promotes the staged bundle, reloads the sandbox runtime, and makes the new provider/model active.

5. Open the TUI

bun orginabox chat

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

6. Open the bundled UIs

open http://localhost:3000
open http://localhost:3001
open http://localhost:3002
open http://localhost:3003

Once the runtime is active, browser chat is ready immediately whether you finished setup in the web app or the CLI. Slack, Teams, and Email pairing can happen later without blocking the web demo.

If you save more than one provider, open Settings → Providers in the web app to switch the active provider or replace the default model and credential.

Next steps

Contributor hot-reload lives behind bun run compose:dev:up if you want the separate development stack instead of the stable demo stack above.
Configuration: All environment variables and their defaults.
First Agent: Walk through your first agent task end-to-end.
Troubleshooting: Fix chat, provider, and runtime issues quickly.
Gateways: Connect Slack, Teams, or Email.