> ## 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.

# eve provider reference

> The options of VmsSandbox.environment() and open(), the sandbox and template names, the session state, and the API calls of each eve lifecycle step in @vms.dev/eve.

For the setup steps, see [Run eve agents in sandboxes](https://vms.dev/docs/sandboxes/eve.md).

## Exports

| Export | Value |
| - | - |
| `VmsSandbox` | The eve sandbox provider. Call `VmsSandbox.environment(options)` in the sandbox file. |
| `vmsSandboxProvider` | The provider definition that `VmsSandbox` comes from, for `defineSandboxProvider()`. |
| `sandboxNameOf(sessionId, namespace?)` | The sandbox name of a session. |
| `templateNameOf(templateKey)` | The template name of a build. |
| `VmsSandboxOptions`, `VmsSandboxOpenOptions` | The option types. |
| `VmsSandboxState`, `VmsSandboxArtifact` | The session state, and the template of the build. |

The package works with eve 1.0. Its name in eve is `vms`.

## Environment options

`VmsSandbox.environment(options)` takes these options. Each option is optional.

| Option | Default | Value |
| - | - | - |
| `apiKey` | `VMS_API_KEY` | The API key. |
| `baseUrl` | `VMS_API_URL`, then `https://vms.dev/api` | The base URL of all routes. |
| `fetch` | `globalThis.fetch` | The `fetch` function for each request. |
| `size` | `small` | The size of a new sandbox. |
| `labels` | `{}` | The labels of a new sandbox. |
| `env` | `{}` | Environment variables for each command. `AI_AGENT=eve` comes first, and the `env` of one command comes last. A change makes a new template. |
| `namespace` | `""` | A text that goes into the sandbox name, so that 2 agents in one workspace get different names. A change makes a new template. |
| `workspaceRoot` | `/workspace` | The folder where commands start and relative paths resolve. A new sandbox makes it. A change makes a new template. |
| `stopAfterSeconds` | `3600` | The longest time that a sandbox runs for one step of a session, from 60. A new or resumed sandbox gets it as its `stopAfterSeconds`. |
| `stopWhenIdleSeconds` | `60` | The time after the last step before the sandbox stops. `0` stops the sandbox at the end of each step. `null` turns off the stop. |
| `waitTimeoutMs` | `120000` | The time to wait for a sandbox to be `running`, and for room on a host. |
| `prepare` | | Setup that goes into the template of the build. See [Run setup commands](https://vms.dev/docs/sandboxes/eve.md#run-setup-commands). |

`environment.open(options)` takes `size` and `labels`. They apply only when the call starts a new sandbox. The labels of `open()` go on top of the environment labels.

## Sandbox name

The name is `eve-` and the first 32 hexadecimal characters of the SHA-256 hash of the namespace, a zero byte, and the session ID. For example, `eve-3f9a1c2e7b4d0a6e8c5f1b2d9e7a4c3b`.

To find the sandbox of a session, send `GET /v1/sandboxes` with `name` and the states that hold a name: `creating`, `starting`, `running`, `stopping`, `stopped`, and `error`.

```typescript TypeScript theme={null}
import { sandboxNameOf } from "@vms.dev/eve";
import { Vms } from "@vms.dev/sdk";

const vms = new Vms();

const page = await vms.listSandboxes({
  name: sandboxNameOf(sessionId, "support-agent"),
  state: ["creating", "starting", "running", "stopping", "stopped", "error"],
});
```

## Template name

The template name is `eve-template-` and the first 32 hexadecimal characters of the template key of eve. For example, `eve-template-8d2f6a1c9e4b7d3a0f5c2e8b1a6d9f4c`. The provider gives eve `provider`, `version`, `namespace`, `workspaceRoot`, and `env` for the key. eve adds the workspace files, the skills, and the source of the sandbox file.

The artifact of the build is `{ templateId }`: the ID of the template, or `null` when the agent has no setup.

## Session state

eve saves `{ id, name }` with the session: the sandbox ID and its name. The sandbox of a live session has the extension `sandboxId`, which `ctx.getSandbox(environment)` gives.

## API calls of each step

| eve calls | API calls |
| - | - |
| `prepare` | `GET /v1/templates?name=` with the template name. A `ready` template is the artifact, and a `saving` template is the artifact when it is `ready`. A `failed` template gets `DELETE /v1/templates/{id}`. With no template, `POST /v1/sandboxes` with the label `eve-prepare: true`, the setup, `POST /v1/templates` with the name and the sandbox, `GET /v1/templates/{id}` each second until the template is `ready`, then `DELETE /v1/sandboxes/{id}`. When the agent has no workspace files, no skills, and no `prepare`, nothing. |
| `start` | `GET /v1/sandboxes?name=` with the states that hold a name. If no sandbox holds the name, `POST /v1/sandboxes` with the name and the `template` of the build. If 2 starts send the same name, the second start uses the sandbox of the first. |
| `resume` | `GET /v1/sandboxes/{id}`. A stopped sandbox gets `PATCH` with `"state": "running"`. A sandbox that stops soon gets `PATCH` with a new `stopAt`. |
| A command | `POST /v1/sandboxes/{id}/commands`, with `bash -lc` and the working folder. Aborting the call kills the command. |
| Read a file | `GET /v1/sandboxes/{id}/files`. A `404` gives `null`. |
| Write files | `PUT /v1/sandboxes/{id}/files` for one file, which keeps the mode of a file that exists. `POST /v1/sandboxes/{id}/files/tar` for more files, which gives each file the mode `0644`. |
| Remove a path | With `recursive`, `DELETE /v1/sandboxes/{id}/files`. Without it, the command `rm -d`, which does not remove a folder that has files. |
| The end of a step | `PATCH` with `stopAt` set to `stopWhenIdleSeconds` from now. |
| `sandbox.stop()` | `PATCH` with `"state": "stopped"`. A second stop does nothing. |
| `onSessionEnd` and `sandbox.delete()` | `DELETE /v1/sandboxes/{id}` for the saved sandbox and for the sandbox that holds the name. A sandbox that does not exist is not an error. |

## Errors and retries

| Problem | What the provider does |
| - | - |
| `503 no_capacity`, `429 rate_limited`, or `429 start_limit` on a create or a resume | Tries again until `waitTimeoutMs`. The wait starts at 1 second and doubles each time, up to 30 seconds, and is never shorter than `retryAfterSeconds`. |
| `503 unavailable` on a command or a file call | Tries again up to 3 times. |
| `409 sandbox_not_running`, `sandbox_stopping`, or `sandbox_starting` | Starts the sandbox, waits until it is `running`, and sends the call again one time. |
| The sandbox does not exist, is `deleting`, `deleted`, or `failed`, or answers `snapshot_expired` | `resume` throws `SandboxSessionGoneError`, and eve starts a new sandbox. |
| The template of the build is `failed` after a save | `prepare` throws the error of the template. The next build deletes the template and builds it again. |
| `POST /v1/sandboxes` answers `404` for the template of the build | `start` throws `SandboxTemplateNotProvisionedError`. Run `eve build` again. |

Each API key can send 1,200 requests each minute. Each step of a session sends about 3 requests in addition to its commands and file calls.

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


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