Ch8. Sandbox Secure Runtime

Turn Eve sandbox trust boundaries, backends, network policy, credential brokering, and workspace lifecycle into operating standards.

Key takeaways

Eve sandbox isolates built-in shell/file work; it does not sandbox authored tool execute.
Backend choice, network policy, workspace seed, and credential brokering define production posture.
Sandbox state follows the durable session, so retention, reproducibility, and egress need governance.

The sandbox is where model-driven shell and file work happens. The mistake is assuming that "there is a sandbox" means "it is safe." The real question is what is allowed inside it.

Trust Boundary

Concern	App runtime	Sandbox
secrets/env	available	not available by default
custom tool `execute`	runs here	does not run here
shell/file effects	proxied	applied to `/workspace`
filesystem	app code	isolated workspace
network	runtime environment	sandbox network policy

Built-in Sandbox Tools

Tool	Function
`bash`	run shell commands
`read_file`	read text with line numbers
`write_file`	complete file write with read-before-write enforcement
`glob`	file pattern search
`grep`	regex content search

Disable or override tools that do not fit the agent's purpose.

agent/tools/bash.ts

import { disableTool } from "eve/tools";

export default disableTool();

Backend Selection

Backend	Runs where	Use
`vercel()`	Vercel Sandbox microVM	hosted production
`docker()`	local Docker container	local/self-host with real binaries
`microsandbox()`	local lightweight VM	local isolation close to Vercel Sandbox
`justbash()`	JS bash interpreter	fallback with limited capabilities
`defaultBackend()`	availability-aware choice	fast start, less explicit

For production, prefer explicit backend policy, especially when network or resource controls matter.

`defineSandbox` Pattern

agent/sandbox/sandbox.ts

import { defineSandbox } from "eve/sandbox";
import { vercel } from "eve/sandbox/vercel";

export default defineSandbox({
  backend: vercel({
    runtime: "node24",
    resources: { vcpus: 2 },
    networkPolicy: "deny-all",
  }),
  revalidationKey: () => "bootstrap-v1",
  async bootstrap({ use }) {
    const sandbox = await use();
    await sandbox.run({ command: "mkdir -p reports" });
  },
  async onSession({ use, ctx }) {
    const sandbox = await use({ networkPolicy: "deny-all" });
    const principal = ctx.session.auth.current?.principalId ?? "anonymous";
    await sandbox.writeTextFile({
      path: "SESSION_PRINCIPAL.txt",
      content: `${principal}\n`,
    });
  },
});

Bootstrap vs onSession

Lifecycle	Scope	Put here	Avoid
`bootstrap`	template-scoped	common packages, baseline repo clone	per-user secrets, tenant data
`onSession`	durable session-scoped	principal markers, per-session setup	expensive common setup repeated

Workspace Seed

Files under agent/sandbox/workspace/** are copied into /workspace.

agent/sandbox/
├── sandbox.ts
└── workspace/
    ├── schema.sql
    └── scripts/run-report.sh

Do not put secrets in seed files. If you seed customer snapshots, define retention and deletion policy.

Network Policy

Default sandbox egress is allow-all. Sensitive or production agents should narrow it.

Policy	Meaning
`"allow-all"`	all egress allowed
`"deny-all"`	egress blocked
allow-list object	domain/subnet controls

networkPolicy: {
  allow: ["api.github.com", "*.vercel.com"],
  subnets: { deny: ["10.0.0.0/8"] },
}

Backend capability differs. Docker and just-bash do not provide the same network-control semantics as hosted Vercel Sandbox or microsandbox.

Credential Brokering

Vercel Sandbox and microsandbox support credential brokering: headers can be inserted at the network/firewall layer for allowed hosts without exposing token strings to the model.

Use it carefully:

Use	Judgment
private repo clone	good fit with allow-list
arbitrary `curl` bearer token	risky
internal API call	prefer custom tool or connection when possible
token string in prompt or workspace	prohibited

The sandbox filesystem persists for the same durable session. Vercel may idle the VM but preserve filesystem state. Docker keeps long-lived containers; just-bash stores a local virtual filesystem cache.

Operating points:

monitor workspace growth
delete sensitive artifacts when no longer needed
include sandbox id/session id in audit logs
remember that declared subagents may have separate sandboxes

Security Checklist

Item	Standard
backend	explicit production backend
network	deny-all or allow-list
secrets	no secrets in workspace or seed
default tools	disable/override when unnecessary
bootstrap	no tenant data; revalidation key set
onSession	applies auth-derived policy
credential brokering	only with host allow-list
eval	validates tool access and network limits

Key takeaways

Eve sandbox isolates built-in shell/file work; it does not sandbox authored tool execute.
Backend choice, network policy, workspace seed, and credential brokering define production posture.
Sandbox state follows the durable session, so retention, reproducibility, and egress need governance.

The sandbox is where model-driven shell and file work happens. The mistake is assuming that "there is a sandbox" means "it is safe." The real question is what is allowed inside it.

Trust Boundary

Concern	App runtime	Sandbox
secrets/env	available	not available by default
custom tool `execute`	runs here	does not run here
shell/file effects	proxied	applied to `/workspace`
filesystem	app code	isolated workspace
network	runtime environment	sandbox network policy

Built-in Sandbox Tools

Tool	Function
`bash`	run shell commands
`read_file`	read text with line numbers
`write_file`	complete file write with read-before-write enforcement
`glob`	file pattern search
`grep`	regex content search

Disable or override tools that do not fit the agent's purpose.

agent/tools/bash.ts

import { disableTool } from "eve/tools";

export default disableTool();

Backend Selection

Backend	Runs where	Use
`vercel()`	Vercel Sandbox microVM	hosted production
`docker()`	local Docker container	local/self-host with real binaries
`microsandbox()`	local lightweight VM	local isolation close to Vercel Sandbox
`justbash()`	JS bash interpreter	fallback with limited capabilities
`defaultBackend()`	availability-aware choice	fast start, less explicit

For production, prefer explicit backend policy, especially when network or resource controls matter.

`defineSandbox` Pattern

agent/sandbox/sandbox.ts

import { defineSandbox } from "eve/sandbox";
import { vercel } from "eve/sandbox/vercel";

export default defineSandbox({
  backend: vercel({
    runtime: "node24",
    resources: { vcpus: 2 },
    networkPolicy: "deny-all",
  }),
  revalidationKey: () => "bootstrap-v1",
  async bootstrap({ use }) {
    const sandbox = await use();
    await sandbox.run({ command: "mkdir -p reports" });
  },
  async onSession({ use, ctx }) {
    const sandbox = await use({ networkPolicy: "deny-all" });
    const principal = ctx.session.auth.current?.principalId ?? "anonymous";
    await sandbox.writeTextFile({
      path: "SESSION_PRINCIPAL.txt",
      content: `${principal}\n`,
    });
  },
});

Bootstrap vs onSession

Lifecycle	Scope	Put here	Avoid
`bootstrap`	template-scoped	common packages, baseline repo clone	per-user secrets, tenant data
`onSession`	durable session-scoped	principal markers, per-session setup	expensive common setup repeated

Workspace Seed

Files under agent/sandbox/workspace/** are copied into /workspace.

agent/sandbox/
├── sandbox.ts
└── workspace/
    ├── schema.sql
    └── scripts/run-report.sh

Do not put secrets in seed files. If you seed customer snapshots, define retention and deletion policy.

Network Policy

Default sandbox egress is allow-all. Sensitive or production agents should narrow it.

Policy	Meaning
`"allow-all"`	all egress allowed
`"deny-all"`	egress blocked
allow-list object	domain/subnet controls

networkPolicy: {
  allow: ["api.github.com", "*.vercel.com"],
  subnets: { deny: ["10.0.0.0/8"] },
}

Backend capability differs. Docker and just-bash do not provide the same network-control semantics as hosted Vercel Sandbox or microsandbox.

Credential Brokering

Vercel Sandbox and microsandbox support credential brokering: headers can be inserted at the network/firewall layer for allowed hosts without exposing token strings to the model.

Use it carefully:

Use	Judgment
private repo clone	good fit with allow-list
arbitrary `curl` bearer token	risky
internal API call	prefer custom tool or connection when possible
token string in prompt or workspace	prohibited

Session Persistence

Operating points:

monitor workspace growth
delete sensitive artifacts when no longer needed
include sandbox id/session id in audit logs
remember that declared subagents may have separate sandboxes

Security Checklist

Item	Standard
backend	explicit production backend
network	deny-all or allow-list
secrets	no secrets in workspace or seed
default tools	disable/override when unnecessary
bootstrap	no tenant data; revalidation key set
onSession	applies auth-derived policy
credential brokering	only with host allow-list
eval	validates tool access and network limits

Trust Boundary

Built-in Sandbox Tools

Backend Selection

`defineSandbox` Pattern

Bootstrap vs onSession

Workspace Seed

Network Policy

Credential Brokering

Session Persistence

Security Checklist

On this page

Ch8. Sandbox Secure Runtime

Trust Boundary

Built-in Sandbox Tools

Backend Selection

`defineSandbox` Pattern

Bootstrap vs onSession

Workspace Seed

Network Policy

Credential Brokering

Session Persistence

Security Checklist

On this page