@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, andsnapshots:readscopes. 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.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, runspreparein 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, thenamespace, theworkspaceRoot, or theenvoption 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
preparestarts 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. Runeve buildagain.
Change the options
Give the options toVmsSandbox.environment(), such as the size, labels, a namespace, and the idle time before a stop. See eve provider reference.
TypeScript
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 withsandboxId, and call the API with the TypeScript SDK, for example to make a URL for a port.
TypeScript