Agent frameworks

Eve

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

The Eve adapter gives an Eve 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 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 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 shows how to install it.
  • A Nevia key file for a service account with the editor role. Use an automation key file shows how a workspace admin issues one.

Install the adapter

Invited testers only

The SDKs are in early access for invited testers. To ask for access, see Request access to Nevia.

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

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 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 through NODE_OPTIONS="--import tsx".

Authenticate

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

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.

Give an agent a computer

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

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

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

Create agent/instructions.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:

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:

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:

import { disableTool } from 'eve/tools'

export default disableTool()

Start the agent in one terminal:

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

Ask it from a second terminal:

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:

v24.22.2

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

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:

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.

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

On this page