Self-hosted environment for Gemini Managed Agents
Google runs the agent. Its shell and files run on a VM of yours.
Shelley handles the setup. About 10 minutes.
Prefer a terminal?
curl -fsSL https://exe.dev/deploy/gemini-managed-agents/prompt.txt | ssh exe.dev new --prompt=/dev/stdinManaged Agents in the Gemini API
run Google's Antigravity agent on Google's servers. Since November 11, 2026,
an agent's tools can run in a
self-hosted environment
instead of Google's sandbox: a worker from the open-source
gemini-api CLI,
gemini-api environments connect, polls Google over outbound HTTPS, runs
each shell command and file edit where it is, and sends back the result.
This page makes that machine an exe.dev VM:
- Always on. The worker is a systemd service. The VM doesn't pause when it's idle, so there's no keep-awake loop to write, as there is on Fly Sprites and E2B.
- No key on the VM. The worker's only credential, the environment key, lives in an exe.dev HTTP proxy integration that adds it to requests on their way to Google. The agent shares the VM with the worker, so a key on disk or in the worker's environment would be the agent's to read.
- Files that stay. The agent works in
~/workspaceon the VM's disk. Look at what it did over SSH, or ask Shelley on the same VM. - No inbound ports. Nothing listens. A web app the agent starts on a port
from 3000 to 9999 is at
https://my-gemini-sandbox.exe.xyz:<port>/, behind your exe.dev login.
your computer Gemini API my-gemini-sandbox
gemini-api agent run ... ──▶ Antigravity agent, model ◀── gemini-worker polls through
environment: <id> queues tool calls https://gemini-env.int.exe.xyz
(GEMINI_API_KEY) (exe.dev adds the env key)
runs them in ~/workspace
What you get#
- The gemini-api CLI 0.4.6 in /usr/local/bin
- The gemini-worker service, restarted on failure and after a reboot, giving the agent ~/workspace
- No environment key on the VM; the worker reaches Google through
https://gemini-env.int.exe.xyz Worker ... pollinginjournalctl -u gemini-workeronce the owner has added the gemini-env integration
What's running, and where
https://my-gemini-sandbox.exe.xyz:8000/
anything the agent serves on a port from 3000 to 9999, behind your exe.dev login
environments connect, the gemini-worker systemd service
Deploy with Shelley#
Click Deploy and Shelley will set up Gemini Managed Agents on a new VM, then check that it works. No config-file wrangling required.
Prefer a terminal?
curl -fsSL \
https://exe.dev/deploy/gemini-managed-agents/prompt.txt \
| ssh exe.dev new --prompt=/dev/stdinWhen it's done, run this on your computer (only you can):
ssh exe.dev integrations add http-proxy --name gemini-env --target https://generativelanguage.googleapis.com --header "x-goog-environment-key:$(jq -r .environment_key gemini-env.json)" --attach vm:my-gemini-sandbox # in the folder with gemini-env.jsonWhat Shelley is told
Set up Gemini Managed Agents on this VM by following the exe.dev recipe at https://exe.dev/deploy/gemini-managed-agents.md?via=deploy from top to bottom.
The recipe's example VM name is my-gemini-sandbox. This VM's name is the output of `hostname`: use it wherever the recipe writes my-gemini-sandbox. Skip the step that creates the VM; you are on it.
You are done when all of these are true. Check each one yourself:
- The gemini-api CLI 0.4.6 in /usr/local/bin
- The gemini-worker service, restarted on failure and after a reboot, giving the agent ~/workspace
- No environment key on the VM; the worker reaches Google through `https://gemini-env.int.exe.xyz`
- `Worker ... polling` in `journalctl -u gemini-worker` once the owner has added the gemini-env integration
Run "Set up the worker by hand" from "On the VM", skipping VM creation
and SSH. Install exactly the pinned version. Don't ask for or handle any
key: the environment key goes into an exe.dev integration that only the
owner can add, from their computer. Until they do, the log shows
`integration not found or not attached to this VM`, which is expected;
tell the owner to run the `integrations add` command from "Connect the
worker" in the folder where they saved gemini-env.json, then check the
log for `polling`. Don't change the VM's egress policy. Finish by pointing
the owner to "Give it a task".
Finish with the URLs I should open and these commands, which only I can run, from my own computer (with this VM's name in them):
ssh exe.dev integrations add http-proxy --name gemini-env --target https://generativelanguage.googleapis.com --header "x-goog-environment-key:$(jq -r .environment_key gemini-env.json)" --attach vm:my-gemini-sandbox # in the folder with gemini-env.json
Also at /deploy/gemini-managed-agents/prompt.txt. The recipe it follows is /deploy/gemini-managed-agents.md.
Before you start#
You need a Gemini API key and jq on your computer. Create the self-hosted environment there, so your API key never reaches the VM. On your computer:
export GEMINI_API_KEY=...
(umask 077; curl -fsS -X POST \
https://generativelanguage.googleapis.com/v1beta/environments \
-H "x-goog-api-key: $GEMINI_API_KEY" -H "Content-Type: application/json" \
-d '{"mode": "self_hosted"}' > gemini-env.json)
jq -r .id gemini-env.json
That prints the environment's ID, a bare UUID. gemini-env.json also holds
its environment_key, which Google returns only this once, so keep the file
until the key is stored with exe.dev below.
Set up the worker#
Deploy sets it up on a new VM. To do it yourself:
Set up the worker by hand
On your computer (pick any free name; VM names are global):
ssh exe.dev new --name=my-gemini-sandbox
ssh my-gemini-sandbox.exe.xyz
On the VM, install the CLI, pinned to a release, as Google recommends for unattended use:
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh |
sudo GEMINI_VERSION=v0.4.6 bash
gemini-api --version
Expect gemini-api 0.4.6. Then write the worker's settings. The key is a
placeholder: exe.dev replaces it on the way to Google.
sudo install -m 600 /dev/null /etc/gemini-worker.env
sudo tee /etc/gemini-worker.env > /dev/null <<'EOF'
GEMINI_SERVER_URL=https://gemini-env.int.exe.xyz
GEMINI_ENVIRONMENT_KEY=held-by-exe-dev
EOF
Run it as a service, with ~/workspace as the agent's directory:
mkdir -p ~/workspace
sudo tee /etc/systemd/system/gemini-worker.service > /dev/null <<'EOF'
[Unit]
Description=Gemini Managed Agents self-hosted environment worker
Wants=network-online.target
After=network-online.target
[Service]
User=exedev
WorkingDirectory=/home/exedev/workspace
EnvironmentFile=/etc/gemini-worker.env
ExecStart=/usr/local/bin/gemini-api environments connect --server-url ${GEMINI_SERVER_URL} --root-dir /home/exedev/workspace --workdir /home/exedev/workspace
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now gemini-worker
Until the integration below exists,
journalctl -u gemini-worker -n 5 --no-pager shows
integration not found or not attached to this VM, and the service retries
every 10 seconds.
Connect the worker#
Give exe.dev the environment key, as an integration that only this VM can
use. On your computer, in the folder with gemini-env.json:
ssh exe.dev integrations add http-proxy --name gemini-env \
--target https://generativelanguage.googleapis.com \
--header "x-goog-environment-key:$(jq -r .environment_key gemini-env.json)" \
--attach vm:my-gemini-sandbox
Within 10 seconds the worker connects. On the VM:
journalctl -u gemini-worker -n 5 --no-pager
Expect Worker worker-my-gemini-sandbox-... polling (maxConcurrent=4). Now
the key is with exe.dev, which shows it only as ***: delete
gemini-env.json, or move it to your password manager.
Optional: let the VM reach nothing else#
The worker needs only the integration, so you can close off the rest of the internet. On your computer:
ssh exe.dev egress my-gemini-sandbox integrations
The agent can then reach Google only as the worker, plus your other attached
integrations (such as exe.dev's LLM integration),
so it can't send your files anywhere else. It also can't install packages or
clone repositories: install what it needs first, or switch back for a while
with ssh exe.dev egress my-gemini-sandbox all. See
Egress policy.
Give it a task#
Send an interaction that names the environment. With the gemini-api CLI on
your computer (the curl ... install.sh | bash line above, without sudo)
and GEMINI_API_KEY set:
gemini-api agent run \
"Write the output of hostname to hello.txt, then run uname -a in bash." \
--agent antigravity-preview-09-2026 \
--body "{\"environment\": \"$(jq -r .id gemini-env.json)\",
\"agent_config\": {\"type\": \"antigravity\", \"model\": \"gemini-3.5-flash-lite\"}}"
(If you've deleted gemini-env.json, put the ID in by hand.) The
agent_config picks a small, quick model for the test; leave it out to use
the agent's default, or name another
model.
The reply
streams in as the agent works; uname -a reports my-gemini-sandbox. The
worker logs Claimed interaction lease and an Executing function line for each tool call. Then:
ssh my-gemini-sandbox.exe.xyz cat workspace/hello.txt
prints my-gemini-sandbox. Pass --previous-interaction-id <id> to
continue the same conversation; the files are still there.
Note
The worker runs up to four interactions at once, all in
~/workspace. Give agents that must not see each other's files their own environments and VMs.
Look at the workspace#
Everything the agent made is on the VM's disk, and stays there between interactions and across reboots:
ssh my-gemini-sandbox.exe.xyzand look around~/workspace.- Open Shelley at
https://my-gemini-sandbox.shelley.exe.xyz/and ask it what changed, or to tidy up or finish the job. - Copy it out:
ssh my-gemini-sandbox.exe.xyz tar -C workspace -czf - . > workspace.tgz.
To start the agent fresh, empty ~/workspace. To set a VM aside before an
experiment, copy it: ssh exe.dev cp my-gemini-sandbox.
Keep the key off the VM, or not#
The integration is the safe way. If you'd rather not use it, put the key in the settings file instead, on the VM:
sudo tee /etc/gemini-worker.env > /dev/null <<'EOF'
GEMINI_SERVER_URL=https://generativelanguage.googleapis.com
GEMINI_ENVIRONMENT_KEY=<environment_key from gemini-env.json>
EOF
sudo systemctl restart gemini-worker
The file is root's, mode 600, and the worker clears credential variables
from the agent's shell. But the agent runs as the same user as the worker,
so it can read the key if it tries: from the worker's
/proc/<pid>/environ, or from the file with sudo. The key is good for this one
environment only: anyone holding it could run your agent's tool calls, and
see them. If it leaks, delete the environment and make a new one.
Update the CLI
The gemini-api CLI is a beta, and minor versions can break things. Check the releases, then run the install line with the new tag and restart, on the VM:
curl -fsSL https://raw.githubusercontent.com/google-gemini/gemini-api-cli/main/scripts/install.sh |
sudo GEMINI_VERSION=v0.4.6 bash
sudo systemctl restart gemini-worker
With egress set to integrations, set it to all first, and back after.
Clean up
On your computer, delete the environment at Google, then the integration and
the VM (copy out ~/workspace first if you want it):
gemini-api environments delete <id>
ssh exe.dev integrations remove gemini-env
ssh exe.dev rm my-gemini-sandbox
Troubleshooting
The worker's log is journalctl -u gemini-worker -f on the VM.
integration not found or not attached to this VM: the gemini-env integration doesn't exist yet, or is attached to another VM. Runssh exe.dev integrations attach gemini-env vm:my-gemini-sandbox.The caller does not have permission(HTTP 403): Google refused the environment key. Check it againstgemini-env.json, and fix it withssh exe.dev integrations edit gemini-env --header "x-goog-environment-key:<key>".lookup generativelanguage.googleapis.com ... server misbehaving: the VM's egress isintegrationsbutGEMINI_SERVER_URLpoints straight at Google. Use the integration, or set egress back toall.- Interactions wait and then time out: the worker isn't running
(
systemctl status gemini-worker) or is connected to another environment.agent runmust name the same environment ID. - The interaction ends after a few minutes with no reply and no tool calls in
the worker's log: the agent's model is likely overloaded (a plain call to
it returns
503 ... high demand). Pick another model for the agent with--body '{"environment": "<id>", "agent_config": {"type": "antigravity", "model": "gemini-3.5-flash-lite"}}'. 400 INVALID_ARGUMENTwhen you send an interaction: self-hosted environments reject the hosted-only options (sources,network,env, and/filessnapshots). Put files in~/workspaceover SSH instead.
Frequently asked questions#
What runs where?
Google runs the model, the agent loop, and the conversation. The VM runs the agent's tools (execute_bash, and file tools that read, write, edit, list, and search) as exedev in ~/workspace. Prompts, tool calls, and their output still pass through Google's API, so this keeps the files and commands on your machine, not the conversation.
Can the agent get out of ~/workspace?
The file tools can't: the worker confines them to --root-dir. Shell commands can, and run as exedev, which has sudo. The VM is the boundary, so give each environment a VM of its own and keep anything you care about off it.
Where is the environment key?
In the gemini-env HTTP proxy integration, stored by exe.dev and added to requests on their way to Google. The VM has a placeholder. Anything on the VM can still use the integration while it's attached, so the agent can't leak the key, but it could talk to Google as the worker would. Detach it to cut it off.
Does it need a keep-alive, like Sprites or E2B?
No. An exe.dev VM doesn't pause when it's idle, so the worker polls all day and picks up an interaction the moment you send it. There's nothing to wake up and no inbound port.
What does it cost?
Google bills the agent's model tokens to your Gemini API project (free tier projects get a rate-limited quota). The VM is part of your exe.dev plan, with no per-minute charge while the worker waits.
Can I use Gemini through exe.dev's LLM integration instead of a key?
Not for this. The LLM integration serves Anthropic, OpenAI, and Fireworks models, and a managed agent's model runs at Google anyway. The VM needs only the environment key; your Gemini API key stays on your computer.
Can several environments share one VM?
They could, but don't: every agent would see the others' files and processes. Make one VM, one environment, and one integration (with its own --name) per agent or customer.
Updated Nov 17, 2026 · tested end to end Nov 17, 2026 · Markdown · manifest.json · Something wrong? Tell us