Deploy

Run egin in a container, and put it behind a web app on Vercel or a Cloudflare Worker.

An agent’s sessions run for minutes and keep their state on disk, so egin serve needs a long-lived process and a volume. Serverless functions have neither. Deploy in two parts:

  • The agent runs as a container on any host that keeps a process up and mounts a volume: Fly.io, Railway, Render, a VM.
  • Your app runs on Vercel or Cloudflare and forwards the browser’s calls to the agent, adding its token on the server.

The agent, in a container

The repository’s Dockerfile builds egin and serves the folder mounted at /agent:

docker build -t egin .
docker run -p 8787:8787 -v "$PWD/my-agent:/agent" \
  -e EGIN_TOKEN=... -e YDC_API_KEY=... egin
  • EGIN_TOKEN is required. The image listens on 0.0.0.0, so without a token egin exits at start. With it, every route except /health and the channels answers 401 to a request without the token.
  • Put /agent on a persistent volume. Sessions, uploads and memory live in that folder, and a session interrupted by a redeploy resumes from it.
  • A container has no KVM, so microVMs are out. Set sandbox in agent.toml to a cloud sandbox (e2b, vercel, daytona), or to local to run tools inside the container itself. Left at auto, it falls back to local with a warning. secrets need a microVM, so an agent that uses them won’t start in a container.
  • Point the host’s health check at GET /health. The server listens on $PORT when the host sets one.

Check it before wiring up an app:

curl -H "Authorization: Bearer $EGIN_TOKEN" https://agent.example.com/agent

Vercel

A Next.js app made with --template web, or set up as in Frontends, deploys as is. Set two environment variables in the Vercel project:

Variable Value
EGIN_URL The container’s URL, such as https://agent.example.com
EGIN_TOKEN The token the container was started with

With EGIN_URL set, withEgin starts no local server, and the /egin/* route handler forwards each call to the container with the token. The browser only ever talks to your app. The agent/ folder in the app is not used on Vercel: deploy the same folder to the container.

Cloudflare Workers

createProxy takes a web Request and returns a Response, so it runs in a Worker as it is:

// src/index.ts
import { createProxy } from "egin/proxy";

export default {
  fetch(request: Request, env: { EGIN_URL: string; EGIN_TOKEN: string }) {
    if (!new URL(request.url).pathname.startsWith("/egin/")) return new Response("Not found", { status: 404 });
    return createProxy({ target: env.EGIN_URL, token: env.EGIN_TOKEN, prefix: "/egin" })(request);
  },
};
// wrangler.jsonc
{
  "name": "my-agent-proxy",
  "main": "src/index.ts",
  "compatibility_date": "2026-11-01",
  "vars": { "EGIN_URL": "https://agent.example.com" }
}
npx wrangler secret put EGIN_TOKEN
npx wrangler deploy

Event streams pass through the Worker unbuffered. Serve your frontend from the same Worker, or from Pages on the same domain, and call useAgent({ baseUrl: "/egin" }).

Many users

When people sign in to your app, pass user to createProxy so each one reaches only their own sessions. See One app, many users.