Registry schema and deploy contracts

alchemy.new reads a versioned alchemy.new.jsonc file at the project 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 repository root for a Git project, or at the package root for an npm project. The file can use JSON with comments. The app rejects 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	JSON Schema URL for editors. Use the live versioned schema URL.
`schemaVersion`	Required	Schema version. The only accepted value is 1.
`id`	Required	Stable project identifier.
`name`	Required	Display name on alchemy.new.
`description`	Required	Short project summary.
`publisher`	Required	Publisher identity object.
`source`	Required	Git source object or npm source object.
`deployment`	Required	Entrypoint, providers, and default stage.
`parameters`	Required	Form inputs. An empty array is valid.
`tags`	Optional	Search and display labels.
`website`	Optional	Project website.

Publisher

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

ProjectPublisher fields

Field	Required	Description
`name`	Required	Publisher display name.
`github`	Optional	GitHub organization or user.
`website`	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	Repository-relative Alchemy entrypoint. npm wrappers write alchemy.run.ts and import the package export.
`packageManager`	Optional	Declared installer. The accepted value is nub. The runner installs and deploys with Nub.
`providers`	Required	Supported providers. Allowed values are cloudflare, aws, and other.
`defaultProvider`	Required	Default provider. Allowed values are cloudflare, aws, and other.
`defaultStage`	Required	Default Alchemy stage.

Git and npm sources

source is one Git object or one npm object. The two shapes do not mix.

Git source

The repository must contain the declared Alchemy entrypoint. Direct manifest loads currently support GitHub repositories. The runner clones the repository into an isolated sandbox. A private repository can use a one-run source token on the deployment request.

GitSource fields

Field	Required	Description
`kind`	Required	Source kind. The value must be git.
`url`	Required	HTTPS repository URL.
`ref`	Optional	Branch, tag, or commit. Direct GitHub loads use HEAD when this field is absent.
`token`	Optional	One-run token for a private repository. Do not publish this value in the manifest. Send it only with the deployment request. Share links remove it.

npm source

The npm package must export a default Alchemy Stack from the declared export path. alchemy.new writes a wrapper repository with package.json, alchemy.run.ts, and a resolved lockfile. The wrapper keeps the npm dependency so the user can update it later.

NpmSource fields

Field	Required	Description
`kind`	Required	Source kind. The value must be npm.
`packageName`	Required	npm package name.
`version`	Optional	Package version. Direct loads use latest when this field is absent.
`exportPath`	Optional	Package export that returns the default Alchemy Stack. The runner uses ./alchemy when this field is absent.

Parameters

Each parameter declares an environment variable name and a display label. The web form is built 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.

Mark required only when the process cannot start without the value. Feature environment variables should stay optional, with a safe public default or a fail-open description. A missing optional value must not block a first deploy. People can add values later to turn features on.

ProjectParameter fields

Field	Required	Description
`name`	Required	Exact environment variable name.
`label`	Required	Display label on the form.
`description`	Optional	Help text on the form.
`required`	Required	Boolean that controls form validation.
`secret`	Required	Boolean that marks a secret. The form masks the field and removes the value from URL state and short links.
`type`	Optional	string, number, boolean, or select. The form uses a text field when this field is absent.
`default`	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.
`options`	Optional	Allowed values for a select input.
`paths`	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 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	Stable path identifier written as the parameter value.
`label`	Required	Display label on the form.
`description`	Optional	Help text for this implementation path.

ParameterWhen fields

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

Example

This example matches schema version 1. It includes a public string, a secret string, 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": "git",    "url": "https://github.com/example-org/example-stack",    "ref": "main"  },  "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"    },    {      "name": "API_KEY",      "label": "API key",      "description": "Service key for the Example API.",      "required": true,      "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 on disk. That local write does not need a live registry session.

Commit and push alchemy.new.jsonc to GitHub before treating a ?repo= deploy link as working. alchemy.new fetches the file from the remote. An unpushed local file is not deployable. After the file is on the remote, the skill asks whether to upload the repository 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": "git",    "url": "https://github.com/example-org/example-stack",    "ref": "main"  },  "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 repository from the alchemy.new home page after alchemy.new.jsonc is on the GitHub remote. A submission records the repository for review. 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 a Git project with an encoded HTTPS repository URL:

bash

https://alchemy.new/?repo=https%3A%2F%2Fgithub.com%2Fexample%2Fproject

Add ref when the default revision is not correct. Open an npm package with npm:

bash

https://alchemy.new/?npm=%40example%2Finfrastructure

The source must contain alchemy.new.jsonc at the revision the URL points at. Direct Git loads currently support GitHub. npm loads read the published package.

Do not put secrets in a URL. The form excludes secret parameters, provider credentials, Git source tokens, and GitHub tokens from query state and short links.

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