# Gemini Managed Agents Self-Hosted Sandboxes: Setup and Security Boundaries Self-hosted environments move tool execution onto your infrastructure, but the shell boundary and hosted-only API options need careful handling. By Paras Madan | 2026-11-12 Gemini Managed Agents can execute shell and file tools inside a sandbox you control. The connection uses outbound HTTPS, so you do not need to open an inbound firewall port. That makes it easier to reuse existing execution infrastructure, but it does not make an ordinary working directory a secure sandbox. The useful distinction is between choosing where an agent runs commands and owning the whole agent stack. Google's server-side agent still coordinates the interaction. Your worker receives tool calls, executes them and returns results. This is a way to bring your own execution environment, not a way to run Gemini inference locally. ## Connect an isolated worker, not your everyday terminal Start with a disposable container, microVM or VM that has only the files and permissions the task needs. Google's [self-hosted environment reference](https://github.com/google-gemini/gemini-api-cli/tree/main/docs/self-hosted) includes Docker and Podman recipes, plus examples for providers including Cloud Run, Vercel Sandbox, E2B and Modal. These are reference implementations, not a promise that Google operates or supports every deployment for you. The basic sequence has three parts. Create an environment through the Gemini API, connect a worker from inside your sandbox, then submit an interaction that names that environment. The following commands follow the documented interface; I have not run an end-to-end deployment for this guide. From a trusted control machine with your Gemini API key configured: ```bash curl -fsSL -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"}' ``` The response contains an environment `id` and an `environment_key`. Store the key securely when the response arrives because it is returned only once. Keep the ID exactly as returned, without adding an `environments/` prefix. Install the official `gemini-api` CLI inside your isolated worker using the relevant provider recipe. Inject the scoped environment key through your secret-management mechanism, then connect: ```bash gemini-api environments connect \ --environment-key "$GEMINI_ENVIRONMENT_KEY" \ --root-dir /workspace \ --workdir /workspace ``` Here `/workspace` must exist inside the isolated environment and contain the intended task files. Keep the worker running. From your application, pass the returned ID as the `environment` value when creating an interaction. The [provider setup guide](https://github.com/google-gemini/gemini-api-cli/tree/main/docs/self-hosted/providers) includes a CLI interaction example as well. Use a disposable text-file task for the first check. Confirm the output appeared in the intended sandbox, then inspect the worker logs and permissions before giving it a real repository. A completed interaction alone does not prove that your isolation policy is correct. ## Why root-dir does not contain arbitrary shell commands The runtime's structured file tools enforce a root-directory boundary. They block path traversal and symlinks that escape that root. The shell tool has a different security model: it executes model-generated commands through Bash, and its working directory is not an operating-system isolation boundary. **Setting `--root-dir` is not a substitute for a container or VM.** If you run the worker directly on your laptop with shell execution enabled, commands execute on that host. A prompt saying “stay in this directory” does not change the process's underlying privileges. For file-only work, the runtime supports `--disable-bash`. For workloads that genuinely need a shell, Google recommends an unprivileged runtime user, dropped Linux capabilities and controls at the container or VM layer. Apply outbound network restrictions there too, including blocking cloud metadata endpoints when they are not needed. This is where a bring-your-own sandbox can become more work than a managed one. You gain control over the execution boundary, but you also inherit responsibility for making that boundary real. ## Fix 400 INVALID_ARGUMENT without weakening the sandbox The [environment documentation](https://aistudio.google.com/docs/agent-environment#self-hosted-environments) says that hosted-sandbox options such as `sources`, `network`, `env` and `/files` snapshots apply only to Google's hosted environments. Self-hosted environments reject those options with `400 INVALID_ARGUMENT`. If a request copied from a hosted example fails, first remove the hosted-only configuration rather than changing authentication or opening network access. Prepare the source files, environment variables and network policy in your own infrastructure, then submit the interaction with the self-hosted environment ID. For example, a repository-processing task should start with the intended checkout already present in the worker's workspace. Its network policy should come from the sandbox provider or your container setup, not a hosted-environment `network` object. Moving the runtime without moving those setup responsibilities leaves a surprisingly incomplete migration. ## Keep the project API key outside the execution worker The single-worker connection accepts a scoped environment key, so the sandbox does not need your project-wide Gemini API key. That is a useful reduction in exposure, especially when the agent reads repositories or other material you do not fully trust. For self-managed fleets, the reference architecture also separates a trusted poller from ephemeral execution workers. The poller holds the credential and provisions work; each execution worker receives a short-lived interaction lease token rather than an API key. That is a stronger starting point for a multi-tenant service than copying the same long-lived credential into every container. Managed Agents and environments remain in preview. Treat interface stability, provider costs and operational support as things to assess before production deployment. The practical win is being able to choose an execution boundary that fits your application. If that boundary is just your personal shell with a different working directory, you have taken on the responsibility without getting the isolation. I'm Paras. I work at the intersection of AI, engineering and distribution. I help technical teams turn agent infrastructure, product updates and engineering decisions into clear stories developers can use. [Book a 30-minute call](https://cal.com/paras-madan/30min).