# Eve

> Give an Eve agent a Nevia computer as its sandbox, so its file tools and commands run on the computer

> Nevia is in early access for selected teams. The CLI installs with `curl -fsSL https://get.nevia.cloud | sh`, and the MCP server is at https://api.nevia.cloud/mcp. A person signs in once in the browser.
> Setup, sign-in and requesting access: [SKILL.md](https://nevia.cloud/SKILL.md). When Nevia fits and when it doesn't: [why.md](https://nevia.cloud/why.md).

> For the complete documentation index, see [llms.txt](https://nevia.cloud/llms.txt). This page's HTML version: https://nevia.cloud/docs/agent-frameworks/eve

The Eve adapter gives an [Eve](https://eve.dev) agent a sandbox on a Nevia
computer. The agent's file tools and its commands run on the computer, not on
your machine. The adapter is built on the
[TypeScript SDK](https://nevia.cloud/docs/reference/sdk/typescript.md) and is in early access, so
names and behaviour can change.

The quick start gives an agent a computer, asks it to write and run a program
and deletes the computer. The adapter follows Eve's sandbox provider contract,
so [Eve's custom provider docs](https://eve.dev/docs/sandbox/custom-providers)
cover the options and the lifecycle. This page covers only what is particular
to Nevia.

## Prerequisites

You need:

* Node.js 24.22.1 or later.
* `eve` 0.91 or later.
* An API key for the model provider. The quick start uses Anthropic, so it
  needs `ANTHROPIC_API_KEY`.
* The `nevia` CLI, signed in with `nevia login`, to download the SDK bundle.
  The [Quickstart](https://nevia.cloud/docs/get-started/quickstart.md) shows how to install it.
* A Nevia key file for a service account with the **editor** role.
  [Use an automation key file](https://nevia.cloud/docs/guides/automation-key-file.md) shows how a
  workspace admin issues one.

## 1. Install the adapter

> **Invited testers only**
>
> The SDKs are in early access for invited testers. To ask for access, see
> [Request access to Nevia](https://nevia.cloud/docs/get-started/request-access.md).

From your project's root, download the SDK bundle. It unpacks to
`vendor/nevia-sdk-0.1.0/`:

```bash
curl -fsSL --oauth2-bearer "$(nevia auth access-token)" https://sdk.nevia.cloud/0.1.0.tar.gz | tar -xz
```

Then install the adapter, with the SDK beside it, from the bundle:

**npm**

```bash
npm init -y
npm pkg set type=module
npm install ./vendor/nevia-sdk-0.1.0/typescript/nevia-sdk-0.1.0.tgz \
  ./vendor/nevia-sdk-0.1.0/typescript/nevia-eve-0.1.0.tgz \
  eve zod
npm install --save-dev tsx
```

Name the SDK's file next to the adapter's, so both come from the bundle and
nothing is looked up on a public registry.

The quick start loads its TypeScript files into Eve with [tsx](https://tsx.is)
through `NODE_OPTIONS="--import tsx"`.

## 2. Authenticate

Point the adapter at the key file and set the model provider's key:

```bash
export NEVIA_KEY_FILE="$HOME/path/to/key.json"
export ANTHROPIC_API_KEY="sk-ant-..."
```

Without `NEVIA_KEY_FILE`, the adapter falls back to your `nevia login`
session. It finds credentials in the same order as the
[TypeScript SDK](https://nevia.cloud/docs/reference/sdk/typescript.md#client).

## 3. Give an agent a computer

An Eve agent is a folder of files. Create `agent/agent.ts`:

```ts
import { defineAgent } from 'eve'
import { anthropic } from 'eve/models/anthropic'

export default defineAgent({
  model: anthropic('claude-sonnet-5-5'),
})
```

Create `agent/instructions.md`:

```md
You write and run code in your sandbox. Work in /workspace. Use run_command to run commands.
```

Create `agent/sandbox.ts`, which opens the sandbox on a Nevia computer:

```ts
import { defineSandbox } from 'eve/sandbox'
import { NeviaSandbox } from '@nevia/eve'

export const environment = NeviaSandbox.environment({ image: 'docker.io/library/node:24-slim' })
export default defineSandbox(() => environment.open())
```

Create `agent/tools/run_command.ts`. Eve's own `bash` tool needs background
processes, which the adapter doesn't run, so this tool runs a foreground
command on the computer instead:

```ts
import { neviaComputerOf } from '@nevia/eve'
import { defineTool } from 'eve/tools'
import { z } from 'zod'

export default defineTool({
  description: 'Run a shell command in the workspace and wait for it to end.',
  inputSchema: z.object({ command: z.string() }),
  async execute({ command }, ctx) {
    const sandbox = await ctx.getSandbox()
    const result = await neviaComputerOf(sandbox).exec(command, {
      cwd: sandbox.resolvePath('.'),
      transport: 'direct',
    })
    return { stdout: result.stdout, stderr: result.stderr, exitCode: result.exitCode }
  },
})
```

Create `agent/tools/bash.ts` to turn off Eve's `bash` tool so the model can't
pick it:

```ts
import { disableTool } from 'eve/tools'

export default disableTool()
```

Start the agent in one terminal:

```bash
NODE_OPTIONS="--import tsx" npx eve dev --no-ui
```

Ask it from a second terminal:

```bash
npx eve remote connect --url http://localhost:2000 --print \
  "Write hello.js that prints the Node.js version, then run it. Answer with its output only."
```

The agent writes `/workspace/hello.js` with Eve's `write_file` tool, runs
`node hello.js` with `run_command` and answers with the output. The Node.js
version varies:

```text
v24.22.2
```

The first tool call opens the session's sandbox, which creates the computer.

## 4. Clean up

Eve deletes the computer when it ends or deletes the session. Stopping
`eve dev` doesn't end its sessions, so the quick start's computer stays.
`nevia ls` lists it as `eve-` and a hash, and `nevia rm` deletes it:

```bash
nevia ls
nevia rm eve-<hash>
```

To sleep or keep the computer when a session ends, set `onSessionEnd` to
`'sleep'` or `'keep'` in `NeviaSandbox.environment()`.

## How the sandbox maps to a computer

`NeviaSandbox.environment()` returns an Eve sandbox environment that
`environment.open()` opens for each session, so the agent uses Eve's own file
tools. It takes `image`, `env` for environment variables stored on the
computer, `workdir`, `onSessionEnd`, `onStop` and `nevia` for client options.
`neviaComputerOf()` returns the SDK `Computer` behind a sandbox for tools you
write yourself.

The adapter names the computer after the Eve session, so a later turn finds
the same computer, files included. `image` and `env` apply only when the
adapter creates the computer. Relative paths resolve from `/workspace`, the
working directory.

`sandbox.stop()` sleeps the computer, and the next turn wakes it with its files
intact. `onStop: 'keep'` leaves it running instead. A sleeping computer's disk
still counts toward storage until the session ends with the default
`onSessionEnd: 'delete'` or you run `nevia rm`.

Commands run in the foreground. With `transport: 'direct'`, `exec()` keeps the
last 64 KiB of each output stream and sets `truncated` when it drops output.
Pass `maxOutputBytes` for another cap.

## Limitations

These add to the SDK's [Limits and workarounds](https://nevia.cloud/docs/reference/sdk/limits.md).

* **No background processes or stdin.** Eve's `spawn`, `run`, `bash`, `glob`
  and `grep` answer `not_supported`. Run commands, `find` and `grep` through
  your own command tool, as the quick start does. A `prepare` callback can't
  run commands either.
* **No network policy.** The sandbox has no `setNetworkPolicy()`, so the
  computer keeps its default network access.
* **No tool sessions.** A keyed tool call that reaches the sandbox gets Eve's
  `ToolSessionSandboxUnsupportedError`.
* **Cancelling doesn't stop the command.** Aborting a call closes the
  connection, but the command can keep running on the computer.
* **Large workspaces start slowly.** Eve writes workspace and skill files one
  call at a time at every session start.
* **The image needs `find` and `grep`.** Eve's file tools call them.
* **Every turn wakes the computer.** That includes a turn that never uses the
  sandbox.
