Control an Agent Platform sandbox's private ingress and internet egress with Private Service Connect (PSC-E / PSC-I). These controls make the sandbox compliant with VPC Service Controls inside a perimeter or without a perimeter.
Overview
VPC Service Controls lets you define a service perimeter that isolates Google Cloud resources to mitigate the risk of data exfiltration. The Gemini Enterprise Agent Platform sandbox gives your agents a secure, isolated compute environment to run untrusted code, drive a web browser (computer use), or execute a custom container image. The sandbox exposes an interactive data plane and makes outbound calls, so it is governed with two Private Service Connect controls: private ingress (PSC-E) and egress control (PSC-I).
When you run the sandbox inside a perimeter, the following stay protected within your boundary:
- Data your agent reads or writes during a sandbox session (files on the sandbox disk, in-memory state).
- Sandbox snapshots that capture disk and in-memory state and are stored automatically in a Cloud Storage bucket.
- Requests and responses exchanged with the sandbox data plane (for example, computer-use commands and screenshots).
- Custom container images pulled from Artifact Registry.
- Calls the sandbox makes to Google APIs (for example, Cloud Storage or Agent Platform).
You can also set up ingress and egress control without a VPC Service Controls perimeter, since the PSC-E (private ingress) and PSC-I (egress) are what makes a sandbox VPC Service Controls-compliant. To set up ingress and egress without a VPC Service Controls perimeter, skip to Control sandbox egress with a Private Service Connect interface (PSC-I).
Limitations and considerations
Keep the following limitations and security boundaries in mind when configuring VPC Service Controls and Private Service Connect for sandboxes:
- No built-in sandbox domain allowlist: Sandboxes and
SandboxEnvironmentTemplateresources don't have a built-in domain allowlist field. Enablinginternet_access: Trueonegress_control_configwithout anetwork_attachmentgrants unrestricted outbound access to public IP addresses (0.0.0.0/0, excluding private RFC 1918 ranges and the169.254.0.0/16metadata range). To restrict outbound connections by domain name (FQDN), URL, or IP address, you must bridge sandbox egress into your VPC with a Private Service Connect interface (network_attachment) and enforce filtering in your VPC using Cloud Next Generation Firewall (Cloud NGFW) or Secure Web Proxy (Secure Web Proxy). - Single consumer project for private ingress: Private ingress (PSC-E) can be enabled for at most one consumer project, which must be the same user project that the sandbox runs in.
- DNS resolution and anti-tunneling: When egress is bridged into your VPC, only private name resolution through Cloud DNS peering (
dns_peering_configs) is supported; public DNS forwarding is disabled to prevent DNS-tunnel exfiltration. - Cloud Audit Logs and network threat inspection: Cloud Audit Logs records control-plane lifecycle calls and data-plane execution RPCs (
ExecuteSandboxEnvironment,BidiExecuteSandboxEnvironment, andAuthorizeSandboxEnvironmentAccess), while request and response payload logging is unavailable for resources protected by VPC Service Controls. Individual child processes and network sockets inside the container aren't logged in Cloud Audit Logs; to inspect outbound connections and detect network threats, enable VPC Flow Logs, Cloud NGFW rule logging, Cloud DNS query logging, and Secure Web Proxy logs in your VPC. - Isolated in-sandbox identity: Code inside the sandbox runs under an unprivileged tenant identity with no Identity and Access Management (IAM) roles on your project, doesn't inherit the parent agent's Agent Identity or service account, and can't query the Compute Engine metadata server (
169.254.169.254:80) for credentials. For details, see Execution identity and credential boundaries. - Perimeter access levels: Programmatic and console access from outside the perimeter is denied unless the caller matches an access level on the perimeter.
Before you begin
Before configuring VPC Service Controls or Private Service Connect for your sandboxes, complete the following prerequisites:
- Create or identify the VPC Service Controls service perimeter that contains your project. In order for the sandboxes to be secured by the VPC Service Controls perimeter, your Google Cloud project must be in the perimeter before you create the sandboxes.
- Enable the Agent Platform API (
aiplatform.googleapis.com) in your project. - Have a VPC network in the region where you run sandboxes.
- Confirm you hold the required roles:
- Access Context Manager admin role for the perimeter
- Compute Network Admin (
roles/compute.networkAdmin) in the project that owns the network attachment.
Add Agent Platform to your service perimeter
Add the Agent Platform API to the list of restricted services in your VPC Service Controls perimeter. This protects Agent Platform (including the sandbox control plane) and blocks public internet access to the API unless the caller is on an access level.
- Open VPC Service Controls in the Google Cloud console and edit your perimeter.
- Under Restricted services, add Agent Platform API (
aiplatform.googleapis.com). - Ensure dependencies your sandbox uses are in the same perimeter, typically Cloud Storage (
storage.googleapis.com) and Artifact Registry (artifactregistry.googleapis.com, for custom container images). Snapshot storage is handled for you automatically. - To restore access for trusted users outside the perimeter (for example, your corporate network), attach an access level to the perimeter.
Optional: Configure private access to Google APIs
Inside the VPC Service Controls perimeter, the sandbox reaches Google APIs privately over the restricted virtual IP address (VIP). From your own VPC and on-premises networks, use the restricted VIP as well so requests never traverse the public internet:
- Route
*.googleapis.comto the restricted VIP199.36.153.4/30and enable Private Google Access on the subnets that call Google APIs. - Create Cloud DNS private zones for
googleapis.com(and, if you pull images,pkg.dev/gcr.io) that resolve to the restricted VIP.
Control sandbox egress with a Private Service Connect interface (PSC-I)
Because sandboxes don't include a built-in domain allowlist setting, use a Private Service Connect interface (PSC-I) whenever you need to allowlist outbound domains (FQDNs), filter URLs, or let the sandbox reach private services. PSC-I bridges all sandbox egress into your VPC so you can govern and log that traffic with your own VPC security controls, whether or not your project is inside a VPC Service Controls perimeter.
Every resource in this step is created in the user project that owns the sandbox or in its Shared VPC host project. Egress is directed to the single VPC network and network attachment you set on the template.
Create the network attachment
Create the network attachment for the sandbox:
# A dedicated subnet for the PSC interface (minimum /28)
gcloud compute networks subnets create sandbox-psc-subnet \
--network=YOUR_VPC \
--range=10.0.0.0/28 \
--region=REGION
# The network attachment the sandbox connects into
gcloud compute networks network-attachments create sandbox-egress-na \
--region=REGION \
--connection-preference=ACCEPT_AUTOMATIC \
--subnets=sandbox-psc-subnet
Reference the attachment from the sandbox template
Set the egress fields on the SandboxEnvironmentTemplate so the sandbox routes egress through your VPC:
from vertexai import Client
client = Client(project="PROJECT_ID", location="REGION",
http_options={"api_version": "v1beta1"})
templates = client.agent_engines.sandboxes.templates
op = templates.create(
name=agent_instance_name,
display_name="cu-vpcsc-template",
config={
"custom_container_environment": {
"custom_container_spec": {"image_uri": "IMAGE_URI"},
"ports": [{"port": 8080, "protocol": "TCP"}],
},
"egress_control_config": {
"internet_access": True, # Enables outbound access from the sandbox. With VPC-SC, that traffic is bridged into your VPC.
"customer_vpc_network":
"projects/PROJECT_ID/global/networks/YOUR_VPC", # The VPC network in your project that egress is bridged into. Checked by VPC-SC at creation time.
"network_attachment":
"projects/PROJECT_ID/regions/REGION/networkAttachments/sandbox-egress-na", # The network attachment that accepts the sandbox's PSC interface.
},
},
)
The PSC interface builds the private path into your VPC, and the platform automatically steers the sandbox's egress onto it when internet_access is enabled.
To set up and govern the path out of your VPC, decide if you need internet or private-only egress:
- Internet egress: For internet egress, Cloud NAT is required, plus destination control using Cloud Next Generation Firewall (Cloud NGFW) rules or Secure Web Proxy.
- Private-only egress (reach services in your VPC or on-premises, no internet): Cloud NAT isn't required. You only need routes, a firewall rule, and DNS peering.
Set up for internet egress and govern destinations
The sandbox enters your VPC on an internal (RFC 1918) address, so it needs Cloud NAT to reach the internet. Reserve a static egress IP if your destinations allow-list by source IP.
# Reserve a static egress IP (optional, for destination-side allow-listing)
gcloud compute addresses create sandbox-egress-ip --region=REGION
# Cloud Router + NAT for the region, scoped to the PSC subnet
gcloud compute routers create sandbox-egress-router \
--network=YOUR_VPC --region=REGION
gcloud compute routers nats create sandbox-egress-nat \
--router=sandbox-egress-router --region=REGION \
--nat-external-ip-pool=sandbox-egress-ip \
--nat-custom-subnet-ip-ranges=sandbox-psc-subnet
To restrict which destinations the sandbox may reach as its traffic transits your VPC, choose the level of control you need:
Cloud NGFW (network-level): a global network firewall policy with allow rules (FQDN objects are supported) plus a default-deny for everything else:
gcloud compute network-firewall-policies create sandbox-egress-policy --global # Allow only the destinations your agent needs (by FQDN) gcloud compute network-firewall-policies rules create 1000 \ --firewall-policy=sandbox-egress-policy --global-firewall-policy \ --direction=EGRESS --action=allow --layer4-configs=tcp:443 \ --dest-fqdns=api.partner.example.com # Default-deny the rest of egress gcloud compute network-firewall-policies rules create 65000 \ --firewall-policy=sandbox-egress-policy --global-firewall-policy \ --direction=EGRESS --action=deny --layer4-configs=all \ --dest-ip-ranges=0.0.0.0/0 gcloud compute network-firewall-policies associations create \ --firewall-policy=sandbox-egress-policy --global-firewall-policy \ --network=YOUR_VPCSecure Web Proxy (application/L7): deploy Secure Web Proxy as the egress inspection point in your VPC for TLS-aware, per-URL policy, and route the PSC subnet's egress through it.
Set up for private-only egress
If the sandbox only needs private services in your VPC or on-premises, make sure your VPC has a route to the destination, allow it with an egress firewall rule from the PSC subnet (10.0.0.0/28), and resolve the service name through DNS peering.
Set up DNS peering
Give the sandbox name resolution through your VPC instead of public resolvers (this also blocks DNS-tunnel exfiltration). Create a Cloud DNS private zone in your VPC with the records the sandbox needs, then configure DNS peering so the sandbox resolves names from that zone.
Grant the service agent access (Shared VPC)
If the network attachment lives in a separate project (Project A) from the project where the sandbox is run (Project B), grant Project B's Agent Platform service agent the Compute Network User role on Project A:
# Agent Platform service agent of the project that runs the sandbox
service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com
# On the project that owns the network attachment
gcloud projects add-iam-policy-binding NETWORK_PROJECT_ID \
--member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com" \
--role="roles/compute.networkUser"
Replace the following:
PROJECT_NUMBER: the project number of the project that runs the sandbox.NETWORK_PROJECT_ID: the ID of the project that owns the network attachment.
Enable private ingress with Private Service Connect (PSC-E)
Interactive workloads expose a data plane that a client must connect to. Reach that data plane over a private Private Service Connect endpoint (PSC-E) in your VPC instead of over the public internet.
Declare the allowed consumer project
Set the ingress configuration on the template with the consumer project allowed to connect. Only the same user project that the sandbox runs in can have private ingress to the sandbox VPC.
Connect to the sandbox from a VPC in that same project:
config = {
# ...custom_container_environment, egress_control_config...
"ingress_control_config": {
"private_service_connect_config": {
# Must be the same project the sandbox runs in.
"enable_private_service_connect": True,
}
},
}
Create the PSC endpoint in your VPC
After the sandbox is created, read the service attachment from its connection info:
# The sandbox returns a service attachment to connect to
service_attachment = sandbox.connection_info.service_attachment
Then, reserve an internal IP address and create a forwarding rule (PSC endpoint) in your VPC that targets the service attachment:
# Reserve an internal IP and create the PSC endpoint
gcloud compute addresses create sandbox-ingress-ip \
--region=REGION --subnet=YOUR_SUBNET
gcloud compute forwarding-rules create sandbox-ingress-ep \
--region=REGION \
--network=YOUR_VPC \
--address=sandbox-ingress-ip \
--target-service-attachment=SERVICE_ATTACHMENT_URI
Clients in that project's VPC (or reachable through it) now connect to the sandbox through the endpoint's private IP (for example, a client connecting over the sandbox WebSocket or CDP port).
What's next
To continue configuring and securing your sandboxes, see the following resources:
- Read the Sandbox overview and Custom containers (BYOC).
- Learn how Private Service Connect interfaces work with Agent Runtime.
- Review VPC Service Controls troubleshooting.
- Follow the Agent Engine PSC interface codelab for an end-to-end egress walkthrough.