Skip to main content
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.

Before you start

  • You need an eve 1.0 project. See Getting started in the eve docs.
  • Your workspace needs a plan or a trial. See Choose a plan or start a trial.
  • 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.
  • 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.
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
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.

What happens in a session

See Stop and resume a sandbox 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.
  • 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.
  • 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.
TypeScript
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, for example to make a URL for a port.
TypeScript