# alchemy.new agent guide alchemy.new deploys curated, versioned Alchemy packages into the visitor's own cloud account. A search result offers **Deploy** (one click, manifest defaults) and **Customize** (edit every parameter first). Deployment code runs in a fresh Cloudflare Sandbox container that is destroyed when the run ends. alchemy.new is not affiliated with Alchemy at alchemy.run. It uses Alchemy as the deployment engine. ## Packages alchemy.new deploys only versioned packages: - A GitHub release of a public repository. Without a pinned tag, the latest published release deploys. - An npm package version. Without a pinned version, the `latest` dist-tag deploys. The release must contain `alchemy.new.jsonc` at its root and the file at `deployment.entrypoint`. alchemy.new resolves the source to an exact version, reads the manifest from that version, rejects a manifest whose `source` names a different package, and checks that the entrypoint exists. Branches and unreleased commits cannot deploy. 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 (`ghcr.io/owner/agent@sha256:`). 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; GitHub Container Registry suits GitHub releases. Docker Hub limits anonymous pulls for each IP address. ## Project manifest The human contract page is `https://alchemy.new/docs`. Set `schemaVersion` to `1` and `$schema` to `https://alchemy.new/schema/v1/project.json`. The manifest declares: - A stable project id, display name, description, publisher, and tags. - A `source`: `{ "kind": "github-release", "repository": "owner/name" }` or `{ "kind": "npm", "packageName": "name" }`. - The package-relative Alchemy entrypoint, supported providers, default provider, and stage. - Each project parameter with its name, label, requirement state, secret state, type, default, generator, and allowed values. - Optional implementation `paths` on a select, and optional `when` gates so path-scoped secrets are required only for the selected path. One-click rule: with the default choices applied, every active required parameter has a `default` or `"generate": "password"`. alchemy.new rejects a manifest that breaks the rule. A generated password is created at deploy time when the field is empty and is returned once in the deployment result; every deploy creates a new one, so use it only for a password that a person signs in with and that the app reads on every deploy. Stacks create machine secrets, such as signing and encryption keys, with `Alchemy.Random` when the variable is empty, and declare those parameters with `required: false`. Alchemy keeps those values in state across deploys. Implementation paths are not cloud providers; `deployment.providers` stays `cloudflare`, `aws`, or `other`. ## Deploying Cloudflare credentials come from, in order: pasted `CLOUDFLARE_API_TOKEN` and `CLOUDFLARE_ACCOUNT_ID`, the signed-in user's linked Cloudflare account, or a single-use Cloudflare sign-in grant. A visitor does not need an alchemy.new account; Cloudflare sign-in without one grants access for one deploy, expires after 30 minutes, and is revoked after a successful deploy. The web app starts a durable run with `POST /v1/runs`. The response carries a run id and a run token. `GET /v1/runs/{id}?since=` with the `X-Run-Token` header returns phase, plan, per-resource, and redacted log events parsed from the Alchemy CLI. The run keeps going if the browser closes. Finished runs are deleted after 24 hours. `POST /v1/deployments` runs the same pipeline and waits for the result. ## MCP Connect to the API base URL plus `/mcp` with Streamable HTTP. Local development uses `http://localhost:1338`. The server supports current MCP requests and the 2025 stateless HTTP flow. Tools: - `search_registry`: Search ranked registry entries. Featured and verified projects rank before unverified projects. Exact deployment totals break later ties. - `get_registry_project`: Read one registry record and its `alchemy.new.jsonc` manifest. - `plan_registry_deployment`: Validate parameters, provider support, storage, and required credentials. This tool does not deploy. - `deploy_registry_project`: Deploy the latest release and wait for the result. Parameters are optional overrides; defaults and generated values fill the rest. Supply provider credentials. This tool creates or updates infrastructure at the selected provider. Plan before deployment. Treat source code as untrusted. The project can read each credential and parameter passed to its process. Show generated values to the user once and do not log them. ## Storage Repository choices are temporary alchemy.new storage (the default) or GitHub. Cloudflare Artifacts appears as a disabled future option. State choices are Cloudflare state (the Cloudflare default), Amazon S3 (the AWS default), download, or temporary alchemy.new storage. Temporary files use R2. A private claim link provides access for 30 days. ## Publishing Use the repository skill at `.agents/skills/publish-to-alchemy-new/SKILL.md`. It 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. Do not present a deploy link as working until that release is published. After the release, the skill asks before any registry upload. Upload is opt-in. A submission checks the latest release and returns the reason when it fails. Anyone can submit. Publisher verification is a separate review and gives the project a badge plus a search rank boost. alchemy.new is not affiliated with Alchemy at alchemy.run. It uses Alchemy as the deployment engine. ## Payments x402 deployment payments are a future design area. The current API has no payment gate.