How to create a Gemini Enterprise computer-use sandbox

Gemini Enterprise Agent Platform Computer Use sandboxes give your agents a secure, isolated browser they can operate the way a person would—clicking, navigating sites, typing, and taking screenshots. When you create a sandbox, the platform provisions a containerized environment that runs a web browser agent. You control that browser with API requests, or you attach over Chrome DevTools Protocol (CDP) and use automation tools such as Playwright.

This walkthrough follows Google Cloud’s official Computer Use quickstart. You create an Agent Platform instance, define a Computer Use template, start a sandbox, mint a JWT, send a health check and a CDP navigate command, then delete the resources.

Before you begin

Sign in to Google Cloud, select or create a project, and verify that billing is enabled for the project. Enable the Gemini Enterprise Agent Platform API.

To use the sandbox and generate tokens, you need:

• Agent Platform User (roles/aiplatform.user) on the project.
• Service Account Token Creator (roles/iam.serviceAccountTokenCreator) on the service account used for token generation.

The service account used for token generation must also have the Agent Platform User (roles/aiplatform.user) role on the project.

Install the Agent Platform SDK:

pip install google-cloud-agentplatform>=2.0.1

Create an Agent Platform instance

To use the sandbox, first create an Agent Platform instance. Construct a client with API version v1beta1, then create the runtime:

import agentplatform
client = agentplatform.Client(
    project='PROJECT_ID',
    location='LOCATION',
    http_options={
        "api_version": "v1beta1",
    }
)
remote_agent = client.runtimes.create()
remote_agent_name = remote_agent.api_resource.name

Replace PROJECT_ID with your Google Cloud project ID and LOCATION with the region for your instance (such as us-central1).

To encrypt your sandbox data using customer-managed encryption keys (CMEK), you must configure CMEK when you create your Agent Platform instance. That configuration is documented separately from this quickstart.

Create a template for Computer Use

Create a sandbox template that you will use when you create a Computer Use sandbox. The Computer Use category is DEFAULT_CONTAINER_CATEGORY_COMPUTER_USE. The sample also enables internet access in egress_control_config:

# Create a default Computer Use sandbox template
templates_client = client.sandboxes.templates
tmplt_operation = templates_client.create(
    name=remote_agent_name,
    display_name='DISPLAY_NAME',
    config={
        "default_container_environment": {
            "default_container_category": "DEFAULT_CONTAINER_CATEGORY_COMPUTER_USE",
        },
        "egress_control_config": {
            "internet_access": True,
        },
    },
)
template_name = tmplt_operation.response.name
print(f"Created template: {template_name}")

Store the template name from the operation response. The create-sandbox call references it as sandbox_environment_template.

Create a Computer Use sandbox

Create a sandbox environment from the template. The default lifetime is two hours. The official sample optionally overrides that lifetime with a duration string in seconds.

# Create a sandbox environment referencing the template.
# To customize the lifetime, set `ttl` to a duration string in seconds (for example, "3600s" for 1 hour).
create_operation = client.sandboxes.create(
    name=remote_agent_name,
    config={
        "sandbox_environment_template": template_name,
        "display_name": 'DISPLAY_NAME',
        "ttl": "3600s",  # Optional. Overrides the default 2-hour sandbox lifetime.
    }
)
sandbox = create_operation.response
print(f"Created sandbox environment: {sandbox.name}")
print(f"Sandbox will expire at: {sandbox.expire_time}")

The response includes the sandbox name and when the environment expires. You pass the sandbox object into later calls.

Generate an access token

To interact with the sandbox, generate a JSON web token (JWT) access token by using a service account:

service_account_email = "SERVICE_ACCOUNT_EMAIL"
access_token = client.sandboxes.generate_access_token(
    service_account_email=service_account_email,
)

Replace SERVICE_ACCOUNT_EMAIL with the email of the service account that has the Service Account Token Creator role.

Send a request to the sandbox

Send an HTTP GET request to the sandbox API server to check its status.

response = client.sandboxes.send_command(
    http_method="GET",
    access_token=access_token,
    sandbox_environment=sandbox
)
print(f"Sandbox response: {response.body}")

When that succeeds, send an HTTP POST request to navigate to a specific page. The quickstart posts a Page.navigate CDP command on path cdp:

data = {"command": "Page.navigate", "params": {"url": "https://example.com"}}

response = client.sandboxes.send_command(
    http_method="POST",
    path="cdp",
    access_token=access_token,
    request_dict=data,
    sandbox_environment=sandbox
)

The quickstart also lists additional methods and paths you can send to your sandbox. Those include a health check on the root path; creating a tab and listing open tabs; activating a tab or closing a specific tab; reading the CDP WebSocket endpoint path; running a CDP command on the active tab; and running multiple CDP commands on the active tab.

API requests cover common browser actions: navigating to a URL, clicking at specific coordinates, typing text into fields, and taking screenshots. For more advanced automation, connect to the sandbox browser over CDP and use Playwright. The Computer Use overview shows generating a WebSocket URL and headers with the Python SDK generate_browser_ws_headers method, then connecting with Playwright’s connect_over_cdp. Computer Use sandboxes also support a live streaming view (VNC) so you can monitor the agent in real time—for example with noVNC through WebSocket.

Clean up

To avoid incurring charges, delete the resources created in this quickstart:

client.sandboxes.delete(name=sandbox.name)
remote_agent.delete()

After a successful health check and Page.navigate, read the Computer Use overview for Playwright over CDP, the live streaming view, VPC Service Controls, and customer-managed encryption keys. When you are finished, delete the sandbox and runtime so you do not keep paying for an environment that would otherwise run until it expires.

Sources

• Computer Use quickstart
• Computer Use