DEV Community

Prabhakaran Jayaraman Masani
Prabhakaran Jayaraman Masani

Posted on

Letting AI Agents Run Code Safely: A Hands-On Look at Cloud Run Sandboxes and Sandbox Templates

The problem: agents want to execute code

Sooner or later, every useful AI agent wants to run code. It might be a data-analysis agent that writes a pandas script, a coding agent that runs tests, or a research agent that spins up a headless browser. The model generates the code, so from an architecture point of view that code is untrusted input.

The usual options are uncomfortable:

  • Run it in the agent's own container, and the generated code can read your environment variables, call the metadata server and act as your service account.
  • Spin up a new Cloud Run job or VM per task, and you pay in latency, plumbing and cost for every tool call.
  • Run a separate sandbox service, and you now own another piece of infrastructure, plus the networking and auth between the two.

Cloud Run sandboxes (currently in Preview) target exactly this gap. On 16 November 2026, Google added sandbox templates, which let you launch sandboxes as separate containers with their own images and dynamically mount in-memory volumes into them. In this article I walk through how the feature fits together, how I would wire it into an agent, and the security and cost trade-offs to think about before you enable it.

How Cloud Run sandboxes work

According to the documentation, sandboxes run inside the same Cloud Run instance as your main container (second-generation execution environment) and share its CPU and memory. You enable them per container with a sandboxLauncher flag, and your code then calls a CLI shipped at /usr/local/gcp/bin/sandbox.

The defaults are what make this interesting from a security point of view. By default, a sandbox:

  • has no outbound network access (you opt in with --allow-egress)
  • does not inherit the parent's environment variables, secrets or access to the Google Cloud metadata server
  • is isolated from every other sandbox
  • runs processes as a non-root user with sudo, so it can still pip install or apt install inside its own ephemeral filesystem

There are two modes:

  • Local sandboxes use the host container's root filesystem, mounted read-only, as their base. Simple, but your main image has to contain every tool the sandbox needs, and the sandbox can read whatever is on the host's disk.
  • Templated sandboxes (new) start from a separate image you declare, such as python:3.12-slim or a custom toolchain image. You can declare up to 10 templates. They still share the host instance's CPU and memory, and the docs note they launch without provisioning new VMs or billing for new instances.

Templates can mount an in-memory volume shared with the main container, and a subPath with a $(VARIABLE) placeholder means each sandbox only sees its own subdirectory.

Agent container launching isolated Cloud Run sandboxes that share an in-memory volume

The agent container keeps the identity, the secrets and the network access. The sandboxes get a scratch directory and nothing else unless you grant it.

Hands-on: a code-execution tool for an agent

Note: Cloud Run sandboxes are a Preview feature. The configuration below follows the official documentation as of 17 November 2026, but the Python tool wrapper is illustrative and has not been tested in production. Check the docs for changes before you use it.

1. Enable the sandbox launcher

For a quick start on an existing service, the docs use the beta gcloud command:

gcloud beta run services update my-agent --sandbox-launcher
Enter fullscreen mode Exit fullscreen mode

The Terraform google_cloud_run_v2_service resource exposes the same setting as sandbox_launcher = true on the container. Because sandboxes share the container's resources, size CPU and memory for your app plus the sandboxes you expect to run at the same time.

2. Declare a template and a shared in-memory volume

Templates are configured through the service YAML (or the Admin API). Export the current config, edit it, and replace it:

gcloud run services describe my-agent --format export > service.yaml
Enter fullscreen mode Exit fullscreen mode
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: my-agent
  annotations:
    run.googleapis.com/launch-stage: BETA
spec:
  template:
    spec:
      containers:
      - image: europe-west2-docker.pkg.dev/PROJECT_ID/agents/my-agent:latest
        ports:
        - containerPort: 8080
        sandboxLauncher: true
        volumeMounts:
        - name: work
          mountPath: /mnt/work
      volumes:
      - name: work
        emptyDir:
          medium: Memory
      sandboxes:
        templates:
        - name: python
          image: python:3.12-slim
          volumeMounts:
          - name: work
            mountPath: /work
            subPath: $(SANDBOX_DIR)
Enter fullscreen mode Exit fullscreen mode
gcloud run services replace service.yaml
Enter fullscreen mode Exit fullscreen mode

Two details from the docs that are easy to miss:

  • Template variable names can only contain ASCII letters and underscores, so SANDBOX_DIR works but SANDBOX_DIR_2 or sandbox-dir does not.
  • subPath does not create directories for you. The main container has to mkdir -p the subdirectory before launching the sandbox.

3. Wrap it as an agent tool

Here is an illustrative Python function you could register as a tool in an agent framework such as ADK. It gives each call its own directory and sandbox name, runs the generated code in the python template with no egress, and enforces a timeout.

# Illustrative only: verify flags against the current sandbox CLI reference.
import pathlib
import subprocess
import uuid

SANDBOX = "/usr/local/gcp/bin/sandbox"
WORK_ROOT = pathlib.Path("/mnt/work")


def run_python(code: str, timeout_s: int = 60) -> dict:
    """Execute model-generated Python in an isolated Cloud Run sandbox."""
    job_id = f"job{uuid.uuid4().hex[:12]}"   # matches ^[a-zA-Z0-9][a-zA-Z0-9-]*$
    job_dir = WORK_ROOT / job_id
    job_dir.mkdir(parents=True, exist_ok=True)  # subPath is not auto-created
    (job_dir / "main.py").write_text(code)

    cmd = [
        SANDBOX, "do",
        "--template=python",
        f"--template-var=SANDBOX_DIR={job_id}",
        f"--sandbox-name={job_id}",
        "--stdin=false",
        "--workdir=/work",
        "--", "/usr/local/bin/python3", "/work/main.py",
    ]
    try:
        result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout_s)
        return {"exit_code": result.returncode,
                "stdout": result.stdout[-10_000:],
                "stderr": result.stderr[-10_000:]}
    except subprocess.TimeoutExpired:
        # Naming the sandbox lets us force-delete it on timeout.
        subprocess.run([SANDBOX, "delete", "--force", job_id], check=False)
        return {"exit_code": -1, "stdout": "", "stderr": "timed out"}
Enter fullscreen mode Exit fullscreen mode

Note the absolute interpreter path: the official images put Python in /usr/local/bin, and the docs advise using absolute paths or setting PATH with --env. Also note what is not in the command: no --allow-egress, no --env with credentials, no bind mounts of host directories.

4. Keep state between steps (optional)

Multi-step agents often need the workspace to survive between tool calls. The CLI supports exporting the sandbox's writable overlay to a tar file and importing it on the next call:

sandbox do --write --sync-tar=/mnt/work/job123/state.tar \
  -- /usr/bin/bash -c "mkdir -p /workspace && echo step-done >> /workspace/log.txt"
Enter fullscreen mode Exit fullscreen mode

Files under /tmp inside the sandbox are not included in archives, so persist to another path such as /workspace. For long-lived sessions you can also sandbox run NAME --detach once and then sandbox exec NAME -- ... repeatedly, which the docs recommend for fast repeated commands.

Trade-offs, cost and security notes

Security

  • The defaults are good; the risk is relaxing them under deadline pressure. The documentation is explicit: don't relax isolation flags to work around permission or network errors when running untrusted code.
  • --allow-egress exposes everything the Cloud Run instance can reach, including internal VPC endpoints. If the agent truly needs the internet, consider a narrow egress path rather than turning it on globally.
  • Never pass API keys or tokens via --env, and append ,readonly to any mount you expose.
  • Don't run tar -xf on sandbox archives in the host container; archives can contain malicious symlinks. Inspect with tar -tf or re-import into another sandbox.
  • Do not share writable archives across users or tenants. In a multi-tenant agent, key directories, sandbox names and archives by tenant.
  • Sandbox lifecycle events land in Cloud Logging; pipe sandbox stdout and stderr to your container's streams if you want the output there too.

Cost and capacity

  • Sandboxes don't create new billable instances, but they consume the host instance's CPU and memory, and the in-memory volume counts against memory too. A burst of heavy sandbox jobs can starve the agent itself, so limit concurrency inside the agent and keep request concurrency on the service conservative.
  • You cannot set per-template CPU or memory limits, so a single runaway script can affect its neighbours on the same instance. Timeouts and output truncation (as in the example) matter.

When to use something else

  • Sandboxes are Preview, so weigh support expectations before relying on them for critical workloads.
  • For heavy, long-running or GPU tasks, a dedicated Cloud Run job is still the cleaner unit of isolation and billing.
  • Google has also announced Agent Compute Engine, a hardware-isolated microVM runtime for agents targeted for preview. That looks aimed at large-scale, high-churn agent fleets; Cloud Run sandboxes fit the much more common case of "my agent on Cloud Run needs a safe code interpreter today".

Conclusion

Cloud Run sandboxes turn "let the agent run code" from an infrastructure project into a configuration change plus a CLI call. Sandbox templates are the piece that makes it practical: your agent image stays lean, each tool runtime lives in its own image, and each execution gets its own private directory on a shared in-memory volume. Combined with secure defaults (no egress, no inherited secrets, no metadata server) this is a pattern I would reach for whenever an agent on Cloud Run needs a code interpreter, while keeping a close eye on resource sizing and never relaxing isolation just to make an error go away.

If you try it, start with the defaults, add one capability at a time, and log every sandbox invocation.

References

Top comments (0)