# Run Durable Eve Agents on Kubernetes with Platformatic

[Eve](https://vercel.com/eve) organizes AI agents in a simple way: use Markdown for instructions and skills, TypeScript for tools, and separate files for channels, schedules, and subagents. Behind this setup, Eve relies on the open-source [Workflow SDK](https://workflow-sdk.dev/) to keep every session durable. This means an agent can call a tool, wait for user input, survive restarts, and pick up right where it left off.

Eve runs smoothly on Vercel, which handles the workflow runtime, queues, storage, and sandbox setup for you. This is the easiest option if you already use Vercel for deployment. If you are not on Vercel, Eve uses the Workflow SDK’s Local World by default. Local World saves state on your local filesystem and processes steps one at a time. This works well for development, but it does not offer shared state, distributed queues, or deployment-version routing needed for production environments.

Teams running applications in their own Kubernetes clusters need a production path that keeps Eve’s programming model while running its application and durable workflow infrastructure in the environment they already operate.

You now have two options for running Eve with Platformatic. For standalone agents, the new [@platformatic/eve](https://github.com/platformatic/eve) capability lets you build and run Eve as a Watt application. If your agent is part of a Next.js app, `@platformatic/next` runs the Next.js application, and Eve connects directly using its `withEve()` adapter. Both setups can use @platformatic/world to connect to a self-hosted Workflow Service. On Kubernetes, [Platformatic ICC](https://icc.platformatic.dev/) adds features like application lifecycle management, scaling, and workflow-aware [Skew Protection.](https://icc.platformatic.dev/skew-protection/) Existing runs stay on the version they started with, while new runs use the latest deployment.

You still write your Eve agent the same way. Only the deployment target changes, not the agent model.

* * *

## **What an Eve agent looks like**

Eve is designed to work with the filesystem. For example, a weather agent can be set up as a directory with just four small files:

```plaintext
agent/
|-- instructions.md
|-- agent.ts
|-- channels/
|   `-- eve.ts
`-- tools/
   `-- get_weather.ts
```

`instructions.md` defines the agent’s role. `agent.ts` selects and configures the model. Each file under `tools/` becomes a typed tool, and channel files expose the agent over HTTP, Slack, Discord, or another supported interface.

Eve turns each message into a durable workflow. It records model calls, tool calls, streamed events, waits, and user responses as part of the session. If a process stops in the middle of a turn, another process can pick up from the last completed step instead of starting over.

This is why production needs more than just an HTTP server. Durable execution requires persistent state, queues, retry handling, and a way to route resumed work to code that can still run it.

* * *

## **Running Eve as a standalone Watt application**

The simplest deployment uses `@platformatic/eve` directly. This capability manages Eve’s development server, runs its build pipeline, loads its production Nitro output, and exposes the application through Watt.

The Platformatic configuration is short:

```json
{
 "$schema": "https://schemas.platformatic.dev/@platformatic/eve/0.0.1.json",
 "module": "@platformatic/eve",
 "server": {
   "hostname": "0.0.0.0",
   "port": "{PORT}"
 }
}
```

The usual Watt commands cover the full lifecycle:

```plaintext
wattpm dev
wattpm build
wattpm start
```

Besides starting Eve, this capability connects it to Platformatic’s runtime. It uses Watt’s server settings, manages the agent with Watt’s application lifecycle, and collects HTTP metrics. You can package the production output in the same container and deployment pipeline as your other Watt applications, so you do not need a separate hosting model for the agent.

The [demos/weather-assistant](https://github.com/platformatic/eve/tree/main/demos/weather-assistant) example uses Eve’s weather agent and runs it in this way. It includes one typed tool and an HTTP channel, making it a helpful reference that does not hide the integration behind a bigger application.

* * *

## **Running Eve inside a Next.js application**

Often, an agent fits better inside an existing product instead of running behind a separate public endpoint. The [demos/next-eve-platformatic-world](https://github.com/platformatic/eve/tree/main/demos/next-eve-platformatic-world) example shows how to set this up.

Next.js runs on Watt through `@platformatic/next`, while Eve’s official `withEve()` integration provides the agent API. `@platformatic/eve` is not involved in this deployment path. The browser talks to the Next.js application, and Next forwards Eve session requests to the internal Eve process. A second rewrite forwards Workflow SDK callbacks:

```javascript
import { withEve } from 'eve/next'

const eveOrigin = `http://127.0.0.1:${process.env.EVE_NEXT_PRODUCTION_PORT ?? '4274'}`

const nextConfig = {
 async rewrites() {
   return {
     beforeFiles: [
       {
         source: '/.well-known/workflow/:path+',
         destination: `${eveOrigin}/.well-known/workflow/:path+`
       }
     ]
   }
 }
}

export default withEve(nextConfig)
```

The Next.js UI and Eve agent stay in the same project, image, and Kubernetes pod. Watt manages the Next.js application, while the internal Eve process handles session and workflow routes. This setup keeps the agent close to the application that uses it, without combining both runtimes into a single server.

Embedding Eve does not skip Watt. The Next.js application still runs with `@platformatic/next`, keeping Watt’s production runtime, application lifecycle management, HTTP metrics, health monitoring, gateway integration, and ICC support. ICC can monitor and scale the pod as a Watt deployment, and `@platformatic/world` connects Eve to the Workflow Service. This way, your application uses Eve’s agent model without losing the operational benefits from Watt or moving the Next.js deployment outside your existing infrastructure.

Both deployment styles use the same Eve project layout. Your choice depends on your needs: you can deploy a focused agent service or include the agent with the Next.js application where users interact with it.

* * *

## **Replacing Vercel’s hosted workflow infrastructure with** `@platformatic/world`

Eve uses the Workflow SDK’s World abstraction for session state, queues, hooks, waits, and streams. On Vercel, it can select Vercel World automatically. To run that infrastructure yourself, select `@platformatic/world` and point it to the Workflow Service provided by `@platformatic/workflow`:

```plaintext
WORKFLOW_TARGET_WORLD=@platformatic/world
PLT_WORLD_SERVICE_URL=http://localhost:3042
```

The `@platformatic/world` client sends workflow operations to the Workflow Service. This service stores workflow state in PostgreSQL and manages queue delivery, retries, hooks, waits, streams, and deployment lifecycle data. You can set `PLT_WORLD_SERVICE_URL` to a local service during development or to an internal address in your production environment.

The Workflow Service does not need ICC. It can run by itself with PostgreSQL for local development, CI, or self-managed deployments. This is helpful if you want durable Eve sessions while keeping the database, queue routing, and application inside your existing network and security setup.

ICC comes into play when your application runs in Kubernetes. Pods use their ServiceAccount tokens to authenticate, and ICC handles application provisioning, workflow handler registration, and deployment version management as versions move from active to draining and expired. The World client and Workflow Service stay the same, but ICC adds the Kubernetes control plane around them.

Model routing is equally portable. An Eve agent can pass an AI SDK provider model directly:

```javascript
import { anthropic } from '@ai-sdk/anthropic'
import { defineAgent } from 'eve'

export default defineAgent({
 model: anthropic('claude-sonnet-5')
})
```

The same flexibility applies to sandboxes. Eve can use local Docker, microsandbox, just-bash, or a custom backend. You can set up model routing, sandbox execution, workflow state, and application hosting to match your own infrastructure needs.

* * *

## **Distributing steps across pods and workers**

A durable agent session is made up of a series of queued operations, not a single long request tied to one Node.js process. This approach increases your execution capacity.

Each queue message handled by the Workflow Service includes the deployment version for its run. The Workflow Service sends the message to the Kubernetes Service registered for that version. Kubernetes can pick any ready pod behind that Service, and Watt can accept the connection on any configured application worker in the pod. This means different steps in a session can run on different pods and Watt workers, all while sharing the same durable state.

A session is tied to a deployment version, not to a specific pod or worker. This setup keeps code-version correctness while still allowing horizontal scaling and Watt’s multithreaded execution.

This design avoids sending every agent session through a single Node.js thread. Adding more pods increases your cluster’s capacity, and adding Watt workers lets each pod use its CPU cores. Distribution uses normal connection load balancing, so all eligible pods and workers can participate. The workflow uses your cluster’s existing capacity instead of relying on a provider-specific execution tier.

This design also helps with failure recovery. If a worker stops while handling a step, the queue retries the operation. A restarted worker or another worker in the deployment can take over. If a pod goes away, Kubernetes can send the retry to another ready pod. The durable event history and stable tool call identity let the workflow continue without treating a process failure as the end of the session.

The [demos/workflow-distribution-agent](https://github.com/platformatic/eve/tree/main/demos/workflow-distribution-agent) example shows this in action. It records the pod, Watt worker, and worker thread for each stage, then intentionally crashes selected workers to confirm that queued work finishes elsewhere.

* * *

## **One workflow, one code version**

Distributing work creates a second problem during deployments. A workflow may start on version 1, pause for a tool or human response, and resume after version 2 has become active. Replaying version 1’s event history against changed version 2 code can call steps in the wrong order or apply stored results to the wrong operation.

We introduced the underlying version-pinning model in [our Platformatic World launch post](https://blog.platformatic.dev/durable-workflows-kubernetes-version-safe), which explains why deterministic workflow replay must return to the code version that created the run.

The Workflow Service records the deployment version when the run starts. Every later queue message for that run carries the same version. When version 2 deploys, ICC marks version 1 as draining and sends new sessions to version 2, but the Workflow Service continues routing version 1’s steps to version 1 pods.

![](https://cdn.hashnode.com/uploads/covers/63f78b3e207712e9dab049ad/85323a95-b251-4753-aac6-a6586379f2eb.png align="center")

ICC does not decide that a workflow version is idle from HTTP traffic alone. A run may be sleeping, waiting for a webhook, or paused for human approval without producing traffic or queue messages. ICC asks the Workflow Service for active runs, pending hooks, waits, and queued messages. It keeps the draining deployment available while any of those counts are non-zero.

This setup gives you a clear guarantee: a workflow starts, resumes, and finishes on the same application version, even if new versions are deployed while it is running. New workflows use the latest active version, while older workflows keep the code they started with until they finish or reach the forced-expiration limit you set.

* * *

## **Operating Eve agents through ICC**

After deployment, the Watt application hosting Eve shows up in ICC just like other Watt applications. ICC collects runtime metrics, tracks deployments, and can scale the application based on Node.js signals like Event Loop Utilization. Operations stay within the same control plane your team uses for other Kubernetes workloads.

ICC also reads workflow data from the Workflow Service. The Workflows view lists runs by status and deployment version. Each run detail page shows its execution trace, step graph, events, hooks, and streams. Operators can replay a run on its original deployment version, cancel a run, or wake a sleeping workflow from the same interface.

This setup bridges the gap between building an agent and running it in production. Eve provides the agent framework, Watt runs the application, the Workflow Service handles durable distributed execution, and ICC manages the Kubernetes lifecycle.

* * *

## **Conclusion**

At the infrastructure level, `@platformatic/world` and the Workflow Service provide durable Eve sessions backed by PostgreSQL. You can run them without ICC for local development, CI, or in a self-managed environment.

At the application level, a standalone agent uses `@platformatic/eve` as its Watt capability. If the agent is embedded in Next.js, it uses Eve’s `withEve()` integration directly, while `@platformatic/next` keeps the application on Watt and preserves its runtime and operation.

When you move these applications to Kubernetes, ICC adds deployment management, scaling, and workflow-aware skew protection. Workflow steps can use available pods and, for standalone Watt agents, the configured workers. Retries help recover from process failures, and every run stays on the code version it started with. New deployments get new sessions as older versions finish their current work in progress.

You keep Eve’s instructions, tools, skills, channels, and durable sessions. Platformatic provides the runtime,

distributed execution, deployment lifecycle, and Kubernetes operations. Your application can run anywhere you use Kubernetes, including private cloud and on-premises environments.

The source and demos are available in the [platformatic/eve](https://github.com/platformatic/eve) repository. The source for `@platformatic/world` and the Workflow Service is available from [platformatic/platformatic-world](https://github.com/platformatic/platformatic-world).

If you’re planning to build agents and host on K8s, drop us a note at [hello@platformatic.dev](mailto:hello@platformatic.dev) or reach out on LinkedIn.