Publishing Edge Versions

Once your agent passes validation, you publish an edge version. A version is a snapshot of your bundled code that buyers deploy.

Version lifecycle

draft ──→ published ──→ yanked
              │
              └──→ deprecated (optional)

Status	Description	Buyers can deploy?
draft	Created but not yet published	No
published	Live on marketplace	Yes
yanked	Pulled from marketplace	No (existing deployments unaffected)
deprecated	Still deployable but discouraged	Yes (with warning)

Publishing with the CLI

# Deploy creates a draft version and publishes it
ad deploy

# Specify a version number
ad deploy --version 1.0.0

# Dry run — bundle only, don't upload
ad deploy --dry-run

# Skip validation step
ad deploy --skip-validation

What gets published

When you run ad deploy, the CLI:

1. Bundles your TypeScript with esbuild into a single ESM module (typically 200KB–2MB)
2. Uploads to POST /internal/edge/versions with:
   • The bundled script
   • Compatibility date and flags (nodejs_compat)
   • Auto-detected bindings from script analysis
3. Validates via the platform's edge validator (security patterns, size limits, SDK import checks)
4. Publishes the version to the marketplace

Version numbering

Use semantic versioning:

Change type	Version	Example
Breaking change	Major	2.0.0
New feature	Minor	1.1.0
Bug fix	Patch	1.0.1

If you don't specify --version, the CLI generates one based on the timestamp: 0.1.202501201430.

Publishing from the dashboard

1. Go to Dashboard > Seller > Templates > [Your Template] > Edge
2. Click Publish New Version
3. Enter a version number and changelog
4. Click Publish

Auto-detected metadata

The platform's script analysis (analyzeRenderedScript()) automatically detects:

Detection	How it's used
Durable Object classes (extends Agent, AIChatAgent)	Creates DO namespace bindings
SQLite-backed DO classes	Generates new_sqlite_classes migration
Agents SDK imports (agents, @cloudflare/ai-chat)	Injects nodejs_compat flag
env.AI references	Creates Workers AI binding
routeAgentRequest calls	Enables agent routing pattern

You don't need to manually configure these — they're inferred from your bundled code.

Updating a published version

You cannot modify a published version. The SHA-256 hash ensures buyers always deploy the exact code that was validated.

To update your agent:

# Push new code
ad deploy --version 1.1.0

• New deployments automatically use the latest published version
• Existing deployments stay on their current version until the buyer updates

Yanking a version

If you discover a critical bug:

Via CLI:

# Coming soon
ad yank --version 1.0.0

Via dashboard:

1. Go to your template's Edge tab
2. Find the version
3. Click Yank

Yanking immediately:

• Removes the version from the marketplace
• Prevents new deployments from using it
• Does not affect existing deployments

Best practices

• Write changelogs. Buyers want to know what changed between versions.
• Test locally first. Run ad dev to verify before deploying.
• Don't skip major versions. Breaking changes should bump the major version.
• Use --dry-run to check bundle size. SDK-bundled agents up to 3MB are accepted.