Configuration (5)·续

Local development

Starting the dev server

With Vite (recommended for full stack apps):

npx vite dev

Without Vite:

npx wrangler dev

Local state persistence

Durable Object state is persisted locally in .wrangler/state/:

  • .wrangler/
  • state/
    • v3/
    • d1/
      • miniflare-D1DatabaseObject/
      • ... (SQLite files)

Clearing local state

To reset all local Durable Object state:

rm -rf .wrangler/state

Or restart with fresh state:

npx wrangler dev --persist-to=""

Inspecting local SQLite

You can inspect agent state directly:

# Find the SQLite file
ls .wrangler/state/v3/d1/

# Open with sqlite3
sqlite3 .wrangler/state/v3/d1/miniflare-D1DatabaseObject/*.sqlite

Dashboard setup

Automatic resources

When you deploy, Cloudflare automatically creates:

  • Worker - Your deployed code
  • Durable Object namespaces - One per agent class
  • SQLite storage - Attached to each namespace

Viewing Durable Objects

Log in to the Cloudflare dashboard, then go to Durable Objects.

Go to Durable Objects ↗

Here you can:

  • See all Durable Object namespaces
  • View individual object instances
  • Inspect storage (keys and values)
  • Delete objects

Real-time logs

View live logs from your agents:

npx wrangler tail

Or in the dashboard:

  1. Go to your Worker.
  2. Select the Observability tab.
  3. Enable real-time logs.

Filter by:

  • Status (success, error)
  • Search text
  • Sampling rate

Production deployment

Basic deploy

npx wrangler deploy

This:

  1. Bundles your code
  2. Uploads to Cloudflare
  3. Provisions the Agent's Durable Object namespace storage
  4. Makes it live on *.workers.dev

Custom domain

Add a route in the Wrangler configuration file:

{
    "routes": [
        {
            "pattern": "agents.example.com/*",
            "zone_name": "example.com",
        },
    ],
}

[[routes]]
pattern = "agents.example.com/*"
zone_name = "example.com"

Or use a custom domain (simpler):

{
    "routes": [
        {
            "pattern": "agents.example.com",
            "custom_domain": true,
        },
    ],
}

[[routes]]
pattern = "agents.example.com"
custom_domain = true

Preview deployments

Deploy without affecting production:

npx wrangler deploy --dry-run    # See what would be uploaded
npx wrangler versions upload     # Upload new version
npx wrangler versions deploy     # Gradually roll out

Rollbacks

Roll back to a previous version:

npx wrangler rollback

Multi-environment setup

Environment configuration

Define environments in the Wrangler configuration file:

{
    "name": "my-agent",
    "main": "src/server.ts",
    "upload_source_maps": true,

// Base configuration (shared)
    // Set this to today's date
    "compatibility_date": "2026-10-27",
    "compatibility_flags": ["nodejs_compat"],
    "durable_objects": {
        "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }],
    },
    "exports": {
        "MyAgent": { "type": "durable-object", "storage": "sqlite" },
    },

// Environment overrides
    "env": {
        "staging": {
            "name": "my-agent-staging",
            "durable_objects": {
                "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }],
            },
            "vars": {
                "ENVIRONMENT": "staging",
            },
        },
        "production": {
            "name": "my-agent-production",
            "durable_objects": {
                "bindings": [{ "name": "MyAgent", "class_name": "MyAgent" }],
            },
            "vars": {
                "ENVIRONMENT": "production",
            },
        },
    },
}

name = "my-agent"
main = "src/server.ts"
upload_source_maps = true
# Set this to today's date
compatibility_date = "2026-10-27"
compatibility_flags = [ "nodejs_compat" ]

[[durable_objects.bindings]]
name = "MyAgent"
class_name = "MyAgent"

[exports.MyAgent]
type = "durable-object"
storage = "sqlite"

[env.staging]
name = "my-agent-staging"

[[env.staging.durable_objects.bindings]]
name = "MyAgent"
class_name = "MyAgent"

[env.staging.vars]
  ENVIRONMENT = "staging"

[env.production]
name = "my-agent-production"

[[env.production.durable_objects.bindings]]
name = "MyAgent"
class_name = "MyAgent"

[env.production.vars]
  ENVIRONMENT = "production"

Deploying to environments

# Deploy to staging
npx wrangler deploy --env staging

# Deploy to production
npx wrangler deploy --env production

# Set secrets per environment
npx wrangler secret put OPENAI_API_KEY --env staging
npx wrangler secret put OPENAI_API_KEY --env production

Separate Durable Objects

Named environments do not inherit Durable Object bindings. Repeat the bindings for each environment, as in the multi-environment setup. Each environment gets its own Durable Objects. Staging agents do not share state with production agents.

To explicitly separate:

{
    "env": {
        "staging": {
            "durable_objects": {
                "bindings": [
                    {
                        "name": "MyAgent",
                        "class_name": "MyAgent",
                        "script_name": "my-agent-staging",
                    },
                ],
            },
        },
    },
}

[[env.staging.durable_objects.bindings]]
name = "MyAgent"
class_name = "MyAgent"
script_name = "my-agent-staging"

Agent class lifecycle

Each Agent maps to a Durable Object class. You manage the lifecycle of those classes (create, rename, delete, transfer) through the exports field of your Wrangler configuration file.

Adding a new agent

Declare the new class in the exports:

{
    "exports": {
        "NewAgent": { "type": "durable-object", "storage": "sqlite" },
    },
}

[exports.NewAgent]
type = "durable-object"
storage = "sqlite"

Renaming an agent class

Replace the entry for the old name with a renamed tombstone and add a live entry for the new name:

{
    "exports": {
        "OldName": {
            "type": "durable-object",
            "state": "renamed",
            "renamed_to": "NewName",
        },
        "NewName": { "type": "durable-object", "storage": "sqlite" },
    },
}

[exports.OldName]
type = "durable-object"
state = "renamed"
renamed_to = "NewName"

[exports.NewName]
type = "durable-object"
storage = "sqlite"

Also update:

  1. The class name in code.
  2. The class_name in bindings.
  3. Export statements.

Deleting an agent class

Replace the entry with a deleted tombstone:

{
    "exports": {
        "AgentToKeep": { "type": "durable-object", "storage": "sqlite" },
        "AgentToDelete": { "type": "durable-object", "state": "deleted" },
    },
}

[exports.AgentToKeep]
type = "durable-object"
storage = "sqlite"

[exports.AgentToDelete]
type = "durable-object"
state = "deleted"

Caution

This permanently deletes all data for that class.

Class lifecycle best practices

  1. Keep exports in sync with your code. Every Agent class your Worker exports needs an entry.
  2. Use tombstones, not silent removal. When retiring a class, leave a deleted / renamed / transferred tombstone in exports so Cloudflare reconciles the change explicitly.
  3. Test locally first. Lifecycle changes apply on wrangler deploy.
  4. Back up production data before renaming or deleting.

Existing Workers using the legacy migrations array continue to work — refer to Durable Object class migrations (legacy) for the legacy reference, or Migrate from the legacy migrations flow to move to exports.

Troubleshooting

No such Durable Object class

The class is missing from exports. Declare the class and its storage:

{
    "exports": {
        "MissingClassName": { "type": "durable-object", "storage": "sqlite" },
    },
}

[exports.MissingClassName]
type = "durable-object"
storage = "sqlite"

Cannot find module in types

Regenerate types:

npx wrangler types env.d.ts --include-runtime false

Secrets not loading locally

Check that .env exists and contains the variable:

cat .env
# Should show: MY_SECRET=value

Migration tag conflict (legacy migrations only)

If your Worker uses the legacy migrations array, each entry must have a unique tag:

{
    // Wrong - duplicate tags
    "migrations": [
        { "tag": "v1", "new_sqlite_classes": ["A"] },
        { "tag": "v1", "new_sqlite_classes": ["B"] },
    ],
}

[[migrations]]
tag = "v1"
new_sqlite_classes = [ "A" ]

[[migrations]]
tag = "v1"
new_sqlite_classes = [ "B" ]

{
    // Correct - sequential tags
    "migrations": [
        { "tag": "v1", "new_sqlite_classes": ["A"] },
        { "tag": "v2", "new_sqlite_classes": ["B"] },
    ],
}

[[migrations]]
tag = "v1"
new_sqlite_classes = [ "A" ]

[[migrations]]
tag = "v2"
new_sqlite_classes = [ "B" ]

Consider converting to the declarative exports field.

Next steps

Agents API

Complete API reference for the Agents SDK.

Routing

Route requests to your agent instances.

Schedule tasks

Background processing with delayed and cron-based tasks.

Was this helpful?

YesNo

On this page

Configuration (5)·续 - 图1Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/agents/runtime/operations/configuration/#page","headline":"Configuration","description":"Configure Wrangler bindings, environment variables, and type generation for a project using the Agents SDK.","url":"https://developers.cloudflare.com/agents/runtime/operations/configuration/","inLanguage":"en","image":"https://developers.cloudflare.com/agents/runtime/operations/configuration/og.png?v=933c898d421435fa","dateModified":"2026-10-12","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Authenticate WebSocket connections to Cloudflare Agents across domains using signed tokens. title: Cross-domain authentication image: https://developers.cloudflare.com/agents/runtime/operations/cross-domain-authentication/og.png?v=d6fbb0ed839f2c1c

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/agents/llms.txt
Use this file to discover all available pages before exploring further.