Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/content/docs/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -685,7 +685,7 @@ Other options, such as `thinkingLevel` and `env`, pass through to Pi Durable. By
Keys, subagents, agent-to-agent messages, workflows, schedules, and shared credentials.
</Card>
<Card title="Give an Agent a Sandbox" href="/guides/agent-sandboxes">
Run an agent's file and shell tools in agentOS, E2B, Daytona, Freestyle, or your own provider.
Run an agent's file and shell tools in agentOS, E2B, Daytona, Freestyle, Google Cloud Agent Platform, or your own provider.
</Card>
<Card title="Give an Agent Your Own Tools" href="/guides/agent-custom-tools">
Give an agent tools that run in your backend, with your APIs and secrets.
Expand Down
54 changes: 53 additions & 1 deletion docs/content/guides/agent-sandboxes.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Give an Agent a Sandbox"
description: "Run an agent without a sandbox, or give it a shell in agentOS, E2B, Daytona, Freestyle, Docker, or a sandbox provider you write."
description: "Run an agent without a sandbox, or give it a shell in agentOS, E2B, Daytona, Freestyle, Google Cloud Agent Platform, Docker, or a sandbox provider you write."
---

An agent doesn't need a sandbox. Without one, its file tools work on files in the Actor's own database. Add a sandbox only when the agent needs a shell.
Expand Down Expand Up @@ -75,6 +75,7 @@ agentOS needs no provider account. To use E2B or Daytona instead, see
| <a href="https://e2b.dev" target="_blank" rel="noopener noreferrer">E2B</a> | `e2b` | Paused | Deleted |
| <a href="https://daytona.io" target="_blank" rel="noopener noreferrer">Daytona</a> | `@daytonaio/sdk` | Stopped | Deleted |
| <a href="https://freestyle.sh" target="_blank" rel="noopener noreferrer">Freestyle</a> | `freestyle` | Paused | Deleted |
| <a href="https://docs.cloud.google.com/gemini-enterprise-agent-platform/scale/sandbox" target="_blank" rel="noopener noreferrer">Google Cloud Agent Platform</a> | `google-auth-library` | Paused | Deleted |
| <a href="https://docs.docker.com" target="_blank" rel="noopener noreferrer">Docker</a> | None. Uses the `docker` CLI. | Stopped | Removed |

Provider credentials stay on your worker and never enter the sandbox.
Expand Down Expand Up @@ -141,6 +142,57 @@ npm add @rivet-dev/sandbox-adapter freestyle

A Freestyle VM has no network access until a `firewall` rule allows it. Commands run as `root` through Python 3, so the image must include it. Every `freestyle/ubuntu*` snapshot does.

### Google Cloud Agent Platform

Each Actor gets a shell sandbox from Gemini Enterprise Agent Platform.

```sh
npm add @rivet-dev/sandbox-adapter google-auth-library
```

<CodeSnippet file="examples/docs/sandboxes/agent-platform.ts" title="server.ts" />

| Option | Description |
| --- | --- |
| `template` | Required. Resource name of a shell sandbox template. Sandboxes are created in its Agent Engine and Region. |
| `create` | Fields of the new sandbox, such as `ttl`, or a function that receives the Actor context and returns them. |
| `auth` | Supplies access tokens. Defaults to a `GoogleAuth` from `google-auth-library`, which uses Application Default Credentials. |
| `apiEndpoint` | Defaults to `https://{location}-aiplatform.googleapis.com` for the template's location. |
| `cwd` | Working directory inside the sandbox. Created when the Actor connects. Defaults to `/workspace`. |
| `readyTimeoutMs` | How long a create or connect waits for the sandbox to run. Defaults to 5 minutes. |

Create an Agent Engine and a shell sandbox template once, and reuse the template for every sandbox. Each call returns an operation. The engine's id is in the first operation's name. The template takes a few minutes to create: poll its operation until `done` is `true`, and `response.name` is the template to pass as `template`.

```sh
PROJECT=my-project
LOCATION=us-central1
API="https://$LOCATION-aiplatform.googleapis.com/v1/projects/$PROJECT/locations/$LOCATION"

gcloud services enable aiplatform.googleapis.com --project "$PROJECT"

curl -X POST "$API/reasoningEngines" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"displayName": "sandboxes"}'

curl -X POST "$API/reasoningEngines/ENGINE_ID/sandboxEnvironmentTemplates" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
"displayName": "shell",
"defaultContainerEnvironment": {"defaultContainerCategory": "DEFAULT_CONTAINER_CATEGORY_SHELL_SANDBOX"},
"egressControlConfig": {"internetAccess": true}
}'

curl "https://$LOCATION-aiplatform.googleapis.com/v1/OPERATION_NAME" \
-H "Authorization: Bearer $(gcloud auth print-access-token)"
```

- **Permissions.** Your worker's credentials need the `roles/aiplatform.user` role on the project.
- **Network.** A sandbox has no internet access unless its template sets `internetAccess`.
- **Commands.** Commands run as `appuser`, without `sudo`. Output arrives once a command ends, so `onData` is called once. Aborting ends the wait, but the command keeps running in the sandbox until it exits or reaches its timeout. A command that reaches `timeoutMs` is killed and returns no output. A command without `timeoutMs` runs until the sandbox's own time limit.
- **Lifetime.** The sandbox is deleted when its `ttl` ends. After that the Actor gets a new sandbox the next time a tool needs one, and the old files are lost.

### Docker

For local development. The provider runs the `docker` CLI on your worker, so it uses the current Docker context.
Expand Down
4 changes: 3 additions & 1 deletion docs/content/guides/sandbox-adapter.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Use a Sandbox from Any Actor"
description: "Use one API to create and drive sandboxes on agentOS, E2B, Daytona, Freestyle, or Docker from any Rivet Actor, without the agent harness."
description: "Use one API to create and drive sandboxes on agentOS, E2B, Daytona, Freestyle, Google Cloud Agent Platform, or Docker from any Rivet Actor, without the agent harness."
---

<Diagram
Expand Down Expand Up @@ -50,6 +50,7 @@ Every provider returns the same `SandboxProvider`, so you change one import and
| E2B | `e2bProvider()` | `@rivet-dev/sandbox-adapter/e2b` | `e2b` | `E2B_API_KEY` |
| Daytona | `daytonaProvider()` | `@rivet-dev/sandbox-adapter/daytona` | `@daytonaio/sdk` | `DAYTONA_API_KEY` |
| Freestyle | `freestyleProvider({ create })` | `@rivet-dev/sandbox-adapter/freestyle` | `freestyle` | `FREESTYLE_API_KEY` |
| Google Cloud Agent Platform | `agentPlatformProvider({ template })` | `@rivet-dev/sandbox-adapter/agent-platform` | `google-auth-library` | Application Default Credentials |
| Docker | `dockerProvider()` | `@rivet-dev/sandbox-adapter/docker` | Nothing | None |

## Manage the lifecycle
Expand Down Expand Up @@ -92,6 +93,7 @@ Some providers report output differently:

- **Daytona** returns stdout and stderr together in `stdout`, leaves `stderr` empty, and calls `onData` once when the command ends.
- **E2B and Daytona** return empty `stdout` and `stderr` after a timeout. On E2B, `onData` has already received the output.
- **Google Cloud Agent Platform** calls `onData` once when the command ends, with stdout and then stderr. A command that times out returns no output. Aborting does not stop the command.

## Use files

Expand Down
1 change: 1 addition & 0 deletions examples/docs/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@
"discord-interactions": "^4.4.0",
"e2b": "^2.51.0",
"freestyle": "^0.2.16",
"google-auth-library": "^11.3.4",
"hono": "^4.13.12",
"react": "^19.3.0",
"rivetkit": "^3.0.0"
Expand Down
25 changes: 25 additions & 0 deletions examples/docs/sandboxes/agent-platform.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
import { createRegistry } from "@earendil-works/pi-durable";
import { CodingTools } from "@earendil-works/pi-durable/tools";
import { pi } from "@rivet-dev/pi";
import { agentPlatformProvider } from "@rivet-dev/sandbox-adapter/agent-platform";
import { setup } from "rivetkit";

// read, write, edit, and bash, running in the sandbox
const extensions = createRegistry();
extensions.install(CodingTools);

const agent = pi({
model: "anthropic/claude-opus-5-5",
registry: extensions,
sandbox: agentPlatformProvider({
// The shell sandbox template from the setup below.
template:
"projects/my-project/locations/us-central1/reasoningEngines/ENGINE_ID/sandboxEnvironmentTemplates/TEMPLATE_ID",
// The sandbox and its files are deleted after a day.
create: { ttl: "86400s" },
}),
});

export const registry = setup({ use: { agent } });

registry.start();
16 changes: 14 additions & 2 deletions packages/sandbox-adapter/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@
"daytona",
"freestyle",
"docker",
"google-cloud",
"agent-platform",
"agent",
"ai",
"rivet",
Expand All @@ -38,6 +40,10 @@
"types": "./dist/agentos.d.ts",
"default": "./dist/agentos.js"
},
"./agent-platform": {
"types": "./dist/agent-platform.d.ts",
"default": "./dist/agent-platform.js"
},
"./e2b": {
"types": "./dist/e2b.d.ts",
"default": "./dist/e2b.js"
Expand All @@ -64,14 +70,16 @@
"scripts": {
"build": "tsc -p tsconfig.build.json",
"check-types": "tsc --noEmit",
"test": "vitest run"
"test": "vitest run",
"test:live": "vitest run --config vitest.live.config.ts"
},
"peerDependencies": {
"@daytonaio/sdk": "^0.216.0",
"@earendil-works/chord": "~1.5.0",
"@earendil-works/pi-durable": "~1.5.0",
"e2b": "^2.51.0",
"freestyle": "^0.2.16"
"freestyle": "^0.2.16",
"google-auth-library": "^11.3.4"
},
"peerDependenciesMeta": {
"@daytonaio/sdk": {
Expand All @@ -88,6 +96,9 @@
},
"freestyle": {
"optional": true
},
"google-auth-library": {
"optional": true
}
},
"devDependencies": {
Expand All @@ -97,6 +108,7 @@
"@types/node": "^24.0.0",
"e2b": "^2.51.0",
"freestyle": "^0.2.16",
"google-auth-library": "^11.3.4",
"typescript": "^5.9.2",
"vitest": "3.2.7"
},
Expand Down
Loading
Loading