Run it locally

Two ways to run an agent on your own machine.

aai dev — while you are building

aai dev

Starts a local server and prints a URL. Open it and click the microphone.

Edit agent.ts, a tool, or system-prompt.md and it rebuilds and replaces the server.

npm start — a plain Node process

npm start                          # http://127.0.0.1:3000
PORT=8080 HOST=0.0.0.0 npm start   # bind every interface, e.g. in a container

This is the deployment counterpart of aai dev: no platform account, nothing managed. The scaffold’s prestart script builds first (aai build --skip-tests), then aai start serves the result.

aai start on its own never builds — it fails and tells you to run aai build. It serves your client.tsx build when there is one, and falls back to the default UI otherwise.

It listens on localhost for a reason

This server has no request authentication of its own, so set HOST=0.0.0.0 only behind your own proxy or auth.

There is no server file in your project. When you need to own the startup — your own routes, your own auth — see Self-hosting.

Watching and restarts

Watching is on when you run aai dev at a terminal. --watch=false (or AAI_DEV_WATCH=0) turns it off.

A restart ends any voice session in flight. That is right while you are editing and wrong while something drives the agent for twenty minutes — so a harness or process supervisor, which has no TTY, gets no watcher unless it sets AAI_DEV_WATCH=1.

What the dev server can see

Two things behave differently here than they do deployed.

Secrets come from .env in the project root. Only keys declared there are visible to your tools as ctx.env. On the platform the same keys come from the agent’s secrets, which aai publish syncs from that same file.

Session state lives in memory for the life of the process, so a restart forgets it; deployed, it is stored for you. Point a DATABASE_URL at your own Postgres in .env and it becomes durable here too — same code either way. See Remembering things.

Environment variables in a container

A real environment variable beats the file’s value, so docker run -e MY_API_KEY=… needs no .env in the image.

That works only for keys something declares, and .env.example counts as a declaration and ships. A variable nothing declares never reaches ctx.env.

For Vercel, Deno Deploy, or Modal rather than a container, see Deploy anywhere.

Next

• Publish — the managed platform, in two commands
• Deploy anywhere — Vercel, Deno Deploy, Modal
• Self-hosting — owning the startup yourself