Self-host Eve: setup, costs, and tradeoffs
Self-hosting Eve moves the Nitro agent service and your chosen sandbox backend onto infrastructure you operate. Model tokens, many workflow storage options, and third-party tools still bill externally. A local Docker demo is not equivalent to a hardened multi-tenant service.
Next action: Pin eve@0.52.5, pick a backend, then follow the single-tenant recipe below. Estimate costs before committing operator time.
Upstream:
Build with eve build, serve with eve start, persist .eve/.workflow-data, proxy /eve/ and /.well-known/workflow/.
Last verified: 2026-09-10. See docs/eve-sources.md in this repository.
What moves vs what stays
| Component | Self-hosted | Still external |
|---|---|---|
| Sandbox command execution | Your Docker / microsandbox / VM pool | Vercel Sandbox if you keep vercel() backend |
| Agent HTTP routes | Your Node process + reverse proxy | — |
| Workflow state | Local .eve/.workflow-data or custom world | Managed Workflow world if you keep Vercel |
| Models | Your AI Gateway key or provider keys | Provider invoices |
| TLS, auth, scaling | Your platform | — |
Sandbox backends are not interchangeable
| Backend | Isolation | Real binaries | Network policy | Fit |
|---|---|---|---|---|
| Docker | Container | Yes (image-bound) | allow-all / deny-all only | Single-tenant servers with Docker socket secured |
| microsandbox | Lightweight VM (KVM / Apple Silicon) | Yes | Domain allow-lists + credential brokering | Closest to hosted Vercel Sandbox locally |
| just-bash | Simulated shell | No (git, node, etc. missing) | None | Demos and unit-style tests only |
| vercel() on self-host | Hosted microVM | Yes | Full Vercel features | Hybrid — still pays Vercel Sandbox |
Do not present a just-bash demo as proof of production agent security.
Deployment modes
| Mode | Audience | Notes |
|---|---|---|
| Local demo | Developer laptop | defaultBackend() or Docker; no TLS |
| Single-tenant deployment | One team / product | One Eve service, auth on /eve/, secrets on host |
| Public multi-tenant | Untrusted users | Requires strong isolation, quota, audit — not covered by a basic Docker compose file |
Single-tenant recipe (eve@0.52.5)
1. Build and run
pnpm add eve@0.52.5
eve build
PORT=3000 eve start --host 0.0.0.0Output lives in .output/. Run under systemd, Kubernetes, or a container entrypoint you already use.
2. Persist workflow state
Mount persistent volume at .eve/.workflow-data (default local Workflow world). For custom worlds, install a package compatible with Workflow SDK 5.0.0-beta per Eve docs.
3. Select sandbox backend
// agent/sandbox.ts
import { defineSandbox } from "eve/sandbox";
import { docker } from "eve/sandbox/docker";
export default defineSandbox({
backend: docker({ networkPolicy: "deny-all" }),
async onSession({ use }) {
await use({ networkPolicy: "deny-all" });
},
});Use microsandbox() on supported hosts when you need domain-level egress rules. Do not select vercel() unless you intentionally keep paying for hosted sandboxes from your own server.
4. Proxy routes
Forward both prefixes without rewriting paths:
/eve/— health, sessions, streams, tools, subagents/.well-known/workflow/— workflow callbacks
A proxy limited to /eve/ lets sessions start then stall when callbacks cannot reach the server.
5. Authentication and models
Configure route auth (Basic, JWT, OIDC) — do not rely on vercelOidc() alone off-Vercel. Set AI_GATEWAY_API_KEY or install provider SDK packages for models.
6. Verify
curl https://your-agent.example.com/eve/v1/health
eve dev https://your-agent.example.comOperational responsibilities
- Patch Node and sandbox images; pin
ghcr.io/vercel/evetags to Eve releases - Backup
.eve/.workflow-dataand any Docker volumes holding/workspace - Set concurrency and retention limits — abandoned sandboxes consume disk and CPU
- Keep management sockets and host secrets out of sandbox workloads
- On shutdown, Eve stops open sandboxes (
SIGTERM/SIGINT) and reattaches on restart
When staying managed makes sense
- Episodic traffic with low operator capacity
- You need Vercel Sandbox network brokering without building it
- Sandbox spend is already small after optimization
- Compliance requires Vercel’s hosted boundary
Cost comparison
Use the cost calculator with operator hours and peak concurrency. Self-hosting wins only when capacity, reliability, and run cost beat optimized managed execution — not when sandbox list price alone looks lower.
Register pilot interest
We are validating demand for a supported self-hosted Eve pilot — not offering hosting today.
Register interest in a self-hosted Eve pilot
Demand validation only — not an available hosting service or promised launch date. We do not collect provider keys or private logs.
Reproducible experiment
Tokenminning maintains a separate harness under experiments/eve/ in this repository (not the site runtime). See experiments/eve/FEASIBILITY.md for tested vs not-run benchmarks. The comparison page /agents/eve/vercel-vs-self-hosted ships only when comparable measurements exist.