Skip to main content
The package keeps its old name, @asciidev/eve-box, and its function asciiBox(). Version 0.1.6 calls the old Box API, which sends a Sunset date of 31 October 2026. Without apiKey, it reads BOX_API_KEY. See Migrating from Box.
Eve is a TypeScript framework for coding agents. Eve runs each agent in a sandbox: a filesystem and a shell where the agent reads files, writes files and runs commands. Eve lets you choose where that sandbox runs. boat is a cloud sandbox: a full Linux machine that you create over an API. @asciidev/eve-box connects Eve to boat. It is an Eve sandbox backend. It sends the Eve filesystem and process operations to the boat API. Your Eve agents then run on boat sandboxes, not on your laptop.
You need only two things for this guide: Node.js 18+ and a boat API key. You do not need to know Eve or boat before you start.

How it fits together

Set it up

1

Create a boat account

Sign in at boat.dev and start a plan. See Quickstart and Free trial.
2

Get a boat API key

Create a key on the API keys tab of the dashboard, or run boat api-key create eve --preset ci. Keep it in an environment variable, never in source control.
3

Install the packages

Use a modern TypeScript config: "module": "NodeNext", "target": "ES2022", "lib": ["ES2022", "DOM"]. Set "type": "module" in package.json.
4

Define the sandbox backend

Set the Eve sandbox to use boat. In an Eve project, put this in your sandbox definition file:
sandbox.ts
The Eve agents in this project now run on boat.

A complete example

This script runs on its own. It creates a boat sandbox session and tests the operations that Eve uses: run commands, read files and write files. Use it to check your setup before you connect the backend to a larger Eve agent.
hello-sandbox.ts
The output shows the file contents, the uname output of the machine, and exit code 0.

What the backend maps

Configuration

asciiBox(options) accepts these options:

Running agents for other people

By default, a sandbox gets your boat account. This includes your secrets, secret files, repositories cloned with your GitHub credentials, and your SSH identity. This is fine for your own agents. If other people can control the agent, set noEnv: true. Then they cannot read your secrets or act as you.
With noEnv: true, the sandbox starts without your account credentials. It cannot act on your account or other sandboxes. This does not restrict network access. You then give it only what it needs:
  • Secrets: through env.
  • Files and setup: through the Eve onSession hook.
sandbox.ts
Rules for env:
  • env keys merge over your account variables. The per-sandbox value wins.
  • The limit is 100 variables and 64 KB in total.
  • boat rejects reserved boat-internal names.
The session API replaces the boat CLI inside Eve: A no-env sandbox cannot reach your private repositories. Clone public ones, or let the user sign in inside the sandbox. Read No-env sandboxes.

Reusing a prepared environment

Setup runs when boat first creates the sandbox for each session. To start many sessions from the same prepared state:
  1. Prepare one sandbox.
  2. Save it as a saved snapshot: boat snapshot <id> my-stack.
  3. Create each new sandbox from it: boat new --from my-stack, or from in the API.
A fork also copies a sandbox, but it follows the newest snapshot of its source. A saved snapshot does not change.

Network policies

boat does not enforce the fine-grained Eve network policies yet.
  • The backend accepts "allow-all".
  • For stricter policies, it throws EveSandboxUnsupportedError. This includes "deny-all", allow-lists and subnet rules.
Thus you never get isolation that is not real. If you need policies that a firewall enforces, run that Eve agent on a backend that supports them.

Resources

npm package

@asciidev/eve-box on npm.

Source on GitHub

Issues, examples and the adapter source.

boat quickstart

Install boat and create your first sandbox.

boat API keys

Create and manage the key that this adapter needs.