Part 1: Your First Stack

Install Alchemy, declare an Archil disk, and deploy it.

Prerequisites

• Bun or Node.js 24.11.1+
• An Archil API key in an Alchemy profile (Setup)

Create a project

pnpm

mkdir my-app && cd my-app && pnpm init

bun

mkdir my-app && cd my-app && bun init -y

npm

mkdir my-app && cd my-app && npm init -y

yarn

mkdir my-app && cd my-app && yarn init -y

Install dependencies

pnpm

pnpm add https://pkg.alchemy.run/alchemy/pr:2930:0cabab6 https://pkg.alchemy.run/@alchemy.run/archil/pr:2930:0cabab6 effect @effect/platform-node

bun

bun add https://pkg.alchemy.run/alchemy/pr:2930:0cabab6 https://pkg.alchemy.run/@alchemy.run/archil/pr:2930:0cabab6 effect @effect/platform-node

npm

npm install https://pkg.alchemy.run/alchemy/pr:2930:0cabab6 https://pkg.alchemy.run/@alchemy.run/archil/pr:2930:0cabab6 effect @effect/platform-node

yarn

yarn add https://pkg.alchemy.run/alchemy/pr:2930:0cabab6 https://pkg.alchemy.run/@alchemy.run/archil/pr:2930:0cabab6 effect @effect/platform-node

Create the Stack

Every Alchemy program starts with a Stack:

alchemy.run.ts

import * as Archil from "@alchemy.run/archil";
import * as Alchemy from "alchemy";
import * as Effect from "effect/Effect";

export default Alchemy.Stack(
  "MyApp",
  { providers: Archil.providers(), state: Alchemy.localState() },
  Effect.gen(function* () {}),
);

Archil.providers() reads your key from your Alchemy profile. Alchemy.localState() keeps deploy state in .alchemy/ next to your code; Part 5 moves it somewhere CI can read.

Declare a disk

Declare resources in their own module so programs can import them:

src/Storage.ts

import * as Archil from "@alchemy.run/archil";

export const Files = Archil.Disk("Files", {});

Alchemy names the disk from the stack, stage and logical id.

Add it to the Stack

Yield the disk and return its id:

alchemy.run.ts

import * as Archil from "@alchemy.run/archil";
import * as Alchemy from "alchemy";
import * as Effect from "effect/Effect";
import { Files } from "./src/Storage.ts";

export default Alchemy.Stack(
  "MyApp",
  { providers: Archil.providers(), state: Alchemy.localState() },
  Effect.gen(function* () {}),
  Effect.gen(function* () {
    const files = yield* Files;
    return { diskId: files.diskId };
  }),
);

Deploy

pnpm

pnpm alchemy deploy

bun

bun alchemy deploy

npm

npx alchemy deploy

yarn

yarn alchemy deploy

The output prints diskId, a dsk-… id. The disk shows up under Disks in the Archil console.

Recap

You have a Stack with one Archil disk. In Part 2 you’ll run a program that reads and writes files on it.