---
title: Operate a Self-Hosted Agent
description: Upgrade, scale, and troubleshoot an eve agent that runs on your own infrastructure.
url: "https://eve.dev/docs/guides/deployment/self-hosted-operations"
docs_index: /llms.txt
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

Use this guide after your agent runs with [`eve start`](./self-hosting). It covers upgrades, replicas, schedules, workspace members, run data, and common failures.

## Upgrade a self-hosted agent

A self-hosted Workflow world serves one eve version at a time. Deploying a new build of your agent on the same eve release keeps existing sessions running. Upgrading eve strands sessions started by the previous version: their recorded history remains readable, but they cannot resume. See [Recover a stranded session](#recover-a-stranded-session) for how a new channel message starts a replacement.

To deploy a new build:

1. Stop the processes running the previous build.
2. With the Postgres world, run `bootstrap` if the build upgrades `@workflow/world-postgres`; see [Use the Postgres world](./workflow-worlds#use-the-postgres-world).
3. Start the new build with `eve start`.

When the eve version is unchanged, the new build resumes runs that were active when the previous processes stopped.

### Recover a stranded session

A session is **stranded** when another eve version built the workflow run that owns it, so the current deployment cannot replay it. Its recorded history stays readable, but it cannot process new work. A new message to its channel address starts a replacement session whose `ctx.session.predecessor` names the stranded one.

See [Stranded sessions](../../concepts/execution-model-and-durability#stranded-sessions) for when a session is stranded in each world, how it ends, and how a replacement session can read the earlier conversation.

## Run replicas

Use the [Postgres world](./workflow-worlds#use-the-postgres-world) to serve an agent from several `eve start` processes. Every process connected to the database runs queued work, so any replica can continue any session. The local world serves one process.

Configure each replica the same way, with two differences:

- Run schedules on one replica only; see [Run schedules](#run-schedules).
- Give every replica access to the same sandboxes. A session records its sandbox, and the next replica to run the session resumes it. A Docker sandbox lives on the Docker daemon of the host that created it. A replica that can't find it starts a fresh sandbox without the earlier files if its own daemon has the build's sandbox image, and fails with `SandboxTemplateNotProvisionedError` otherwise. For replicas on several hosts, use a provider every replica can reach, such as [Vercel Sandbox](../../sandbox/vercel) or a [custom provider](../../sandbox/custom-providers).

## Run schedules

The standard `eve build && eve start` path starts Nitro’s schedule runner. If you adapt the output to a custom HTTP-only host or preset, run Nitro scheduled tasks or invoke the same work from your scheduler.

Each `eve start` process runs every authored schedule. When you run several replicas, start one normally and start the others with `eve start --no-schedules`, or set `EVE_SCHEDULES_DISABLED=1` in their environment. See [`eve start`](../../reference/cli#eve-start).

## Run workspace members

An [agent workspace](../../concepts/project-structure#several-root-agents) does not require Vercel or a frontend at runtime. Build each member from its own directory: root `eve build` produces a Vercel workspace deployment, not a group of self-hosted Node servers.

For a workspace containing `support` and `research`, run these from the workspace root, outside a Vercel build environment:

```bash
(cd agents/support && npx eve build)
(cd agents/research && npx eve build)
```

Start each built agent in a separate terminal, or configure these commands in your process manager:

```bash
(cd agents/support && npx eve start --host 127.0.0.1 --port 3001)
(cd agents/research && npx eve start --host 127.0.0.1 --port 3002)
```

For example, this Caddy configuration gives each agent its own origin and forwards both `/eve/` and `/.well-known/workflow/` without changing their paths. Point the example hostnames at your server and run Caddy on the same machine:

```text
support.example.com {
    reverse_proxy 127.0.0.1:3001
}

research.example.com {
    reverse_proxy 127.0.0.1:3002
}
```

Apply the [authentication, Workflow world, and sandbox configuration](./self-hosting) to each member. With the default local Workflow world, persist each member's own `.eve/.workflow-data` directory. If agents delegate to one another, configure an explicit [workspace-peer transport](../../subagents#vercel-workspace-peers) with the peer's URL and credentials; the default transport requires Vercel. Ensure callback URLs are reachable from the services that call them. Remote agent callbacks must reach a public address: outside `eve dev`, eve refuses callback hosts that are loopback, private, link-local, or reserved addresses, or that resolve to one. Callbacks between services over a private network or `127.0.0.1` don't work. See [How remote dispatch and callbacks work](../remote-agents#how-remote-dispatch-and-callbacks-work) and [Set the public callback origin](./self-hosting#set-the-public-callback-origin).

### Add a peer frontend

A frontend under `apps/web/` is another service managed by your host, not by `eve start`. Build and start it using its framework commands. A browser client can use `useEveAgent({ baseUrl: "https://support.example.com" })`; configure [CORS](../../channels/eve#cors) and browser credentials for that deployment. Alternatively, mount each agent on the frontend's origin through your reverse proxy.

For path-based mounts, strip the public prefix before forwarding requests to the agent and set `EVE_PUBLIC_ROUTE_PREFIX` in that agent's build and runtime environments. Forward its workflow callback routes as well as its eve routes. Keep the browser client, callback URLs, and peer transports consistent with the public mounts.

You can instead use [`eve/next`](../frontend/nextjs#self-host) if you want Next.js to start built agent processes and provide the browser-facing proxy routes. That integration is optional; `eve/vercel` configuration is not used by a self-hosted process manager.

## Manage run data

The Workflow world holds every session's history. Back it up with the rest of your application data:

- **Local world:** back up the `.eve/.workflow-data` directory.
- **Postgres world:** back up the database. The Postgres world keeps the records of finished runs until you delete them.

eve can ask the world to delete a run's inputs, outputs, and stream contents when the run ends. See [Run data retention](../../agent-config#run-data-retention) for the default policy and the override.

## Troubleshoot a self-hosted agent

| Symptom                                                                         | Check                                                                                                                                | Next action                                                                                                                  |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| Sandbox tools fail with `DefaultSandbox has no sandbox provider for this build` | Whether `eve build` could reach a Docker daemon, for example inside a Dockerfile `RUN` step                                          | Rebuild where Docker is reachable, or [select a provider explicitly](./self-hosting#build-inside-a-container-image)          |
| Workflow deliveries fail with HTTP 401 with the local world                     | Whether `WORKFLOW_LOCAL_BASE_URL` reaches a load balancer in front of several processes                                              | Serve the agent from one process, or use the [Postgres world](./workflow-worlds#use-the-postgres-world) for replicas         |
| Sign-in links or remote agent callbacks point at `localhost`                    | Whether `WORKFLOW_LOCAL_BASE_URL` is set                                                                                             | [Set the public callback origin](./self-hosting#set-the-public-callback-origin)                                              |
| A session starts but never responds behind a proxy                              | With `WORKFLOW_LOCAL_BASE_URL` pointing at the proxy, whether the proxy forwards `/.well-known/workflow/` without rewriting the path | Forward both [proxy route prefixes](./self-hosting#configure-proxy-routes)                                                   |
| Requests return `409` with `code: "session_stranded"` after an upgrade          | The eve version in the response                                                                                                      | End the session, or send a new message to its channel address; see [Recover a stranded session](#recover-a-stranded-session) |
| Schedules run more than once                                                    | How many replicas run without `--no-schedules`                                                                                       | [Run schedules](#run-schedules) on one replica                                                                               |

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)