Registry schema and deploy contracts

alchemy.new deploys versioned packages from its registry. Each release publishes alchemy.new.jsonc next to the archive. That file is the project contract. The live JSON Schema is the machine source of truth. This page describes schema version 1.

Independent project

alchemy.new is not affiliated with Alchemy at alchemy.run. It uses Alchemy as the deployment engine.

Project manifest

Place alchemy.new.jsonc at the package root and publish it as its own object. Do not put it in the archive. alchemy.new reads the stored manifest, never a branch. The file can use JSON with comments. The app rejects a release with a missing or invalid manifest.

Set $schema to https://alchemy.new/schema/project.json so editors can validate the file.

Schema fields

The tables below come from the live schema at /schema/project.json. Do not add fields that the schema does not declare. Unknown fields fail validation.

ProjectManifest fields

Field	Required	Description
`$schema`Optional	Optional	JSON Schema URL for editors. Use https://alchemy.new/schema/project.json.
`schemaVersion`Required	Required	Schema version. The only accepted value is 1.
`id`Required	Required	Stable project identifier.
`name`Required	Required	Display name on alchemy.new.
`description`Required	Required	Short project summary.
`publisher`Required	Required	Publisher identity object.
`source`Required	Required	The alchemy.new package identity: org and project.
`deployment`Required	Required	Entrypoint, providers, and default stage. The registry archive is the artifact.
`parameters`Required	Required	Form inputs. An empty array is valid.
`tags`Optional	Optional	Search and display labels.
`website`Optional	Optional	Project website.

Publisher

publisher is a required object. Only name is required inside that object.

ProjectPublisher fields

Field	Required	Description
`name`Required	Required	Publisher display name.
`github`Optional	Optional	GitHub organization or user.
`website`Optional	Optional	Publisher website.

Deployment

deployment names the Alchemy entrypoint and the default run. The registry archive is the artifact. alchemy.new does not install dependencies or build the app.

ProjectDeployment fields

Field	Required	Description
`entrypoint`Required	Required	Package-relative Alchemy entrypoint ending in .ts, .mts, .js, or .mjs. The ready archive must contain it. The path cannot start with / or contain .. alchemy.new does not install or build.
`providers`Required	Required	Supported providers. Allowed values are cloudflare, aws, and other.
`defaultProvider`Required	Required	Default provider. Allowed values are cloudflare, aws, and other.
`defaultStage`Required	Required	Default Alchemy stage.

Packages and releases

source names an alchemy.new package. Publishers upload a ready archive and a separate manifest. alchemy.new resolves org/project to an exact version and reads the manifest stored with that version. A manifest whose source names a different package fails.

Registry package

org and project name the package. A deploy without a pinned version uses the latest non-yanked stable version. The archive root contains the entrypoint, built output, and node_modules/alchemy/bin/cli.js. It must not contain alchemy.new.jsonc. The runner downloads the archive, checks its sha256, and writes the stored manifest into the package root. It does not install dependencies.

RegistryPackageSource fields

Field	Required	Description
`kind`Required	Required	Source kind. The value must be registry.
`org`Required	Required	Lowercase org slug that owns the package.
`project`Required	Required	Lowercase package name inside the org.
`version`Optional	Optional	Exact semantic version. Omit it in a published manifest. Deploys use the latest non-yanked stable version unless a link pins a version.

Container images

The sandbox has no Docker daemon, so alchemy.new cannot build container images. A stack that uses Cloudflare Containers must reference a prebuilt image in a public registry with image, pinned by digest. A container that builds from main, context, or dockerfile fails the deploy.

During the deploy, alchemy.new copies each image into the deployer's Cloudflare registry, so Cloudflare starts containers from its own cache. Publish images from release CI to a registry such as GitHub Container Registry. Docker Hub works, but it limits anonymous pulls for each IP address.

typescript

// alchemy.run.tsCloudflare.Container<Agent>("Agent", {  image: "ghcr.io/owner/agent@sha256:<digest>",})

Parameters

Each parameter declares an environment variable name and a display label. The one-click defaults and the Customize form come from this list. required and secret are required booleans. type is optional.

A select input can declare options. A secret field uses a masked control. Secret values stay out of shared URL state and short links.

Every listed project deploys in one click. With the default choices applied, each active required parameter needs a default or a generate rule. alchemy.new rejects a manifest that breaks this rule. Feature environment variables should stay optional, with a safe public default or a fail-open description.

generate: "password" creates a 24-character password at deploy time when the field is empty. Use it for a password that a person signs in with. The deploy result shows it to the deployer once, and it never appears in logs, share links, or deployment output. Every deploy creates a new one, so use it only when the app reads the variable on every deploy.

Create machine secrets, such as signing and encryption keys, in the stack with Alchemy.Random when the variable is empty, and declare the parameter with required: false. Alchemy keeps the value in state, so later deploys reuse it.

ProjectParameter fields

Field	Required	Description
`name`Required	Required	Exact environment variable name.
`label`Required	Required	Display label on the form.
`description`Optional	Optional	Help text on the form.
`required`Required	Required	Boolean. A required parameter that is active under the default choices needs a default or a generate rule.
`secret`Required	Required	Boolean that marks a secret. The form masks the field and removes the value from URL state and short links.
`type`Optional	Optional	string, number, boolean, or select. The form uses a text field when this field is absent.
`default`Optional	Optional	Public default. The value can be a string, number, or boolean. Do not publish a credential as a default. Registry readers can inspect the manifest.
`generate`Optional	Optional	password. alchemy.new creates a 24-character sign-in password at deploy time when the field is empty and shows it to the deployer once. Every deploy creates a new one. String parameters only; do not combine with default. Create machine secrets in the stack with Alchemy.Random.
`options`Optional	Optional	Allowed values for a select input.
`paths`Optional	Optional	Implementation paths for one detail. Each path has an id, a label, and an optional description. The selected id is the parameter value. Use this for choices such as D1 or PlanetScale. These paths are not cloud providers.
`when`Optional	Optional	Optional gate. The parameter is active only when another parameter equals the given path id. Required applies only while the gate is true.

Implementation paths

Use paths when one detail has more than one implementation. The first case is a database select with d1 and planetscale. Cloudflare D1 is the default. PlanetScale is not a cloud provider and must not appear in deployment.providers.

Gate path-scoped secrets with when. Those fields stay hidden and are not required until the matching path is selected. The default path stays one-click.

ImplementationPath fields

Field	Required	Description
`id`Required	Required	Stable path identifier written as the parameter value.
`label`Required	Required	Display label on the form.
`description`Optional	Optional	Help text for this implementation path.

ParameterWhen fields

Field	Required	Description
`parameter`Required	Required	Name of the path-selector parameter that controls this field.
`equals`Required	Required	Path id that activates this parameter.

Example

This example matches schema version 1 and deploys in one click. It includes a public string with a default, a generated password, an optional secret, a simple select, and a database implementation-path select with a gated PlanetScale secret. The file can include comments when you store it as JSONC.

jsonc

{  "$schema": "https://alchemy.new/schema/project.json",  "schemaVersion": 1,  "id": "example-stack",  "name": "Example stack",  "description": "Deploys the Example service.",  "publisher": {    "name": "Example",    "github": "example-org",    "website": "https://example.com"  },  "source": {    "kind": "registry",    "org": "example-org",    "project": "example-stack"  },  "deployment": {    "entrypoint": "alchemy.run.ts",    "providers": [      "cloudflare"    ],    "defaultProvider": "cloudflare",    "defaultStage": "prod"  },  "parameters": [    {      "name": "APP_NAME",      "label": "Application name",      "description": "Public name used for deployed resources.",      "required": true,      "secret": false,      "type": "string",      "default": "example"    },    {      "name": "ADMIN_PASSWORD",      "label": "Administrator password",      "description": "Signs in to the admin console.",      "required": true,      "secret": true,      "type": "string",      "generate": "password"    },    {      "name": "API_KEY",      "label": "API key",      "description": "Optional key for the Example API. The project deploys without it.",      "required": false,      "secret": true,      "type": "string"    },    {      "name": "REGION",      "label": "Region",      "required": false,      "secret": false,      "type": "select",      "default": "us-east",      "options": [        "us-east",        "eu-west"      ]    },    {      "name": "DATABASE",      "label": "Database",      "description": "Implementation path for the database.",      "required": true,      "secret": false,      "type": "select",      "default": "d1",      "paths": [        {          "id": "d1",          "label": "Cloudflare D1"        },        {          "id": "planetscale",          "label": "PlanetScale Postgres"        }      ]    },    {      "name": "PLANETSCALE_SERVICE_TOKEN_ID",      "label": "PlanetScale service token ID",      "required": true,      "secret": true,      "type": "string",      "when": {        "parameter": "DATABASE",        "equals": "planetscale"      }    }  ],  "tags": [    "cloudflare",    "example"  ],  "website": "https://example.com"}

Publisher skill

Copy the publish-to-alchemy-new skill into an Alchemy repository. The skill writes or updates alchemy.new.jsonc, checks the one-click rule, and prepares a ready archive plus the manifest upload. The local write does not need a live registry session.

A deploy link works only after a release that contains alchemy.new.jsonc and a ready deploy artifact is published. alchemy.new reads the manifest from the release, so a committed but unreleased file is not deployable. After the release, the skill asks whether to upload the package for review. Upload is optional.

Start from an empty parameters list when the stack can deploy without project-specific env:

jsonc

{  "$schema": "https://alchemy.new/schema/project.json",  "schemaVersion": 1,  "id": "example-stack",  "name": "Example stack",  "description": "Deploys the Example service and its data resources.",  "publisher": {    "name": "Example",    "github": "example-org",    "website": "https://example.com"  },  "source": {    "kind": "registry",    "org": "example-org",    "project": "example-stack"  },  "deployment": {    "entrypoint": "alchemy.run.ts",    "providers": [      "cloudflare"    ],    "defaultProvider": "cloudflare",    "defaultStage": "prod"  },  "parameters": [],  "tags": [    "cloudflare",    "web"  ],  "website": "https://example.com"}

Listing and verification

Submit an alchemy.new package (org/project) from the alchemy.new home page. alchemy.new checks the latest release before it accepts the submission: the release must ship a ready deploy artifact, and the manifest must deploy in one click. A submission does not grant verification.

alchemy.new reviews publisher identity in a separate step. After that review, a project can receive a verified badge and a higher search rank. Featured and verified projects rank before unverified projects.

Deploy links

Open the latest published version of a registry package:

bash

https://alchemy.new/?package=example-org/example-stack

Add version to pin an exact semantic version.

bash

https://alchemy.new/?package=example-org/example-stack&version=1.4.0

Add action=deploy to start a one-click deploy as soon as the visitor connects a cloud account.

Do not put secrets in a URL. Share links exclude secret parameters, provider credentials, and GitHub tokens.

For agents

Agents can read the compact or full machine guide, or connect directly to the MCP endpoint for registry search, deployment planning, and deployment tools.

llms.txt
Short agent index for the registry and MCP endpoint.
llms-full.txt
Longer agent guide for search, plan, and deploy tools.
MCP endpoint
Streamable HTTP server at the API base URL, https://alchemy-new-api-pre-130.jonbeckman.workers.dev/mcp.

Brand kit

Live text experiment: the Manrope wordmark is rendered as a responsive puffy cloud field with pointer dissolve controls.

Standard
Charcoal square with a transparent fluff center.
Download SVG
Negative
Charcoal fluff mark on a transparent square.
Download SVG
White center
Charcoal square with an opaque white fluff center.
Download SVG
Deploy badge
Cloud-backed README badge for linking projects to alchemy.new.
Download SVG
Cloud text
Interactive puffy cloud lettering built from the wordmark.
Enter Playground