> ## Documentation Index
> Fetch the complete documentation index at: https://vms.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Run eve agents in sandboxes

> Install the @vms.dev/eve sandbox provider, give an eve agent a sandbox for each session, build a template at eve build, and see what happens when the session sleeps, resumes, and ends.

[eve](https://github.com/vercel/eve) is a framework for backend AI agents. The `@vms.dev/eve` package gives each eve session its own sandbox. The `bash`, `read_file`, `write_file`, and `edit_file` tools of the agent then run in that sandbox.

Give my eve agent a vms.dev sandbox.

Use the @vms.dev/eve package with eve 1.0.
In agent/sandbox.ts, export environment = VmsSandbox.environment() and a default defineSandbox(() => environment.open()).
Read the API key from the VMS\_API\_KEY environment variable.
Do not ask me to share my API key.

## Before you start

* You need an eve 1.0 project. See [Getting started](https://github.com/vercel/eve) in the eve docs.
* Your workspace needs a plan or a trial. See [Choose a plan or start a trial](https://vms.dev/docs/workspace/billing.md).
* You need an API key with the `sandboxes:read`, `sandboxes:write`, `sandboxes:exec`, `sandboxes:files`, `templates:read`, `templates:write`, and `snapshots:read` scopes. See [API keys](https://vms.dev/docs/workspace/api-keys.md).
* The package runs where eve runs: on Node.js 24 or later, or on Bun.

## Give the agent a sandbox

**1. Install the package**

Install the package, and put your API key in the `VMS_API_KEY` environment variable of the eve app.

```bash theme={null}
npm install @vms.dev/eve
export VMS_API_KEY="<your-api-key>"
```

**2. Write the sandbox file**

Save this code in `agent/sandbox.ts`. If the agent has an `agent/sandbox/` folder, save it in `agent/sandbox/sandbox.ts`.

```typescript TypeScript theme={null}
import { VmsSandbox } from "@vms.dev/eve";
import { defineSandbox } from "eve/sandbox";

export const environment = VmsSandbox.environment({
  size: "small",
  prepare: async (sandbox) => {
    const result = await sandbox.run({ command: "apt-get install -y ripgrep" });

    if (result.exitCode !== 0) throw new Error(result.stderr);
  },
});

export default defineSandbox(() => environment.open());
```

**3. Run the agent**

Start the agent with `eve dev`, and send it a message that uses a tool, such as "List the files in the workspace". The first sandbox access builds a template one time, then starts the sandbox of the session from it.

To see the sandbox, open **Sandboxes** in the app. Its name starts with `eve-`. See [Use sandboxes in the app](https://vms.dev/docs/sandboxes/in-the-app.md).

## What happens in a session

| When | What happens to the sandbox |
| - | - |
| The first tool call of a session | A new sandbox starts from the template of the build. Its name comes from a hash of the session ID. It has the workspace files, the skills, and the files that `prepare` made. |
| Each tool call | The sandbox runs the command or the file change. If the sandbox is stopped, it starts again first. |
| The session waits for the next message | After `stopWhenIdleSeconds` with no tool call, the sandbox stops. Its files stay. The default is 60 seconds. |
| The next message | The same sandbox starts again with the same files. Within 10 minutes of the stop, it also keeps its running programs. |
| The session ends, or the agent calls `sandbox.delete()` | The sandbox is deleted. |
| The sandbox was deleted outside the session | The session continues in a new sandbox, without the old files. |

See [Stop and resume a sandbox](https://vms.dev/docs/sandboxes/stop-and-resume.md) for the stop and the resume.

## Run setup commands

`eve build`, and the first sandbox access in `eve dev`, build a template from the workspace files, the skills, and `prepare`. Each new sandbox of a session starts from this template, so it does not run `prepare` again. See [Save a sandbox as a template](https://vms.dev/docs/sandboxes/templates.md).

* To build the template, the provider starts a sandbox with the label `eve-prepare: true`, runs `prepare` in it, and saves it as a template. Then it deletes the sandbox.
* The template name is `eve-template-` and 32 hexadecimal characters of the template key of eve. The key changes when the workspace files, the skills, the sandbox file, the `namespace`, the `workspaceRoot`, or the `env` option change.
* A build with no change uses the template that has this name. It does not start a sandbox.
* A template holds files only. A program that `prepare` starts does not run in a new sandbox.
* Each build with a change saves a new template. The old template stays, because an older deployment can still use it. Delete the templates that you do not use. They count against the templates of your plan. See [Plans](https://vms.dev/docs/reference/plans.md#plans).
* If the template of a deployment is deleted, a new session fails with `SandboxTemplateNotProvisionedError`. Run `eve build` again.

## Change the options

Give the options to `VmsSandbox.environment()`, such as the size, labels, a namespace, and the idle time before a stop. See [eve provider reference](https://vms.dev/docs/reference/eve-provider.md).

```typescript TypeScript theme={null}
export const environment = VmsSandbox.environment({
  size: "medium",
  namespace: "support-agent",
  labels: { agent: "support" },
  stopWhenIdleSeconds: 300,
});
```

Use a different `namespace` for each agent that uses the same workspace, so that two agents never share a sandbox name.

## Use the API in a tool

A tool can read the sandbox ID with `sandboxId`, and call the API with the [TypeScript SDK](https://vms.dev/docs/reference/typescript-sdk.md), for example to make a URL for a port.

```typescript TypeScript theme={null}
import { Vms } from "@vms.dev/sdk";
import { defineTool } from "eve/tools";
import { z } from "zod";
import { environment } from "../sandbox";

export default defineTool({
  description: "Make a public URL for a port of the sandbox.",
  inputSchema: z.object({ port: z.number() }),
  async execute(input, ctx) {
    const sandbox = await ctx.getSandbox(environment);
    const vms = new Vms();

    const url = await vms.createSandboxUrl({
      id: sandbox.sandboxId,
      body: { port: input.port, public: true },
    });

    return url.url;
  },
});
```

Read the [changelog.](https://vms.dev/docs/changelog.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.