> 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: Deploy a serverless endpoint to Cloudflare Workers
description: Create a new Cloudflare Worker, connect it to AGNT5, and run a signed workflow through the deployed endpoint.
last_verified: 2026-07-09
---

This quickstart takes a new Cloudflare Workers project from an empty template to a successful AGNT5 workflow run. You use Wrangler for local development and deployment, then use the AGNT5 CLI to validate, sync, verify, and activate the endpoint.

The result is a Cloudflare-hosted `hello` workflow registered as an immutable AGNT5 deployment.

<Callout type="info">
This beta guide requires an AGNT5 CLI build whose **`agnt5 serverless --help`** output includes `init`, `validate`, `sync`, and `status`. It uses the published TypeScript SDK `@agnt5/sdk@0.6.0-beta.0`.
</Callout>

## 1. Check the prerequisites

You need:

- A [Cloudflare account](https://dash.cloudflare.com/sign-up/workers-and-pages).
- A current Node.js LTS release with npm.
- An AGNT5 account and the beta AGNT5 CLI.
- Permission to create an AGNT5 project in your workspace.

Verify the two CLIs before creating the project:

```bash
node --version
agnt5 serverless --help
```

## 2. Create the Worker project

Create a Worker with Cloudflare's project generator:

```bash
npm create cloudflare@latest -- hello-agnt5
cd hello-agnt5
```

Choose a Worker-only Hello World template, TypeScript, and no initial deployment when the generator prompts you. The generated project contains `package.json`, `wrangler.jsonc`, and a starter file under `src/`.

Authenticate with AGNT5 and create a linked AGNT5 project for the current directory:

```bash
agnt5 auth login
agnt5 init --new --name hello-agnt5 --language typescript
```

## 3. Add the AGNT5 handler

Install the published beta SDK and generate the Cloudflare handler:

```bash
npm install @agnt5/sdk@0.6.0-beta.0
agnt5 serverless init --provider cloudflare --name hello-agnt5
```

The command creates `src/agnt5-workerless.ts` and adds `.agnt5-serverless-secret` to `.gitignore`. It does not overwrite the Worker files generated by Cloudflare.

Open `wrangler.jsonc` and set its `main` field to the generated handler:

```json
{
  "main": "src/agnt5-workerless.ts"
}
```

Keep the other generated Wrangler fields, including `name` and `compatibility_date`.

## 4. Validate locally

Generate one signing secret. You will use the same value for the Cloudflare binding and the AGNT5 deployment:

```bash
( umask 077 && openssl rand -base64 32 > .agnt5-serverless-secret )
printf 'AGNT5_SERVERLESS_SIGNING_SECRET="%s"\n' \
  "$(cat .agnt5-serverless-secret)" > .dev.vars
```

Do not commit `.dev.vars` or `.agnt5-serverless-secret`. Confirm both files are ignored before continuing:

```bash
git check-ignore .dev.vars .agnt5-serverless-secret
```

The command should print both paths. Add any missing path to `.gitignore` before continuing.

Start the Worker locally:

```bash
npx wrangler dev
```

In a second terminal, validate the local endpoint:

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

A successful validation reports protocol `workerless.v1` and component `workflow:hello`. Stop Wrangler with `Ctrl+C` after validation succeeds.

## 5. Deploy to Cloudflare

Sign in to Cloudflare and store the production secret as a Worker secret:

```bash
npx wrangler login
npx wrangler secret put AGNT5_SERVERLESS_SIGNING_SECRET \
  < .agnt5-serverless-secret
```

Deploy the Worker:

```bash
npx wrangler deploy
```

Copy the `https://<worker>.<account>.workers.dev` endpoint from the Wrangler output. Then list recent Worker versions:

```bash
npx wrangler versions list
```

Copy the newest `Version ID` that matches this deployment. AGNT5 stores that immutable provider version separately from the stable `workers.dev` endpoint.

## 6. Validate the deployment

Validate the public endpoint before creating AGNT5 state:

```bash
agnt5 serverless validate \
  https://<worker>.<account>.workers.dev
```

Validation checks the manifest route, protocol version, service identity, component declarations, and manifest hash. It does not register or activate the endpoint.

## 7. Sync without activating

Load the shared signing secret into the current terminal:

```bash
export AGNT5_SERVERLESS_SIGNING_SECRET="$(cat .agnt5-serverless-secret)"
```

Import the Cloudflare version into the AGNT5 `production` environment without changing active component routes:

```bash
agnt5 serverless sync \
  https://<worker>.<account>.workers.dev \
  --provider cloudflare \
  --env production \
  --immutable-ref <cloudflare-version-id> \
  --signing-secret-env AGNT5_SERVERLESS_SIGNING_SECRET \
  --request-timeout-ms 10000 \
  --yield-before-timeout-ms 1000 \
  --activate=false
```

Copy the AGNT5 deployment ID from the result. The Cloudflare version ID identifies provider code; the AGNT5 deployment ID identifies the registered endpoint and its durable execution state.

## 8. Verify and activate

Require live manifest health, signing configuration, dispatch readiness, protocol compatibility, and no manifest drift:

```bash
agnt5 serverless status \
  --deployment-id <agnt5-deployment-id> \
  --verify
```

After verification passes, run the same sync command with activation enabled:

```bash
agnt5 serverless sync \
  https://<worker>.<account>.workers.dev \
  --provider cloudflare \
  --env production \
  --immutable-ref <cloudflare-version-id> \
  --signing-secret-env AGNT5_SERVERLESS_SIGNING_SECRET \
  --request-timeout-ms 10000 \
  --yield-before-timeout-ms 1000 \
  --activate=true
```

Sync is idempotent for the provider and immutable reference. The second command reuses the imported deployment and activates its component routes.

## 9. Run the workflow

Invoke the deployed workflow through AGNT5:

```bash
agnt5 run workflow hello \
  --deployment-id <agnt5-deployment-id> \
  --input '{"name":"Ada"}'
```

The successful result contains:

```json
{
  "message": "hello Ada"
}
```

You have now exercised the complete path: AGNT5 accepted the run, signed the invoke request, Cloudflare executed the workflow, and AGNT5 recorded the result.

## Troubleshoot the quickstart

### `serverless init` or `serverless validate` is unknown

Your AGNT5 CLI predates this beta slice. Run **`agnt5 serverless --help`** and install the beta CLI build supplied for the test before continuing.

### The SDK serverless import cannot be resolved

Confirm `package.json` contains `@agnt5/sdk` version `0.6.0-beta.0`, then reinstall dependencies:

```bash
npm install @agnt5/sdk@0.6.0-beta.0
```

### Local validation cannot connect

Keep **`npx wrangler dev`** running in the first terminal. If Wrangler chose another port, pass that loopback URL to **`agnt5 serverless validate`**.

### Sync reports a route-owner conflict

Keep `--activate=false` while testing. Follow [Operate serverless endpoints](/docs/run/operate-serverless-endpoints.md#resolve-route-owner-conflicts) before replacing an existing route owner.

### Status reports signing is not configured

Export `AGNT5_SERVERLESS_SIGNING_SECRET` in the terminal that runs sync and include `--signing-secret-env AGNT5_SERVERLESS_SIGNING_SECRET`. Do not pass the secret value directly in shell history.

## Report a beta problem

Capture the following details when a step fails:

```bash
agnt5 version
npx wrangler --version
npm list @agnt5/sdk
```

Include the failing command, redacted output, Cloudflare version ID, AGNT5 deployment ID, and the last successful guide step. Never include `.dev.vars`, `.agnt5-serverless-secret`, an API token, or the value of `AGNT5_SERVERLESS_SIGNING_SECRET`.

## Next steps

- [Operate serverless endpoints](/docs/run/operate-serverless-endpoints.md): disable, recover, rotate, and roll back the deployment.
- [Serverless endpoints](/docs/run/serverless-endpoints.md): understand supported hosts and beta limits.
- [Serverless CLI reference](/cli/serverless.md): inspect every command and flag.
- [Workflows](/docs/build/workflows.md): replace `hello` with a durable multi-step workflow.