Skip to main content
Use this to develop against Opengeni or try it before self-hosting. For production, see Self-host.

​
Prerequisites

  • macOS or Linux (WSL2 on Windows).
  • Bun at the version in .bun-version.
  • Git and curl.
  • Docker with a running daemon, or the native services described in Local development.
Run bun run dev:check to diagnose missing prerequisites.

​
Start the stack

This installs dependencies, starts Postgres, NATS, Temporal and object storage, runs migrations, and starts the API, workers and web app. Wait for Opengeni dev stack ready; the first start can take several minutes. If a port is busy, the launcher picks a free one and prints the URLs it used. The local stack has no login: it runs as a single dev user with broad permissions. By default the agent runs commands directly on your machine, so everything listens only on 127.0.0.1. To run the agent in a container instead, set OPENGENI_SANDBOX_BACKEND=docker. Connect a model in Organization settings → Models, or set a key in .env.

​
Configure

.env holds all configuration. Common settings: Model credentials stay out of the agent sandbox unless you allow them. See the model providers guide.

​
Troubleshooting

  • Bun version mismatch: install the pinned version with curl -fsSL https://bun.com/install | bash -s "bun-v$(cat .bun-version)".
  • Database errors after switching branches: the database must match the checkout. Run bun run dev:clean -- --yes to start fresh (this deletes local data).

​
Stop

Press Ctrl-C to stop the launcher, then:
bun run dev:clean -- --yes also deletes this checkout’s local data.

​
Run tests

Typechecks and unit tests need no running services:
See Local development and CONTRIBUTING.md for more.