Registry schema and deploy contracts

alchemy.new deploys versioned packages: GitHub releases and npm package versions. Each release ships an alchemy.new.jsonc file at its root. 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 include it in every release, together with the entrypoint it names. alchemy.new reads both from the release, never from 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/v1/project.json so editors can validate the file.

Schema fields

The tables below come from the live schema at /schema/v1/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 the live versioned schema URL.
`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 package identity: a GitHub release source or an npm source.
`deployment`Required	Required	Entrypoint, providers, and default stage.
`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. packageManager is optional in the schema. The runner installs and deploys with Nub.

ProjectDeployment fields

Field	Required	Description
`entrypoint`Required	Required	Package-relative Alchemy entrypoint ending in .ts, .mts, .js, or .mjs. The release must contain it. The path cannot start with / or contain ..
`packageManager`Optional	Optional	Declared installer. The accepted value is nub. The runner installs and deploys with Nub.
`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 the package: one GitHub release source or one npm source. alchemy.new resolves it to an exact version, reads alchemy.new.jsonc from that version, and checks that the version also contains deployment.entrypoint. A manifest whose source names a different package fails.

GitHub release

The repository must be public and have a published release. A deploy without a pinned tag uses the latest release. The runner clones that tag into an isolated sandbox, installs with Nub, and runs the entrypoint.

GitHubReleaseSource fields

Field	Required	Description
`kind`Required	Required	Source kind. The value must be github-release.
`repository`Required	Required	Public GitHub repository as owner/name.
`release`Optional	Optional	Release tag. Omit it in a released manifest; deploys use the latest published release unless a link pins a tag.

npm package

npm publishes only the files that package.json includes. Add alchemy.new.jsonc and the entrypoint to files. A deploy without a pinned version uses the latest dist-tag. The runner unpacks the exact version into the sandbox and installs its dependencies.

NpmSource fields

Field	Required	Description
`kind`Required	Required	Source kind. The value must be npm.
`packageName`Required	Required	Published npm package name.
`version`Optional	Optional	Exact version or dist-tag. Omit it in a released manifest; deploys use the latest dist-tag 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/v1/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": "github-release",    "repository": "example-org/example-stack"  },  "deployment": {    "entrypoint": "alchemy.run.ts",    "packageManager": "nub",    "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 GitHub release or npm version that ships the file and its entrypoint. The local write does not need a live registry session.

A deploy link works only after a release that contains alchemy.new.jsonc is published. alchemy.new reads the file 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/v1/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": "github-release",    "repository": "example-org/example-stack"  },  "deployment": {    "entrypoint": "alchemy.run.ts",    "packageManager": "nub",    "providers": [      "cloudflare"    ],    "defaultProvider": "cloudflare",    "defaultStage": "prod"  },  "parameters": [],  "tags": [    "cloudflare",    "web"  ],  "website": "https://example.com"}

Listing and verification

Submit a GitHub repository or npm package from the alchemy.new home page. alchemy.new checks the latest release before it accepts the submission: the release must contain alchemy.new.jsonc and its entrypoint, 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 release of a GitHub repository:

bash

https://alchemy.new/?github=example/project

Add release to pin a tag. Open an npm package with npm, and add version to pin an exact version:

bash

https://alchemy.new/?github=example/project&release=v1.4.0https://alchemy.new/?npm=%40example%2Finfrastructure&version=2.1.0

Add action=deploy to start a one-click deploy as soon as the visitor connects a cloud account. Earlier ?repo= links still open, and their ref must name a release tag.

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-114.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