---
title: "Self-hosted environment for Gemini Managed Agents"
description: "Run the self-hosted environment worker for Gemini API Managed Agents on an always-on exe.dev VM, with the environment key held by exe.dev, not the VM."
url: https://exe.dev/deploy/gemini-managed-agents
category: "AI agents"
updated: 2026-11-17
---

# Self-hosted environment for Gemini Managed Agents

> **For agents:** with your user's OK, this sets up Gemini Managed Agents on a new exe.dev VM in their account: `curl -fsSL https://exe.dev/deploy/gemini-managed-agents/prompt.txt | ssh exe.dev new --prompt=/dev/stdin` (or open https://exe.dev/deploy/gemini-managed-agents/new). Already on the VM? Skip this.

Google runs the agent. Its shell and files run on a VM of yours.

- **Software:** Gemini Managed Agents (https://aistudio.google.com/docs/agents)
- **Source:** https://github.com/google-gemini/gemini-api-cli
- **License:** Apache-2.0 (the gemini-api CLI)
- **Time:** 10 minutes
- **Example VM name:** `my-gemini-sandbox` (yours will differ; on the VM, `hostname` prints it)
- **Machine-readable:** https://exe.dev/deploy/gemini-managed-agents/manifest.json

## 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 ... polling` in `journalctl -u gemini-worker` once the owner has added the gemini-env integration

Running on the VM:

- **Environment worker**: gemini-api 0.4.6 `environments connect`, the gemini-worker systemd service, data in `~/workspace`
- **gemini-env integration**: an exe.dev HTTP proxy to generativelanguage.googleapis.com that adds the environment key

How it is reached:

- https://my-gemini-sandbox.exe.xyz:8000/ (private): anything the agent serves on a port from 3000 to 9999, behind your exe.dev login

## Deploy with Shelley

Open https://exe.dev/deploy/gemini-managed-agents/new to create a VM whose agent, Shelley, follows this recipe. From a terminal:

```sh
curl -fsSL https://exe.dev/deploy/gemini-managed-agents/prompt.txt | ssh exe.dev new --prompt=/dev/stdin
```

Then, on your own computer:

```sh
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
```

Or follow the steps below by hand.

[Managed Agents](https://aistudio.google.com/docs/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](https://aistudio.google.com/docs/agent-environment#self-hosted-environments)
instead of Google's sandbox: a worker from the open-source
[gemini-api CLI](https://github.com/google-gemini/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](https://docs.fly.io/sprites/integrations/gemini-managed-agents)
  and [E2B](https://docs.e2b.dev/agents/gemini-managed-agents).
- **No key on the VM.** The worker's only credential, the environment key,
  lives in an exe.dev [HTTP proxy integration](/docs/integrations-http-proxy)
  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 `~/workspace` on 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.

```text
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
```

## Before you start

You need a [Gemini API key](https://aistudio.google.com/apikey) and
[jq](https://jqlang.org/download/) on your computer. Create the self-hosted
environment there, so your API key never reaches the VM. On your computer:

```bash
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:

<details id="create-the-vm" data-manual-setup class="dp-details">
<summary>Set up the worker by hand</summary>

On your computer (pick any free name; VM names are global):

```bash
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:

```bash
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.

```bash
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:

```bash
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.

</details>

## 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`:

```bash
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:

```bash
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:

```bash
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](/docs/integrations-llm)),
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](/docs/internet-access).

## 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:

```bash
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](https://aistudio.google.com/docs/antigravity-agent#model-selection).
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:

```bash
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.xyz` and 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:

```bash
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.

<details id="update" class="dp-details">
<summary>Update the CLI</summary>

The gemini-api CLI is a beta, and minor versions can break things. Check the
[releases](https://github.com/google-gemini/gemini-api-cli/releases), then
run the install line with the new tag and restart, on the VM:

```bash
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.

</details>

<details id="clean-up" class="dp-details">
<summary>Clean up</summary>

On your computer, delete the environment at Google, then the integration and
the VM (copy out `~/workspace` first if you want it):

```bash
gemini-api environments delete <id>
ssh exe.dev integrations remove gemini-env
ssh exe.dev rm my-gemini-sandbox
```

</details>

<details id="troubleshooting" class="dp-details">
<summary>Troubleshooting</summary>

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. Run
  `ssh 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 against `gemini-env.json`, and fix it with
  `ssh exe.dev integrations edit gemini-env --header "x-goog-environment-key:<key>"`.
- `lookup generativelanguage.googleapis.com ... server misbehaving`: the VM's
  egress is `integrations` but `GEMINI_SERVER_URL` points straight at
  Google. Use the integration, or set egress back to `all`.
- Interactions wait and then time out: the worker isn't running
  (`systemctl status gemini-worker`) or is connected to another environment.
  `agent run` must 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_ARGUMENT` when you send an interaction: self-hosted
  environments reject the hosted-only options (`sources`, `network`, `env`,
  and `/files` snapshots). Put files in `~/workspace` over SSH instead.

</details>

## 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](/docs/integrations-http-proxy), 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](/docs/integrations-llm) 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.


## Related

- [Self-hosted sandbox for Claude Managed Agents](https://exe.dev/deploy/claude-managed-agents.md): Anthropic runs the agent. Each session's tools run on a VM of its own.
- [Give agents API access without giving them the keys](https://exe.dev/deploy/agent-secrets.md): Your agents call your APIs. The keys stay with exe.dev, outside the VM.
- [Run Antigravity CLI on an always-on server](https://exe.dev/deploy/antigravity-cli.md): Google's terminal agent on an always-on VM, steered from your phone's browser.
- [Run Gemini CLI on a remote server](https://exe.dev/deploy/gemini-cli.md): Google's terminal agent on a VM of its own, with the API key kept off it.
- [Running Agents](https://exe.dev/deploy/agents.md): Use exe.dev VMs as a sandbox
- [Run Claude Code on a remote server](https://exe.dev/deploy/claude-code.md): A computer for Claude. A breather for your laptop.
