sailfork / t3code-github / .repos/ alchemy-effect/ website/ src/ content/ docs/ aws/ compute/ choosing-a-runtime.mdx

Every Alchemy app on AWS needs somewhere for its code to run. Alchemy ships four runtimes, all driven by the same pattern — bundle an Effect program, deploy it as a resource, bind building blocks to it:

  • Lambda — serverless functions. Use this by default.
  • Lambda Web Functions — serverless HTTP servers. Use these for APIs and web apps.
  • ECS — long-running containers on Fargate.
  • EKS — containers as Kubernetes workloads on a managed Auto Mode cluster.
  • EC2 — virtual machines you fully control.

At a glance

LambdaLambda Web FunctionsECSEKSEC2
Execution modelPer-request, event-drivenHTTP server, many requests per environmentAlways-on containersKubernetes objects (Deployments, Jobs)Always-on machine
Cost shapePay per invocation; scales to zeroRequests + active CPU + memory; scales to zeroPay per running taskControl plane + Auto Mode nodesPay per running instance
StartupCold starts (ms–s), then warmCold starts, then warm; fewer under loadTask launch (tens of seconds), then steadyCluster create (~10 min), Pods in secondsInstance boot (minutes), then steady
PackagingBundled zip (Rolldown)Bundled zip or a built server; Node.js onlyDocker image, built + pushed for youDocker image, built + pushed for youBundled program on an AMI you choose
NetworkingNone required (Function URL)Built-in HTTPS endpoints; optional VPCVPC required (awsvpc), optional ALBVPC required, LoadBalancer ServicesVPC required, you own every primitive
Alchemy coverageFully documentedFully documentedCluster/Service/Task resourcesCluster/Deployment/Job/Manifest/HelmInstance + full VPC primitives

Lambda — the default

Serverless, event-driven, and the runtime this documentation is written around. You get the Function resource with a public Function URL, typed bindings that mint least-privilege IAM policies from your call sites, and Stream-shaped event sources for SQS, Kinesis, DynamoDB Streams, S3 notifications, SNS, and EventBridge. Cold starts and the 15-minute execution cap are the trade; per-request pricing and zero idle cost are the payoff.

Choose Lambda unless you have a specific reason not to. For an API or web app, start with a Lambda Web Function instead.

→ Lambda

Lambda Web Functions — HTTP servers

For anything that answers HTTP, a WebFunction runs your server on Lambda. Bring an Effect fetch handler or your own server (Hono, Express, Fastify), which Alchemy deploys unchanged.

Responses stream. A Web Function sends each chunk as your handler produces it, so token-by-token AI responses and server-sent events just work. A Lambda Function's fetch buffers the whole response, up to 6 MB, before the caller sees any of it.

One environment serves many requests at once (up to 128). A traffic spike starts fewer environments, requests share warm connection pools, and you pay for the CPU your code uses rather than the time it spends waiting on a database.

Each endpoint has its own URL, auth, rate limit and environment cap, and can sit behind CloudFront so only your distribution may call it.

Stay on a Lambda Function for queues, streams, S3 notifications, schedules and direct invokes: Web Functions only receive HTTP. Stay there too when you need another language or a container image, memory other than the fixed 2 GB per environment, a Region Web Functions don't run in yet, or local emulation under alchemy dev. Many apps use both: a Web Function for HTTP that hands work to a Lambda Function through a queue.

→ Lambda Web Functions

ECS — long-running containers

When your workload doesn't fit a request/response window — a WebSocket server, a worker that holds connections open, anything that should be always-on — run it as a container. Alchemy models ECS with three resources:

  • Cluster — an ECS cluster for running tasks and services.
  • Task — bundles an inline Effect program, builds and pushes a Docker image to a generated ECR repository, provisions task + execution IAM roles and a CloudWatch log group, and registers a Fargate task definition. Tasks can serve HTTP directly and accept the same binding contract (env + IAM policy statements) as Lambda.
  • Service — keeps a task definition running with awsvpc networking; set public: true and Alchemy provisions a public ALB + listener + target group for you.

You pay for running tasks whether or not they're serving traffic, and you bring a VPC (subnets + security groups) — the Network helper builds one in a single call.

→ ECS

EKS — when your platform is Kubernetes

When the workload is container-shaped but you want Kubernetes itself — Helm charts, operators, raw manifests, or teams already speaking Deployments and Jobs — Alchemy targets EKS Auto Mode, where AWS manages the control plane, nodes, storage, and load-balancer integration. Alchemy models it with:

  • Cluster — the control plane; compute: "auto" turns on Auto Mode with sensible defaults.
  • Deployment — a replicated Kubernetes server (the Kubernetes analog of AWS.ECS.Service) with the same three image sources as ECS: a registry image, a Dockerfile context, or an inline Effect program via main.
  • Job — run-to-completion work, or a CronJob when you set schedule.
  • Manifest and HelmChart — any raw Kubernetes object or a rendered Helm chart, applied via server-side apply.

Bindings work the same as on Lambda and ECS — env vars plus IAM policy statements, delivered through an EKS Pod Identity role — and there is no YAML and no kubectl step. You pay for the control plane and the nodes Auto Mode provisions, you bring a VPC (the Network helper builds one), and the control plane takes ~10 minutes to create.

→ EKS

For ML training fleets specifically — persistent, health-checked GPU clusters rather than application containers — EKS pairs with SageMaker HyperPod: the HyperPod nodes join your EKS cluster, and Deployment/Job opt onto them with the hyperpod prop.

EC2 — when you need the machine

Full-control VMs for workloads that need an OS, a GPU, custom daemons, or just predictable dedicated capacity. The Instance resource can act as a low-level compute primitive or run a bundled long-lived Effect program directly on the machine (including serving HTTP), and Alchemy ships the complete networking toolkit around it: Vpc, Subnet, SecurityGroup, NAT and internet gateways, route tables, EIPs, and VPC endpoints (see VPC & networking).

You own patching, scaling, and availability.

→ EC2

Rule of thumb

  1. Start with Lambda. Per-request cost, no servers, and the whole documented binding/event-source surface.
  2. Serve HTTP from a Lambda Web Function — streaming responses, many requests per environment, and endpoint-level auth and limits — unless you need a non-Node runtime, a container, or a Region it doesn't run in yet.
  3. Move a workload to ECS when it's long-running, needs more than 15 minutes, or is already a container.
  4. Pick EKS over ECS when you want Kubernetes itself — Helm charts, operators, raw manifests — not just a container runner.
  5. Reach for EC2 when you need the machine itself — kernel access, GPUs, custom networking, or software that expects a host.

Where next