How VM Bridge works
On this page
Overview
VM Bridge runs T3 Code agents on cloud VMs. You pair an unchanged T3 Code app with VM Bridge once. After that, VM Bridge creates, wakes and sleeps VMs on your sandbox provider, and sends each project and thread to the right one.
- One project per VM. Projects never share a disk, a process list or a shell.
- A VM sleeps after it has been idle for a set time, and wakes when you send a message.
- Several providers at once: boxd, Instabox, Daytona, Boat and Railway. Pick one per repository, or let new VMs use the default.
- Everything is set up from a web dashboard behind one password: provider keys, GitHub, agent sign-ins and device pairing.
- T3 Code needs no changes. To the app, VM Bridge looks like a single T3 server.
Install
VM Bridge runs on macOS and Linux. You need an account with one of the supported providers, and T3 Code on the devices you want to pair. One command installs the server, the dashboard and the command line, as one file in ~/.local/bin:
curl -fsSL https://raw.githubusercontent.com/vkpdeveloper/vmbridge/main/install.sh | sh
Then run vmbridge. It asks for a dashboard password on first run. Run the same command again to update.
To build from source instead, with Bun 1.4.4 or newer:
git clone https://github.com/vkpdeveloper/vmbridge cd vmbridge bun install bun run build # dist/vmbridge ./dist/vmbridge
Run
| Command | What it does |
|---|---|
vmbridge [run] [--host 0.0.0.0] [--port 3774] | Start in this terminal |
vmbridge stop | Stop, including the background service |
vmbridge service install [--host] [--port] | Run in the background at login (launchd or systemd) |
vmbridge service uninstall | Remove the background service |
vmbridge key | Set a new dashboard key |
On first start, VM Bridge asks for a dashboard password of at least 8 characters. On a machine with no terminal, set VMBRIDGE_PASSWORD for the first start instead.
Data lives in ~/.vmbridge. Set VMBRIDGE_HOME to move it. The background service uses launchd on macOS and systemd on Linux, and writes its log to ~/.vmbridge/vmbridge.log.
vmbridge service install --port 3774Set up the dashboard
Open /dashboard on any address VM Bridge printed and log in with your password. Setup has three tabs.
- Providers. Add one or more providers and paste their keys. VM Bridge checks each key before saving it. The first one you add is the default.
- GitHub. A personal access token so agents can clone, push and open pull requests.
- Agent sign-in. Sign in to Codex with ChatGPT and to Claude with your Claude account, or add a token or an OpenCode key.
Under Settings you choose the VM size, how many idle minutes before a VM sleeps (5 by default), and the T3 version to install on VMs. Under Repositories you can send a repository to a given provider and VM size.
Pair T3 Code
Under Devices, name the device and create a pairing link. In T3 Code, add a remote environment and paste the link.
- Each link works once and expires after 15 minutes.
- Pairing swaps the link for a token that only that device holds. VM Bridge stores a hash of it.
- Remove a device under Devices to sign it out right away.
How a request flows
T3 Code keeps one connection to VM Bridge. VM Bridge keeps one connection to the T3 server on each awake VM, and routes each request by its project or thread.
VM Bridge creates a VM for it, installs T3, Codex and Claude, and clones the repository.
- Answered by the bridge. Config, the project list and threads on sleeping VMs come from VM Bridge in about 1 ms.
- Forwarded to a VM. Messages, file browsing and Git status go to the project's VM, about 150 to 230 ms away depending on the provider.
- New projects. Opening a repository creates a VM, installs Node, T3 and the agent CLIs, starts T3 and clones the repository. A fresh VM is ready in 16 to 24 seconds, or about a minute on Railway.
Sleep and wake
A VM counts as idle when no device has used it and nothing is waiting on it: no running agent turn, queued work, pending approval or enabled automation. After the idle minutes you set, VM Bridge saves each thread on that VM and puts it to sleep. The threads stay readable in T3 Code while it sleeps.
Send a message in a sleeping thread and T3 Code shows Waking the boxd VM... until the VM answers. Then the message goes through as usual.
| Provider | Sleep | Wake | Measured wake |
|---|---|---|---|
| boxd | Pause, memory kept | Resume | 6 to 11 s |
| Instabox | Pause, memory kept | Resume | 8 s |
| Daytona | Stop, files kept | Start | 10 to 11 s |
| Boat | Stop, disk kept | Resume | Not measured yet |
| Railway | Checkpoint, then remove | New VM from the checkpoint | 45 s |
Each provider also has its own idle limit as a safety net in case VM Bridge is offline. Railway has none, so VM Bridge never sets one there.
Providers

- boxd wakes a paused VM on any traffic, so VM Bridge closes its connection before it pauses one.
- Daytona uses container sandboxes, which stop rather than pause. Files stay, and T3 starts fresh on wake.
- Boat VMs start in the Boat environment you choose.
- Railway has no pause. Sleep saves a checkpoint and removes the VM. Wake creates a new VM from it. Railway needs an account or workspace API token and an environment ID.
- Instabox uses the agent-browser template.
Agent sign-ins and GitHub
Agents and git sign in only with what you add in Setup, never with sign-ins from the VM provider. Each agent sign-in is a profile saved under ~/.vmbridge/auths, readable only by you. Each agent uses one profile at a time, and VMs get it when they start.
| Sign-in | Set on the VM as |
|---|---|
| Codex, signed in with ChatGPT | auth.json in a private CODEX_HOME |
| Claude account | CLAUDE_CODE_OAUTH_TOKEN |
| Claude auth token | ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL |
| OpenCode API key | OPENCODE_API_KEY |
| GitHub token | GH_TOKEN, GITHUB_TOKEN |
Git on each VM signs in to GitHub with the token and commits as your GitHub account, using GitHub's private noreply email. SSH remotes such as git@github.com:you/app.git go over HTTPS with the token. The GitHub CLI, gh, is installed and signed in, so agents can open pull requests.
VM Bridge refreshes the Codex sign-in before it expires and gives the new tokens to every awake VM, so VMs never sign each other out.
Signing in with your Claude account makes the same one-year token as claude setup-token. Approve on claude.ai, then paste the code it shows into the dashboard.
Addresses and Tailscale
VM Bridge listens on 0.0.0.0 by default, so phones and laptops on your network can reach it. Pass --host 127.0.0.1 to keep it on this machine.
| Address | Example |
|---|---|
| This machine | http://127.0.0.1:3774 |
| Local network | http://192.168.1.20:3774 |
| Tailscale IP | http://100.101.102.103:3774 |
| Tailscale name | http://mac-mini.tail.ts.net:3774 |
| Tailscale HTTPS | https://mac-mini.tail.ts.net |
Turn on Tailscale HTTPS under Settings to reach VM Bridge from anywhere on your tailnet with a certificate.
Data and security
- Everything is in
~/.vmbridge/main.db, readable only by your user. - The dashboard API never returns a saved secret. You can replace a key, not read it back.
- Logs record which call went where and how long it took. They never hold message contents or tokens.
- Each T3 server on a VM requires its own session token on every request, and only VM Bridge holds it. Public preview URLs show nothing without it.
- Requests to VMs refuse redirects, so a token can never be sent to another site.
Troubleshooting
| What you see | What to do |
|---|---|
| An agent shows as signed out on a VM | Add its sign-in under Setup, or in your provider's dashboard if it supplies them. |
| The pairing link does not work | Links work once and expire after 15 minutes. Create a new one. |
| The T3 server on a VM did not answer | The VM may be busy or the provider slow. Check the VM on the dashboard canvas, then retry. |
| Waking takes longer than usual | Stopped VMs (Daytona, Boat) start T3 cold, which adds a few seconds over a paused VM. |
| You forgot the dashboard password | Run vmbridge password on the machine to set a new one. |
Develop
bun run dev # server and dashboard, restarted on change bun run check # typecheck and tests
apps/server: the T3 gateway, the fleet of VMs, providers and the dashboard API.apps/web: the dashboard.apps/cli: thevmbridgecommand.apps/landing: this site.packages/contracts: types shared by the server and the dashboard.