Connect Vercel Daemons to eve agents so background workers can start agent sessions for jobs and agents can send work back to workers.
The daemon handles queue polling, open connections, and compute-heavy jobs. eve manages durable sessions that preserve the agent's state between turns, including while a worker prepares a result. These examples run both in one Vercel project and authenticate with the project's OpenID Connect (OIDC) identity.
Copy link to headingHow do you run eve agents with Vercel Daemons?
Run the daemon in the same Vercel project as your eve agent. For queue-based triage, the daemon pulls a job and starts an eve session with POST /eve/v1/session. It reads the stream until turn.settled, then acknowledges a successful job or records a failed turn for review.
In the other direction, an eve tool publishes a job to Vercel Queues. The session waits without holding compute until the daemon sends the result back through eve's session API. Both directions authenticate with the project's Vercel OIDC token.
Copy link to headingWhen should an agent use a daemon?
Use a Vercel Daemon when the work requires a process to stay running, such as a queue consumer, held-open connection, or CPU-heavy job.
eve and Vercel have a better fit for other triggers:
| Workload | Use | Why |
|---|---|---|
| The agent runs on a fixed cadence, whatever the data says | eve schedules | Each cron fire starts a session, with no worker to maintain |
| The agent reacts to messages that Vercel delivers to a function | Vercel Queues in push mode | Vercel invokes and scales the consumer for you |
| The agent reacts to an external queue such as Amazon SQS, Kafka, or BullMQ, or you need to control how quickly workers take jobs | Vercel Daemons | The daemon pulls at the pace you set |
The agent needs events from a source without webhooks, such as IMAP, MQTT, or Postgres LISTEN | Vercel Daemons | Only a running process can hold the connection open |
| The tool needs system binaries, more CPU, or minutes of compute | Vercel Daemons | The work runs in your container while the session waits |
| The tool needs durable timers, waits, or retries in your own code | eve workflow tools on Vercel Workflows | defineWorkflowTool suspends without holding compute |
| The tool runs model-chosen commands or untrusted code | The eve sandbox on Vercel Sandbox | The sandbox isolates code from your app's credentials |
| The agent answers HTTP requests or webhooks | eve channels on Vercel Functions | The request itself starts the session |
Copy link to headingPrerequisites
You'll need a Vercel account. The rendering example also requires a Pro or Enterprise plan for its 4 GiB instances.
For local development, install Node.js 24 or later, Docker, and the Vercel CLI.
Deploy your eve agent to production and set the project's root directory to the repository root. During beta, daemons don't support subfolder roots or non-production environments.
Configure your agent's instructions and tools for the use case you choose. The ticket triage, fraud review, and monitoring examples assume working integrations with your helpdesk, order database, or logging and incident systems.
Copy link to headingHow do daemons and eve agents talk to each other?
Daemons call an eve agent through the agent's HTTP session routes, and eve agents reach daemons through a queue, because daemons don't accept inbound traffic.
The daemon uses four of eve's session routes:
| Route | What the daemon uses it for |
|---|---|
POST /eve/v1/session | Start a session with the job as its first message. Pass operationId to deduplicate creation. Once the session is active, retries return that session without sending the message again. |
GET /eve/v1/session/:sessionId/stream | Read newline-delimited JSON (NDJSON) events until turn.settled reports the turn's outcome |
POST /eve/v1/session/:sessionId | Send a result to the session. With the queue policy configured below, the message waits for any running turn to finish. Pass idempotencyKey so a retried send is accepted once. |
POST /eve/v1/session/:sessionId/end | Retire a one-shot session after you've saved its result |
The eve channel reference documents every field these routes accept.
Copy link to headingHow daemons authenticate to an eve agent
Each daemon instance receives a Vercel OIDC token for its project, which Vercel writes to the file in VERCEL_OIDC_TOKEN_FILE and refreshes periodically. eve's vercelOidc() verifier always accepts tokens minted for the agent's own project, so a daemon in the same project needs no extra auth configuration.
Keep vercelOidc() in your eve channel's auth list:
turnPolicy: 'queue' makes follow-up messages wait for a running turn to finish. This lets a render result start the next turn even if it arrives before the agent finishes its initial reply.
The daemon needs @vercel/oidc 4.0 or later to read its token file. Send the token as a bearer token to the agent's production URL, as eve's Discord relay daemon does.
To call an agent in another Vercel project, set EVE_URL in the worker project's production environment to the agent's production URL, including https://.
On the agent, admit the worker project with subjects:
Requests that no entry accepts receive a 401 response.
Copy link to headingHow do you set up a shared worker image?
Package all worker code in one container image, then run each use case as its own daemon by setting the daemon's command field. Every daemon shares the same eve client code and dependencies, and you scale each one separately.
Add a worker/ directory next to your agent:
Node.js 24 runs TypeScript files directly by stripping their types, so the worker needs no build step. Import local files with their .ts extension, and avoid TypeScript features that need compilation, such as enums.
Copy link to heading1. Install the worker dependencies
Enable top-level await in worker/package.json:
The override makes the Queues SDK use the same OIDC helper as the worker, so queue requests can read the daemon's refreshed token file.
From worker/, install the dependencies. Keep this directory on npm so its generated package-lock.json matches the Dockerfile's npm ci command:
Return to the repository root before continuing. If you already installed the worker dependencies without the override, regenerate its lockfile and reinstall so no older nested OIDC helper remains.
Copy link to heading2. Add the Dockerfile
This image installs ffmpeg for the rendering use case. If you only need the other use cases, remove the apt-get lines to keep the image smaller:
Copy link to heading3. Add the eve client helpers
worker/lib/eve.ts wraps the four session routes. waitForFirstTurn reads the stream from line 0, so a redelivered job also finds a turn that finished before the daemon restarted:
The eve stream protocol defines the event lines, progress records, and transport records that readLines parses. If you'd rather not handle the stream yourself, the typed eve/client SDK wraps the same routes.
Copy link to heading4. Add the shutdown helper
Vercel sends SIGTERM before it stops or replaces a daemon instance. worker/lib/shutdown.ts turns that signal into an AbortSignal that every loop checks:
Copy link to heading5. Share queues across deployments
By default, Vercel Queues pins each message to the deployment that published it. Tools in an older eve session can therefore publish to a partition that a newer daemon never reads.
Set deploymentId: null on every queue client in these examples so the agent and all daemon versions share the queue. Both sides must also use the same fixed region because messages can only be received in the region where they were sent.
Because every deployment now reads the same messages, keep message payloads backward compatible, or add a version field and handle each version in the daemon.
Copy link to headingUse cases
Choose a use case and add its script to worker/. Merge the corresponding entry into the existing daemons configuration in vercel.json, then deploy to production. Vercel builds the same worker source separately for each configured daemon and runs its configured command.
Copy link to headingHow do you run an agent for every message in a queue?
Your support app publishes each new ticket to a queue. The daemon starts an eve session to read and label the ticket and draft a reply through the agent's tools, then acknowledges the message after a successful turn.
Your app publishes tickets from wherever they arrive, such as a helpdesk webhook. The idempotencyKey drops a duplicate publish of the same ticket:
The triage daemon runs four consumer loops per instance. When a session request or stream fails, the handler throws so redelivery can reconnect to the same attempt. Failed or cancelled turns go to a separate topic before the original message is acknowledged:
The failure topic keeps each failed or cancelled result for seven days. Before deploying triage, connect a consumer that saves those records for operator review. The collector below writes them to Postgres before acknowledging them, so they remain available after queue retention expires.
Apply this migration to the database the collector uses:
Save this as worker/collect-triage-failures.ts. It uses the worker dependencies installed earlier:
Run the collector from an authenticated worker environment at least daily, with DATABASE_URL set and the same TICKETS_TOPIC as triage. It drains the currently available failures and exits. Include it in your existing operations scheduler before enabling the triage daemon, and alert on collector failures.
Review the triage_failures table to diagnose failed tickets. After fixing the cause, republish the stored ticket with a new publish idempotency key for that deliberate attempt. Reuse that key if the publish itself needs retrying, and keep tool side effects deduplicated by ticket ID across attempts.
Declare the daemon in vercel.json. The triage worker spends most of its time waiting on HTTP, so 1 GiB of memory is enough:
Copy link to headingHow does an agent hand heavy work to a daemon?
An agent can enqueue a video edit and finish its turn while a daemon runs FFmpeg. The renderer looks up an upload registered to that session and posts the finished clip's URL back to start the next turn.
Copy link to headingPrepare uploads and storage
This example turns private source videos into public clips. Create a private Vercel Blob store for uploads and a separate public store for clips.
Set SOURCE_BLOB_READ_WRITE_TOKEN and CLIPS_BLOB_READ_WRITE_TOKEN to their respective store tokens in the project's production environment, and set DATABASE_URL to your Postgres connection string.
Create these tables in that database:
Your app's authenticated upload route must verify that the signed-in user owns the eve session and has agreed to publish clips from the video.
Generate the video ID on the server, upload the MP4 to uploads/${videoId}.mp4 with access: 'private', addRandomSuffix: false, and allowOverwrite: false, then insert its pathname and the verified session ID into video_uploads with public_clips_allowed = true. Give the resulting video ID to that session.
Registration belongs to your existing app's upload flow. The agent cannot create or edit these rows. Keep source uploads unchanged while jobs can use them, and retain result rows for as long as your app can replay a job ID.
Copy link to heading1. Add a tool that publishes the job
Install the Queues SDK in the agent's project:
pnpm i @vercel/queuenpm i @vercel/queueyarn add @vercel/queuebun add @vercel/queueThe tool reads eve's runtime session ID so the worker can verify upload access. Queues uses the combined session and call IDs to deduplicate publish requests within the message's retention window, up to 24 hours:
Copy link to heading2. Tell the agent how results arrive
The daemon's result reaches the agent as a new message in the same session. Add instructions so the agent recognizes it:
Copy link to heading3. Write the renderer daemon
worker/lib/render-clip.ts downloads the private Blob to a temporary file and runs FFmpeg against that file. It accepts MP4 sources up to 250 MiB and clip ranges up to 300 seconds, rejects outputs of 100 MiB or more, and sets an eight-minute deadline for downloading, encoding, and uploading.
These are application limits chosen for this example:
Create worker/render.ts to look up the upload by video ID and session ID. It saves an outcome before sending the callback, which has a separate 30-second deadline. Once an outcome is saved, later deliveries resend it without rendering again.
If rendering fails on the third or a later delivery, the worker saves a failure message. Delivery counts can include interrupted handlers, so they do not measure completed rendering attempts. Temporary files are removed on success and failure:
On SIGTERM, the renderer stops accepting new jobs and lets its current handler continue. Vercel can force-stop it when the grace period expires. If it stops before saving an outcome, a later delivery may render again; the deterministic Blob path replaces that job's earlier upload. The same callback idempotency key prevents duplicate result messages while eve retains that key.
Copy link to heading4. Configure the renderer
The renderer requires a Pro or Enterprise plan. Request 4 GiB of memory for 2 vCPUs per instance, and set a 600-second shutdown grace period to give the current handler time to finish during a deploy:
Copy link to headingHow the rendered clip reaches the user
- The app registers an MP4 upload for the session after its owner approves public clips.
- The user asks the agent to cut a clip from 65s to 100s. The model calls
render_clipwith the video ID, and the tool queues a job with the session ID. - The agent tells the user the clip is rendering and finishes its turn.
- The renderer checks the upload record, downloads the private source, runs FFmpeg, and uploads the public clip. It saves the outcome in Postgres.
- The daemon posts
Render finished ...to the session, starting a turn in which the agent shares the clip URL. handleJobreturns, and the SDK acknowledges the queue message. If the callback fails, a later delivery reads the saved outcome and retries the callback.
Copy link to headingHow do you forward events from a source without webhooks?
Some sources only push events over a long-lived connection, such as IMAP IDLE for email, MQTT for devices, or Postgres LISTEN. The daemon holds that connection open and starts an agent session for each event. In this example, a Postgres trigger fires when an order is flagged for fraud review, and the agent reviews the order.
This example assumes an orders table with id, flagged_at, and reviewed_at. Set DATABASE_URL_UNPOOLED to a direct Postgres connection and configure the agent's tools to review an order and set reviewed_at when finished.
Add a trigger that sends the order ID on the order_flagged channel:
Postgres doesn't store notifications for disconnected listeners, so the daemon scans unreviewed orders each time it starts. If handing off a live notification fails, the listener exits so Vercel restarts it and reruns the scan.
The agent's tool sets reviewed_at when the review finishes, while operationId deduplicates overlapping handoffs for that order:
LISTEN needs a direct database connection, because transaction-mode connection poolers don't deliver notifications.
Run one instance, since every listener receives every notification:
During a deploy, old and new listeners can receive the same order notification. Use the same operationId to deduplicate their create requests and handle startup retries as described in the idempotency section.
Copy link to headingHow do you run an agent across thousands of records?
To rewrite the descriptions of 12,000 products in a consistent voice, the backfill daemon claims one product at a time. It runs an agent session for that product and saves the reply before claiming the next one.
With four loops and an average of 15 seconds per turn, the catalog would take about 12.5 hours before retries and other overhead. The loops control how quickly this worker takes products; they do not enforce a global session limit across restarts and deployments.
Set DATABASE_URL to a connection that can read and update products.
The example assumes a products table with id, name, and description. Apply this migration before running the backfill. If the two timestamp columns already exist from an earlier version of the example, omit those two additions:
The claim query excludes completed and failed products, and reclaims work after 30 minutes if a worker stopped before recording a result. Transport recovery keeps the same stored attempt number and operationId, so it can follow the existing session. The worker records failed or cancelled turns and empty completed replies for review instead of reclaiming those products:
The script saves the description or failure in Postgres before requesting session cleanup. If cleanup fails, the saved result still excludes that product from automatic claims, and rewrite_session_id identifies the session for inspection. Sessions that remain open expire under eve's configured idle timeout, which defaults to 30 days.
Inspect failures with:
After resolving a failure, run this parameterized query with the product ID as $1 to schedule another attempt:
The query increments the stored attempt before clearing the failure. Its new operationId starts fresh even if the previous session's end request failed or the worker stopped before cleanup.
Clearing only the failure fields would reuse the old attempt and read its failed turn again. Record the previous session ID if you need to retry its cleanup.
The script idles whenever no products are eligible for claiming, because Vercel restarts an instance when its process exits. Inspect failed products and any outstanding claims before deciding the backfill is complete. Once all products have been updated, scale the backfill daemon to zero.
Copy link to headingHow do you start an agent only when a metric looks wrong?
The monitoring daemon checks a metrics endpoint and waits 15 seconds between checks. It starts an investigating agent only when the checkout error rate crosses a threshold outside the cooldown period. The agent uses its tools to read logs and post findings for the on-call engineer.
Set METRICS_URL to your metrics endpoint and METRICS_TOKEN to its bearer token. The endpoint must return JSON with an errorRate between 0 and 1 and a windowStart string that identifies the measurement window.
The cooldown starts after session creation succeeds, so a failed request is retried on the next poll. It lives in memory and resets when the instance restarts. The metrics window also forms the operationId, which deduplicates retries for that window while its session remains resumable.
eve schedules have minute granularity. This daemon waits 15 seconds between checks and starts an agent only when the threshold is crossed. If checking once a minute is enough, an eve schedule with a run handler can check the metric before sending to the agent.
Copy link to headingHow do you avoid duplicate agent runs?
Vercel Queues delivers messages at least once, and eve's crash recovery doesn't make external effects exactly once. Give each boundary its own idempotency key. The triage handler returns after a successful first turn or a saved failure record; the renderer returns after delivering its saved outcome or logging that the session is no longer active.
| Boundary | Key | What it prevents |
|---|---|---|
| Publishing a job | send(topic, payload, { idempotencyKey }) | Drops duplicate publishes within min(retention, 24 hours) |
| Starting a session | operationId on POST /eve/v1/session | Deduplicates creation. Once the session is active, retries return it without sending the message again. |
| Sending a result | idempotencyKey on POST /eve/v1/session/:sessionId | Accepts a message once per key. Each session remembers its last 1,024 keys. |
| Tool side effects | Stable key passed to the upstream API | Prevents duplicate effects when the upstream API enforces the key |
operationId follows three rules:
- The caller must authenticate. Anonymous callers can't use
operationId. Every daemon instance in the project presents the same OIDC identity, so a redelivery to a different instance still matches. - It works on creation only. Follow-up requests reject
operationIdwith400 Bad Request, so useidempotencyKeythere. - It frees up when the session can't resume. After a session ends or times out, the same
operationIdstarts a new session. Only end sessions early, as the backfill does, after your own data records the outcome and controls whether another attempt can start.
Concurrent create requests can return different session IDs during startup, but only one session runs the first turn. Retry the create request with the same operationId after startup to retrieve that session. The queue worker retries through redelivery if following a provisional session fails.
eve recovers an interrupted step by running it again, and a tool call that started before the interruption may already have taken effect.
Pass a stable key to any upstream API that changes data:
Using the call ID as the key protects against a retried step. When the effect must happen once per job, such as one reply per ticket, key on the job instead and check whether it already happened. The eve tools reference covers these options.
Copy link to headingHow do you control concurrency and cost?
Two triage instances with four loops each normally wait on up to eight first turns at a time. Vercel doesn't autoscale daemons, so queued work waits when those loops are occupied. Active sessions can exceed eight during a rollout or after a worker loses its connection because sessions continue independently of the worker.
Adjust throughput by changing the worker's loop count or the instances configuration in vercel.json. You can also scale instances from the dashboard without a deploy.
Strict limits across deployments need shared permits that remain assigned until the corresponding sessions settle. Apply model and API rate limits separately, and configure per-session usage limits to control model spend.
Costs come from two sides:
- Daemon side: Time an instance spends waiting on a stream or a queue doesn't count as Active CPU, but Provisioned Memory counts every hour an instance runs. Choose
"1Gi"for workers that mostly wait on HTTP, and reserve"4Gi"or"8Gi"for CPU-heavy work like rendering. - Agent side: eve sessions use the billing of the resources they consume, including Vercel Functions, Vercel Workflows, AI Gateway, and Vercel Sandbox when tools use it.
The Hobby plan gives daemons across all of a team's projects 5 Active CPU-hours and 420 GB-hours of Provisioned Memory per month. One 1 GiB instance that runs without stopping uses that memory quota in about 18 days, and Vercel stops all of the team's daemons when either quota runs out.
Use Hobby to try the 1 GiB workers and the Pro plan for workers that need to run all month. The 4 GiB renderer requires Pro or Enterprise.
On Pro, configure Spend Management with Pause Production Deployments to stop the project's daemons when the budget action triggers. Checks can lag by several minutes. Set model budgets separately because pausing the project does not stop AI Gateway API-key usage or direct provider charges.
Copy link to headingWhat happens on deploy or shutdown?
Deployments replace daemon instances, but eve sessions keep running on Vercel Workflows, independent of any daemon connection. Design each daemon so stopping it at any point leaves its work recoverable.
Copy link to headingThe daemon stops in the middle of a turn
When Vercel sends SIGTERM, the triage daemon aborts waitForFirstTurn and throws, so it doesn't acknowledge the message. The agent's turn keeps running.
After the message's visibility timeout expires, another instance receives it and calls POST /eve/v1/session with the same operationId. Once startup has resolved, the request returns the existing session. Reading its stream from line 0 recovers the first turn's result, including one that settled before the worker reconnected.
The renderer stops taking new jobs on SIGTERM and has up to 600 seconds to finish its current handler. If Vercel stops it before the handler returns, the queue can redeliver the message.
The worker reads a saved outcome before attempting another render. If it stopped before saving that outcome, it may render again and replace the upload at the same Blob path. Retrying the callback uses the same idempotencyKey.
Copy link to headingOld and new daemon versions overlap
Instances from the previous deployment keep processing during their shutdown grace period while new instances start. With deploymentId: null, both versions read the same queue and must accept the same message format. Add new payload fields as optional and retain old fields until every publisher uses the updated format.
Copy link to headingSessions move between agent deployments
Sessions with a running turn, pending input, or active tasks stay on their current deployment. In the rendering example, the turn ends after the tool queues the job. When the result arrives, it can move that idle session to the current deployment, where the next turn uses the new system instructions, model, and tools.
If the new deployment cannot read the session's checkpoint, the session stays on the previous deployment and processes the result there. Keep tools that older sessions may call, such as render_clip, compatible across deploys.
Sessions don't become stranded on Vercel, because each run executes on the deployment that started it. Stranding happens in local development and self-hosted setups when the eve version changes.
Copy link to headingHow do you test locally?
Run the agent with eve dev and the worker scripts with Node.js on the same machine. Daemons run only in production during the beta, and vercel dev doesn't start them.
Copy link to heading1. Start the agent
Pull the project's development environment variables, including a Vercel OIDC token, then start the eve development server:
The server listens on http://localhost:2000. localDev() in the channel's auth list accepts requests from the same machine.
Copy link to heading2. Run a worker against it
Point the worker at the local agent with EVE_URL. Use a separate topic so the local worker doesn't take messages from the production daemon:
Copy link to heading3. Publish a test job
Save the following code as worker/send-test-ticket.ts to publish a ticket to the development topic:
From another terminal at the repository root, run the test publisher:
The worker logs a line like this after the agent completes the first turn successfully:
Copy link to heading4. Test the image and shutdown handling
Build the image and run it with Docker to check the Dockerfile and SIGTERM handling. Copy the values the worker needs into .env.docker as unquoted KEY=value lines, and keep the file out of version control. With --network host, the container reaches eve dev on localhost. Docker Desktop on macOS and Windows supports host networking only when you turn it on in its settings.
Run docker stop --timeout 30 triage from another terminal. Docker sends SIGTERM and waits up to 30 seconds before force-stopping the container, matching Vercel's default grace period.
Copy link to headingTroubleshooting
Copy link to headingSession routes return 401
The eve channel rejected the daemon's token. Check that the daemon sends Authorization: Bearer <token> with a token from @vercel/oidc 4.0 or later, since earlier versions can't read the token file daemons receive.
For workers in another project, add the worker project to vercelOidc({ subjects }) and set EVE_URL to the agent's production origin. The helper's default URL belongs to the project running the daemon.
If the production domain uses Deployment Protection, the protection layer can reject the request before eve sees it.
Copy link to headingFollow-up requests return 409 session_not_ready
The session was accepted, but its inbox isn't ready for input yet. This happens when a message follows session creation closely. Retry with bounded backoff, as sendToSession does. eve's TypeScript client retries this code for up to 20s.
Copy link to headingFollow-up requests return 409 session_not_active
The session ended or hit its idle timeout, which is 30 days by default, so no one is waiting for the result. Acknowledge the job and log it, or start a new session if the result still needs an agent. Change the timeout with limits.sessionTimeoutMs in agent/agent.ts.
Copy link to headingRequests return 409 session_stranded during local development
After an eve upgrade, eve dev can encounter a session built with a different version. Stranded sessions can't run, so end the session and create a new one. On Vercel, each run keeps executing on the deployment that started it, so production sessions don't strand.
Copy link to headingThe create request returns 400 for operationId
operationId is accepted only on POST /eve/v1/session. Follow-up requests reject unknown fields with 400 Bad Request, so use idempotencyKey on POST /eve/v1/session/:sessionId.
Copy link to headingThe daemon never receives messages the agent publishes
Check that both sides create their queue clients with deploymentId: null and the same region. With the default pinning, a tool running in an older deployment's session publishes to a partition the current daemon doesn't read. Also confirm both sides use the same topic name.
Copy link to headingThe daemon keeps restarting
Vercel restarts any instance whose process exits, so a script that returns when its work runs out restarts in a loop. Keep the process alive with an idle wait, as the backfill does. Other common causes include an unhandled promise rejection, a missing environment variable such as DATABASE_URL, and a Dockerfile that skips npm ci. Filter your project's Logs by the source daemon and the daemon's name to see the exit reason.
Copy link to headingNext steps
- Configure, scale, and stop daemons with the Vercel Daemons guide.
- Deploy and authenticate your agent with eve on Vercel.
- Look up every session route and field in the eve channel reference.
- Learn how sessions checkpoint, wait, and recover in eve's execution model.
- Consume queues from a daemon with Vercel Queues poll mode.
- Add durable waits to your own tools with Vercel Workflows and eve workflow tools.