> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: Add AGNT5 to a Node.js server
description: Mount signed AGNT5 serverless routes in Node.js, Express, Fastify, or Koa and sync the deployed service.
last_verified: 2026-07-20
---

You can add AGNT5 to an existing Node.js service without replacing its routes or running a persistent AGNT5 worker. The Node adapter preserves the raw request body required for HMAC verification.

## 1. Create the handler

Install the SDK and import the Node entrypoint:

```bash
npm install @agnt5/sdk@0.6.0
```

```typescript
const hello = workflow('hello', async (_ctx, input: { name?: string }) => ({
  message: `hello ${input.name ?? 'world'}`,
}));

export const agnt5Serverless = serveNode({
  serviceName: 'orders-api',
  serviceVersion: process.env.GIT_SHA ?? 'local',
  signingSecret: () => process.env.AGNT5_SERVERLESS_SIGNING_SECRET,
  workflows: [hello],
});
```

## 2. Mount the routes

Mount the handler at both protocol routes. Express must receive the request before a JSON body parser consumes it:

```typescript
app.all('/.well-known/agnt5', agnt5Serverless);
app.all('/agnt5/invoke', agnt5Serverless);
```

Fastify and Koa integrations pass their raw Node request and response objects. Do not reconstruct the signed body from parsed JSON.

## 3. Validate and sync

Set `AGNT5_SERVERLESS_SIGNING_SECRET`, start the service, and validate it:

```bash
agnt5 serverless validate http://127.0.0.1:8787
```

After deploying the service to HTTPS, import its immutable release:

```bash
agnt5 serverless sync https://<node-host> \
  --provider node \
  --immutable-ref <git-sha-or-release-id> \
  --signing-secret-env AGNT5_SERVERLESS_SIGNING_SECRET \
  --activate=false
```

Require **`agnt5 serverless status --deployment-id <deployment-id> --verify`** before activating it.

## Next steps

- [Serverless SDK reference](/docs/run/serverless-sdk-reference.md): add checkpoints, timers, and stream events.
- [Serverless protocol reference](/docs/run/serverless-protocol.md): inspect the routes and signed message contract.
- [Operate serverless endpoints](/docs/run/operate-serverless-endpoints.md): promote and recover immutable releases.