sailfork / t3code-github / .repos/ alchemy-effect/ website/ src/ content/ docs/ fly/ index.mdx

A Service is an Effect program running in Fly Machines inside its own App, with its own {name}.fly.dev hostname. An App is a globally unique namespace. A Machine is a Firecracker VM running a container. A Sprite is an Effect program in an org-scoped sandbox that hibernates when idle.

Disks, managed data, secrets, IPs, and certificates are declared in the same TypeScript program.

Set up your org and API token, then start the tutorial.

Compute

  • Apps — the namespace for Machines, Secrets, IPs, and certificates. Services create their own; declare one for Machines, App-level Secrets, custom domains, or to group Services. https://{appName}.fly.dev is the public URL.
  • Machines — a Firecracker VM running a container image. Use this when you already have an image (nginx:alpine, a registry tag). Region, guest size, proxy services, env, and mounts are all props.
  • Services — an Effect program running in Machines in its own App. Public by default at api.url, or private with public: false. Alchemy bundles main, builds the image, and updates in place when the hash changes. Set count to scale.
  • Connect Services — Services calling each other's methods with Fly.bindService on a stack-scoped private network (Fly.stackNetwork), behind one public gateway.
  • Sprites — an Effect program in a Fly Sprite. Org-scoped, no parent App. Hibernates when idle. Alchemy writes the bundle onto the Sprite. No Docker image.
  • Regions — the datacenter a Machine, Volume, Postgres cluster, or Redis primary lives in. Default iad. Changing region replaces the resource.

Frontend

Data

  • Volumes — region-local block storage. Mount one into a Service with MountVolume({ path, sizeGb }), or pass mounts on a Machine. A Volume attaches to one Machine; count: N creates N disks, not one shared disk.
  • Postgres — billed Managed Postgres. Bind ConnectPostgres on a Service; pass the connection string to Drizzle or SQL. migrations is the same surface as Neon.
  • Redis — Upstash Redis. Bind ReadWriteRedis on a Service.
  • Tigris — S3-compatible object storage (Fly.Bucket). Bind PutObject / GetObject on a Service.

Secrets

  • Secrets — Config.Redacted in a Service for values from .env. Fly.Secret when Fly should own a value shared across Machines. KMS keys are SecretKey plus Encrypt / Decrypt / Sign / Verify.

Networking

  • IPs & certificates — public and private Services, addresses (IpAssignment) for Apps you declare, plus ACME or uploaded TLS certificates for your own hostname.

What are you building?

You're buildingReach for
An HTTP API on FlyService
An internal APIService with public: false
Several Services talking privatelyConnect Services: Fly.bindService + Fly.stackNetwork
A Vite SPAWebsite.Vite
An SSR site (Astro, Next, Nuxt, …)Website
A sandbox that can sleepSprite
A raw containerMachine with an image
A background workerService with ServerHost.run
Persistent diskMountVolume or Machine mounts
Managed PostgresPostgres + ConnectPostgres
Upstash RedisRedis + ReadRedis / WriteRedis / ReadWriteRedis
Object storageTigris + PutObject / GetObject
N replicas behind fly.devService count, or more Machine resources
Restore a diskVolumeSnapshot + mount snapshotId
Config / API tokensConfig.Redacted. Fly.Secret when Fly should own it
Sign / encrypt in-appSecretKey + Encrypt / Sign
Addresses on your own AppIpAssignment type: "shared_v4"
Your own domainCertificate (ACME)

Where next

  • Setup — create a Fly org, generate an API token, and connect alchemy.
  • Tutorial — from empty directory to a public HTTP Service with a mounted Volume and a secret.
  • Websites — Vite, Astro, Next.js, and other framework sites as a Node Service.
  • Providers reference — generated API docs for every Fly resource Alchemy ships.