Quickstart

The default development startup does not require a GPU. Use make up-lite for the smallest local resource profile, or make up for the full development stack. To choose which services run locally (real/stub/off), run make dev-select — see Configurable local stack.

Prerequisites

Requirement	Details
Git	git clone --recurse-submodules, or run make ensure-submodules before make up if submodules are missing.
Docker	Docker Engine 24+ with Compose V2.
Make + Python 3	Required by the make ensure-secrets and make up path.
OpenSSL	Used by the secret-generation script.
Disk + network	First startup pulls and builds several service images (~10 GB).
OpenRouter key	Required for the default no-GPU model path. Get one at openrouter.ai/keys. Skippable if you use make up GPU=single.

Steps

1. Clone the repository

git clone --recurse-submodules https://github.com/egroup-labs/aibox.git
cd aibox

If you already cloned without submodules:

git submodule update --init --recursive

2. Generate secret files

make ensure-secrets is idempotent. It populates deploy/secrets/ with fresh signing keys, internal service passwords, and Keycloak realm-user passwords. Files that already exist are left untouched.

make ensure-secrets

For the default (no-GPU) path, drop your OpenRouter key in:

printf '%s\n' 'sk-or-v1-your-key-here' > deploy/secrets/openrouter_api_key

For local GPU inference, write a Hugging Face token to deploy/secrets/hugging_face_hub_token if the bundled vLLM model is gated, then use make up GPU=single in step 3. Which model the bundled vLLM serves is a deploy fact set by vllm_model/vision_model in config/profiles/<name>.toml. Model selection per role (default, title, classifier, and so on) is runtime and admin-configurable through the inference router's model_roles — see Model Configuration.

3. Start the platform

make up

make up runs preflight checks, renders deploy/.compose.env from the active profile, and starts the dev compose stack. It does not initialize git submodules; run make ensure-submodules first if you cloned without --recurse-submodules. First run builds images and may take 5–15 minutes depending on disk and network.

For raw container output use make logs. To recheck readiness across all services use make health.

When iterating on the laptop stack, just run make up-lite again: it detects which services' sources changed since their last build and rebuilds only those, leaving the rest running. Use NO_REBUILD=1 to skip detection or REBUILD=all to force a full rebuild — see Operating one service.

4. Sign in

Open http://localhost. The dev realm seeds two accounts:

Account	Use
admin	Holds the admin role (sees /admin/*).
testuser	Regular user.

Passwords are generated locally by make ensure-secrets:

Account	Password file
admin	deploy/secrets/keycloak_realm_admin_password
testuser	deploy/secrets/keycloak_realm_testuser_password

The Keycloak master-admin console password is in deploy/secrets/keycloak_admin_password. No realm-user password is committed to the repository.

If 2FA is enabled for a user, sign-in completes through a mobile-push challenge to a paired device — see Authentication for device pairing.

5. Send a chat message

In the chat input, ask:

What can you help me with?

The response streams token-by-token. Tool calls, reasoning summaries, routing metadata, and receipt status appear in the message timeline when the turn uses those features.

Verify

• UI loads: http://localhost renders the chat surface after sign-in.

• Admin loads: http://localhost/admin renders the mission-control page when signed in as admin.

• Stack is healthy:

  make health

  All services should report 200 (or the documented healthy code for that service).

• Observability events flow: the first-party observability API is exposed through the gateway under /v1/admin/observability/* and stores generation events plus GenAI spans from the inference router.

Troubleshooting

• Missing OpenRouter key — deploy/secrets/openrouter_api_key is empty. Add one, then make restart-service SERVICE=inference-router.
• Port 80 already in use — stop the host's existing web server, or expose the frontend on another port by editing the frontend port mapping in deploy/docker-compose.yml.
• Keycloak slow on first boot — the postgres healthcheck allows up to 90 s on cold start; Keycloak waits behind it. make health will turn green once it finishes.

Next

• Chat
• Upload Documents
• Memory
• Run Code
• Guardrails
• Multi-Agent
• Admin Guide — User Management

---

Verified against commit 5187b91e (2026-06-11) · sources e40cbcb99b20.