Setup
Prerequisites
Section titled “Prerequisites”- Node.js 24.11.1+ or Bun
- A Docker engine the
dockerCLI can reach: Docker Desktop, Docker Engine on Linux, a remote host, or Podman
Check that the CLI reaches an engine:
docker versionInstall
Section titled “Install”pnpm add alchemy@latest @alchemy.run/docker@latest effectbun add alchemy@latest @alchemy.run/docker@latest effectnpm install alchemy@latest @alchemy.run/docker@latest effectyarn add alchemy@latest @alchemy.run/docker@latest effectRegister the providers
Section titled “Register the providers”import * as Alchemy from "alchemy";import * as Docker from "@alchemy.run/docker";import * as Effect from "effect/Effect";
export default Alchemy.Stack( "MyApp", { providers: Docker.providers(), state: Alchemy.localState(), }, Effect.gen(function* () { const web = yield* Docker.Container("web", { image: "nginx:alpine", ports: [{ external: 8080, internal: 80 }], start: true, }); return { ports: web.ports }; }),);There’s nothing to sign in to. Alchemy runs the docker CLI, and the CLI’s current context decides which engine it talks to. When Docker runs next to a cloud provider, merge the two: providers: Layer.merge(Cloudflare.providers(), Docker.providers()).
pnpm alchemy deploybun alchemy deploynpx alchemy deployyarn alchemy deployUse Podman or another binary
Section titled “Use Podman or another binary”Pass the CLI to run:
providers: Docker.providers({ bin: "podman" }),The DOCKER_BIN environment variable overrides bin on one machine, without changing the code:
DOCKER_BIN=/opt/homebrew/bin/docker pnpm alchemy deployDOCKER_BIN=/opt/homebrew/bin/docker bun alchemy deployDOCKER_BIN=/opt/homebrew/bin/docker npx alchemy deployDOCKER_BIN=/opt/homebrew/bin/docker yarn alchemy deployA CI runner needs the docker CLI and an engine, and nothing else: no profile, no token. GitHub’s hosted Linux runners have both. To deploy to a remote engine from CI, give the job the SSH key for that host and declare a Docker.Context for it. Registry passwords come from Config, like any other secret. See Registries & credentials and CI.
Next, choose where your containers run in Engines & contexts.