Many agent tasks involve executing untrusted code, running commands, using a web
browser, or interacting with external environments in ways that could pose
security risks. The Gemini Enterprise Agent Platform provides isolated **sandboxes** to handle
these workloads securely.

Sandboxes provide secure, isolated execution environments that are spawned to
perform specific tasks on behalf of an agent. By running these operations in a
sandbox, you can protect your infrastructure and data from potentially malicious
or erroneous actions performed by the agent. Sandboxes mitigate these risks by:

- **Isolation**: Each sandbox is isolated from other sandboxes and the host system. Actions taken by one agent in a sandbox doesn't affect other agents or users sharing the same runtime resources.
- **Security**: Operations within the sandbox are restricted, preventing unauthorized access to your resources. All sandbox environments use secure container sandboxing, providing a strong security boundary. Malicious code can't access sensitive data or credentials within the runtime.
- **Safety**: If an agent executes a harmful command or infinite loop, the impact is contained within the sandbox. For example, poorly written or malicious code could consume all available CPU or memory.

## Sandbox compared to runtime

The agent runtime and a sandbox differ in their purpose and usage:

- **Agent Runtime**: This is the environment where the agent's core logic, decision-making, and orchestration run. It is a trusted environment that executes your code and manages the agent's lifecycle.
- **Sandbox** : This is an auxiliary environment spawned *by* the agent or the platform to execute specific, potentially unsafe tasks. Sandboxes can be short-lived, session-based, or stateful for several days.

For example, if an agent needs to calculate a complex formula by generating and
running a custom Python script, it should run that script in a code execution
sandbox, not in its own runtime. Additionally, if the agent uses a skill and a
shell script, it must run them in an environment provisioned specifically for
that session, using the end user's access.

## TTL and Sandbox provisioning speeds

Sandbox environments have the following time-to-live (TTL) and provisioning characteristics:

- **TTL**: Sandbox TTLs vary, ranging from 7 days for a custom container image to 14 days for a code execution sandbox. This allows you to resume state on a sandbox environment several days later for long-horizon tasks and resumable shell environments.
- **Provisioning** : Creating a new sandbox takes up to 2 minutes to provision resources from a cold start, but after they are provisioned, sandboxes usually spin up in seconds. You can view the underlying architecture in the following open source projects: [AX](https://agentexecutor.io/) and [Substrate](https://github.com/agent-substrate/substrate).

## Features

Sandboxes offer several features such as predefined sandboxes,
custom containers, enterprise security controls, and lifecycle management:

- **[Code execution](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/sandbox/code-execution-overview.md.txt)**: Allows the agent to generate and run code in a secure environment. This is useful for complex mathematical calculations, data analysis, and other tasks that require computation.
- **[Computer use](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/sandbox/computer-use.md.txt)**: Enables the agent to interact with a web browser to perform tasks such as filling out forms, searching the web, or navigating complex UI workflows.
- **[Custom containers](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/sandbox/custom-containers.md.txt)**: You can "Bring Your Own Container" to customize the execution environment with specific libraries, tools, or configurations. Use this to give your agent a shell environment containing the commands and tools in your custom image.
- **[VPC Service Controls](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/sandbox/configure-vpc-sc.md.txt)**: Configure security perimeters to protect sensitive data and prevent unauthorized egress from sandbox environments.
- **[Customer-managed encryption keys (CMEK)](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/sandbox/configure-cmek.md.txt)**: Protect sandbox data at rest with encryption keys managed in Cloud Key Management Service (Cloud KMS).

## Security, identity, and observability boundaries

When you design agents that execute untrusted code or commands in a sandbox,
account for how Agent Platform separates execution identity, network
egress filtering, and audit logging between Agent Runtime and the sandbox
container.

### Execution identity and credential boundaries

Code executed inside a sandbox runs in a Google-managed tenant project inside a
gVisor-isolated container and doesn't inherit the identity or credentials of
your parent agent. The following table summarizes the identities involved in
sandbox operations:

| Identity layer | Principal | Scope and permissions |
|---|---|---|
| **Parent agent runtime identity** | [Agent Identity](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/runtime/agent-identity.md.txt) (`principal://agents.global.org-ORG_ID.system.id.goog/...`) or the custom or default service account attached to the `ReasoningEngine` instance | Used by orchestration code running in Agent Runtime to call Google Cloud APIs and manage or invoke sandboxes. Never mounted inside the sandbox container. |
| **Sandbox service agent** | `service-PROJECT_NUMBER@gcp-sa-vertex-sandbox.iam.gserviceaccount.com` | Google-managed per-project service agent used by the sandbox control plane for infrastructure tasks, such as pulling custom container images from Artifact Registry or using CMEK keys. Never accessible to code running inside the sandbox. |
| **In-sandbox execution environment** | Unprivileged container user (such as `appuser` in shell sandboxes) backed by an unprivileged tenant identity (`sandbox-untrusted`) with no Identity and Access Management (IAM) roles on your project | Runs untrusted code inside the sandbox pod. Has no ambient Google Cloud credentials and no permissions on your project or parent `ReasoningEngine`. |

Keep the following credential and authentication boundaries in mind when
running code inside a sandbox:

- **No ambient credentials or metadata server token access** : Sandboxed code doesn't have Application Default Credentials (ADC) for your project and can't query the Compute Engine metadata server (`169.254.169.254:80`) to mint OAuth 2.0 access tokens, read service account keys, or inspect host project metadata.
- **Inbound caller authentication** : Your agent or client authenticates *to* the sandbox control plane and data plane using IAM (`aiplatform.sandboxEnvironments.execute` permission, included in roles such as `roles/aiplatform.user`) or a short-lived access token generated by `generate_access_token` or `generate_browser_ws_headers`.
- **Authenticating outbound calls from inside a sandbox**: Because the sandbox has no ambient identity, any external API call made directly from inside the sandbox must use credentials that you explicitly provide. Prefer performing authenticated Google Cloud API operations in the parent agent on Agent Runtime and passing only the required input data into the sandbox. If code inside the sandbox must call an external service directly, inject short-lived, narrowly scoped tokens for that specific execution rather than passing long-lived service account keys.

### Network egress and domain allowlisting

Sandboxes don't provide a built-in domain allowlist property on the sandbox or
`SandboxEnvironmentTemplate` resource. Outbound network behavior depends on the
sandbox type and the `egress_control_config` settings on the template:

- **[Code execution](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/sandbox/code-execution-overview.md.txt) sandboxes**: Run without outbound internet or Virtual Private Cloud (VPC) network access.
- **Template-backed sandboxes ([Computer use](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/sandbox/computer-use.md.txt), [Shell sandbox](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/sandbox/shell-sandbox-quickstart.md.txt), and [Custom containers](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/sandbox/custom-containers.md.txt))** : Disable outbound internet access by default (`internet_access` is `False`).
- **Direct internet egress (`internet_access: True` without `network_attachment`)** : Grants the sandbox unrestricted outbound access to public IP addresses (`0.0.0.0/0`), while network policies block access to private RFC 1918 address ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) and the link-local metadata range (`169.254.0.0/16`). You can't specify a list of allowed or denied domains directly in `egress_control_config`.
- **Domain allowlisting and egress filtering with VPC controls** : To restrict a sandbox to specific domains (FQDNs), URLs, or IP ranges, configure `egress_control_config.network_attachment` on the template to bridge all sandbox egress into your VPC over a [Private Service Connect (Private Service Connect) interface](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/sandbox/configure-vpc-sc.md.txt#control-egress). Once traffic enters your VPC, enforce domain allowlists and outbound policies using:
  - **Cloud Next Generation Firewall (Cloud NGFW)** : Create global network firewall policy egress rules that allow specific destination FQDNs or IP ranges and deny all other outbound traffic (`0.0.0.0/0`).
  - **Secure Web Proxy (Secure Web Proxy)**: Route egress from the Private Service Connect subnet through Secure Web Proxy for Layer 7 TLS inspection and URL-level allowlisting.
  - **Cloud DNS peering** : Configure `dns_peering_configs` and private Cloud DNS zones so the sandbox resolves only approved names through your VPC rather than public DNS resolvers.

For step-by-step configuration instructions, see [Configure VPC Service Controls and Private Service Connect with sandboxes](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/sandbox/configure-vpc-sc.md.txt#control-egress).

### Audit logging and threat detection

Observability and security monitoring for sandboxes span the Agent Platform API
control and data planes, the parent agent on Agent Runtime, and your
VPC network.

#### Cloud Audit Logs coverage

Agent Platform writes [Cloud Audit Logs](https://docs.cloud.google.com/gemini-enterprise-agent-platform/machine-learning/general/audit-logging.md.txt)
entries under the `aiplatform.googleapis.com` service name and the
`audited_resource` monitored resource type for API calls made to sandbox
resources, but doesn't generate audit log entries for internal processes
spawned inside a container. The following table summarizes what is logged at
each boundary:

| Activity type | API methods or operations | Log category | Notes |
|---|---|---|---|
| **Sandbox and template lifecycle mutations** | `CreateSandboxEnvironment`, `DeleteSandboxEnvironment`, `SnapshotSandboxEnvironment`, `PauseSandboxEnvironment`, `ResumeSandboxEnvironment`, `CreateSandboxEnvironmentTemplate`, `UpdateSandboxEnvironmentTemplate`, `DeleteSandboxEnvironmentTemplate`, `DeleteSandboxEnvironmentSnapshot` | Admin Activity (`ADMIN_WRITE`) | Always enabled by default. Records the caller identity, resource name, and operation metadata. |
| **Sandbox and template metadata reads** | `GetSandboxEnvironment`, `ListSandboxEnvironments`, `GetSandboxEnvironmentTemplate`, `ListSandboxEnvironmentTemplates`, `GetSandboxEnvironmentSnapshot`, `ListSandboxEnvironmentSnapshots` | Data Access (`ADMIN_READ`) | Disabled by default. Enable `ADMIN_READ` logs for `aiplatform.googleapis.com` to audit who inspects or lists sandboxes. |
| **Data-plane command execution and access authorization** | `ExecuteSandboxEnvironment`, `BidiExecuteSandboxEnvironment`, `AuthorizeSandboxEnvironmentAccess`, `ExecuteCode` | Data Access (`DATA_WRITE`) | Disabled by default. Enable `DATA_WRITE` logs for `aiplatform.googleapis.com` to audit execution RPCs and token generation. For resources inside a VPC Service Controls perimeter, request and response payloads are omitted from audit logs. |
| **In-container child processes, file writes, and interactive stream frames** | Subprocesses spawned by a shell command, file system modifications, and individual frames sent over an open WebSocket, Chrome DevTools Protocol (CDP), or PTY session | Not logged in Cloud Audit Logs | Cloud Audit Logs records the initial API call (`ExecuteSandboxEnvironment`, `BidiExecuteSandboxEnvironment`, or `AuthorizeSandboxEnvironmentAccess`), not subsequent in-guest system calls or stream frames. |
| **Container `stdout` and `stderr` output** | Standard output and error streams from commands run inside the sandbox | Returned in the execution API response | Automatic Cloud Logging collection (such as `reasoning_engine_stdout`) applies only to the parent `ReasoningEngine` runtime and doesn't collect logs from sandbox child resources. Log command outputs from your parent agent in Agent Runtime or see [Manage sandboxes](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/sandbox/manage-sandboxes.md.txt#audit-logging-monitoring). |

#### Threat detection and monitoring

Sandboxes enforce runtime containment using gVisor kernel isolation in
Google-managed tenant projects and don't run a built-in in-guest host
intrusion detection agent or automatic pre-deployment vulnerability scanner. To
monitor sandbox activity and detect threats, combine the following controls:

- **Enable Data Access audit logs** : Enable `ADMIN_READ` and `DATA_WRITE` [Cloud Audit Logs](https://docs.cloud.google.com/gemini-enterprise-agent-platform/machine-learning/general/audit-logging.md.txt) on `aiplatform.googleapis.com` to detect unauthorized sandbox creation, access token generation (`AuthorizeSandboxEnvironmentAccess`), or execution requests.
- **Monitor parent agent behavior** : Enable [Agent anomaly detection](https://docs.cloud.google.com/gemini-enterprise-agent-platform/audit/agent-anomalies) to analyze traces, tool invocations, and execution patterns across your Agent Runtime agents.
- **Inspect network egress in your VPC** : Bridge sandbox egress into your VPC using a [Private Service Connect interface](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/sandbox/configure-vpc-sc.md.txt#control-egress) and enable VPC Flow Logs on the Private Service Connect subnet, Cloud NGFW rule logging, Secure Web Proxy access logs, and Cloud DNS query logging to detect anomalous outbound connections or data exfiltration attempts.
- **Scan custom container images before deployment** : When using [Custom containers (BYOC)](https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/sandbox/custom-containers.md.txt), enable vulnerability scanning in Artifact Registry to identify vulnerable packages before referencing the image URI in a `SandboxEnvironmentTemplate`.