Loading article…
Getting startedInstall and run locally
DocsDocsLoading article…
Use pinned Bun 1.4.2. Native macOS development is the current development track; Windows uses WSL2/Docker, with native Windows execution experimental. A Docker-compatible engine is needed for optional Mailpit, bucket initialization and container verification. Object storage is separately supplied by you, such as RustFS; there is no bundled MinIO service.
bun install --frozen-lockfile
cp .env.example .envEdit the new .env with your S3 endpoint/bucket/credentials and email provider selection. Do not commit it. Configure an endpoint reachable from the API process, then start native hot reload:
bun run devStudio runs on 7610, Docs on 7611 and API on 7612. The terminal startup panel confirms readiness and shows the service links; see terminal logging for display controls. Each app has independent workspace commands. Database files and generated local secrets live under ignored .data.
The launcher checks occupied ports and waits for the API to create/accept its worker credential. If the full Docker stack owns these ports, use its running apps or stop those application services before hot reload:
docker compose stop studio docs api worker
bun run devThis preserves database volumes and separately managed storage. Native .data and Docker's database volume are separate installations. A worker must use its API's QB_DATA_DIR or securely supplied QB_WORKER_TOKEN; never create/copy a token file to bypass startup checks.
Run RustFS or your chosen provider independently. For native development .env.example assumes an S3 endpoint at http://127.0.0.1:9000. Storage configuration explains the remaining variables and container addressing.
For local SMTP inbox capture:
docker compose up -d mailpitSelect QB_MAIL_PROVIDER=smtp, QB_SMTP_HOST=127.0.0.1 and QB_SMTP_PORT=7615 for native API development. Mailpit's inbox is on 7616. Alternatively configure Resend and React Email; explicit SMTP selection overrides a present Resend key.
The optional storage-init service runs inside Docker, so use a container-reachable endpoint when invoking it:
QB_S3_ENDPOINT=http://host.docker.internal:9000 docker compose run --rm --build storage-initThe service needs your configured bucket/credentials; provider provisioning failure is not a healthy storage configuration. Do not reuse example placeholders as real credentials.
Open Studio's setup flow. The one-time token is QB_BOOTSTRAP_TOKEN in your .env; bun run dev generates one there on first start if the key is missing, and Docker deployments take it from the Compose environment. Never commit it. Enter it with your name, email, password and organization. After setup the token is no longer required and Studio opens sign-in; setup cannot create another owner. Passwords require at least 12 characters. Production requires injected master/bootstrap/worker secrets and administrator MFA.
bun run qb doctor --directory .
bun run check
bun run buildDoctor is redacted inventory, not a live provider certification. The optional bun run spike checks integration candidates but does not make GraphQL/vector product capabilities available. See compatibility and production deployment.