Skip to main content
Set up for development gets you to mise dev --agent. This page covers what else you can start. Run every command from the repository root. Each one starts the databases in Docker first, then runs your code with hot reload.

​
Choose how you sign in

--agent and --sim act as the user in DEV_USER (default dev@gaia.local). Run mise seed once so that user exists. Both refuse to start when ENV=production.
Start with DEV_USER=alice@example.com mise dev --agent, and seed the same email with DEV_USER=alice@example.com mise seed.For a single request, send the header X-Dev-User: <email>.
Put instructions in your message. [[say:Hello!]] makes GAIA reply “Hello!”. [[tool:<name> {"arg": "value"}]] makes it call a tool first. A message without instructions gets a fixed reply.The format lives in tools/llm-stub/directives.py.
Plain mise dev shows the login page.
  • Team members use WorkOS with keys from Infisical: mise infisical dev.
  • Outside contributors use AUTH_MODE=local. Set NEXT_PUBLIC_GAIA_SELFHOST=true in apps/web/.env, restart, then open localhost:3000/signup. The first account becomes the administrator.

​
Start more of GAIA

mise dev runs the API and web app. Everything else runs as its own process. --agent and --sim work only on mise dev and mise dev:vm. The combined commands use the real sign-in flow. For skipped login plus the worker, run mise dev --agent and nx worker api in two terminals.
Workspace files use JuiceFS, which needs a FUSE mount that macOS and Windows processes can’t make. On plain mise dev those features raise JuiceFSUnavailable. mise dev:vm runs the API in a Linux container where the mount works.It needs the R2 storage keys in apps/api/.env: R2_ACCOUNT_ID, R2_BUCKET, R2_ACCESS_KEY, R2_SECRET_KEY and JUICEFS_META_URL_TEMPLATE. Stop mise dev first, since both use port 8000.

​
Ports and several checkouts

mise dev stops if port 8000 or 3000 is taken, and names the process holding it. To run a second checkout at the same time, such as another git worktree, run this in it:
It writes .env.worktree with free ports, and mise loads it for every task. Delete the file to go back to the defaults. Both checkouts share the same databases.

​
The databases

mise bootstrap and every mise dev* command start these in Docker. Your data survives restarts. Stop everything with nx run docker:docker:down. See Docker for development for profiles and resetting data.

​
Next

Testing

Which tests to run for your change.