Offline AI agent development, no internet required.
You don't need the cloud to build. `a2a dev --local` runs the entire agent on your machine — a Docker container by default, or a plain Python process with `--host-runtime` — so you can develop on a plane, behind a corporate firewall, or in an air-gapped environment. It loads config from local files, mounts a local workspace, hot-reloads on save, and gives you a `/_dev` console at localhost. The same code deploys, unchanged, when you're back online.
local loop · docker or host-runtime · deploys online
Most agent dev loops stop working the moment you go offline.
Hosted IDEs and cloud dev sandboxes run the agent on someone else's server, so the connection is the dev loop — lose it on a plane, behind a firewall, or in an air-gapped office and everything stalls. Even 'local' setups often phone home to provision a workspace or reach a managed Postgres before they'll boot. And the cloud sandbox is frequently a different environment than what actually ships, so 'works in the sandbox' doesn't mean 'works deployed.'
The whole dev loop runs on your machine.
`a2a dev --local` runs the agent locally — Docker by default, or a bare Python process with `--host-runtime`. It reads `.env.local` and `~/.a2a/credentials.json` from disk, mounts a local workspace, hot-reloads on save, and exposes a `/_dev` console at localhost. `a2a chat` brings up local Postgres and Qdrant. When you reconnect, `a2a deploy` ships the same code.
a2a dev --local
`a2a dev --local` runs the entire agent on your machine. Default is a Docker container; pass `--host-runtime` to run it as a plain Python process instead. No cloud round-trip to start the loop — it's documented as the offline / air-gapped fallback, not a degraded mode.
Docker or a bare Python process
Prefer isolation, run in Docker. Locked down, no daemon, or just want a fast inner loop? `--host-runtime` starts the agent as a direct Python process on the host. Either way the agent is executing locally — the choice is about your environment, not connectivity.
Local config, no fetch
The local loop loads `.env.local` and your agent setup from `~/.a2a/credentials.json` on disk, and mounts a local workspace. Nothing is pulled from the control plane to boot the agent — the inputs it needs are files already on your machine.
Hot reload + /_dev console
Edit code and the local runtime reloads; poke the agent through the `/_dev` console at localhost. The full inner-loop experience — save, reload, inspect — runs entirely on the box in front of you, whether that box has a network or not.
Local datastores, no cloud dependency
`a2a chat` brings up local resources — a Docker Compose Postgres and Qdrant — on your machine. The agent's database and vector store run locally too, so the data layer isn't a cloud call either. Your whole dev stack sits on one host.
Same code, same runtime, deploys later
The local runtime is the same runtime the cloud runs. What you build offline isn't a mock — when you're back online, `a2a deploy` ships exactly what you developed. No rewrite, no 'now make it work in production' step.
Cloud-only dev tools vs. a fully local dev loop.
Frequently asked.
Can I develop AI agents offline or air-gapped?
Yes. `a2a dev --local` runs the whole agent on your machine — a Docker container by default, or a plain Python process with `--host-runtime`. It loads `.env.local` and your setup from `~/.a2a/credentials.json` on disk and mounts a local workspace, so the inner loop boots and runs with no connection. It's documented as the offline / air-gapped fallback. One honest caveat: LLM calls still go to whatever model endpoint you point at, so fully air-gapped means pointing the agent at a local model — the a2a dev loop itself is local either way.
Does `a2a dev --local` need the cloud to run?
No. The local runtime executes the agent on your machine and reads its config from local files, so starting and running the loop doesn't call the control plane. The managed-cloud features — provisioned Postgres, the MCP server, signed receipts — need connectivity, and we're upfront about that. But the develop-and-iterate loop is fully local.
What about the database and vector store when I'm offline?
`a2a chat` stands up local resources with Docker Compose — a local Postgres and a local Qdrant — on your machine. The agent's datastore and vector store run locally, so the data layer isn't a cloud dependency during offline development either. Your whole dev stack lives on one host.
Is the local agent the same as what deploys to the cloud?
Yes — same runtime, same code. What you build with `a2a dev --local` isn't a stub or a simulator; it's the runtime the cloud also runs. When you're back online, `a2a deploy` ships exactly what you developed offline, with no rewrite and no separate 'productionize' pass.
Docker or `--host-runtime` — which should I use offline?
Both run locally; pick by environment. Docker (the default) gives you an isolated container and matches the deployed shape closely. `--host-runtime` runs the agent as a direct Python process on the host — handy when a Docker daemon isn't available or you want the fastest inner loop. Neither needs a network to start; the choice is about isolation and your machine's setup, not connectivity.
Related guides.
All guides live in the guides index.
Trust the receipt.
`a2a dev --local` runs the entire agent on your machine — Docker or a plain Python process via `--host-runtime` — reading config from `.env.local` and `~/.a2a/credentials.json`, with hot reload, a `/_dev` console, and local Postgres and Qdrant through `a2a chat`. Build on a plane, behind a firewall, or air-gapped. The managed-cloud features — provisioned datastores, the MCP server, signed receipts — need connectivity, and we're honest about that. But the dev loop is fully local, and `a2a deploy` ships exactly what you built when you're back online.