The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 177 lines 9.1 KB
Raw
1 ---
2 title: Choosing a runtime
3 description: Lambda vs ECS vs EKS vs EC2 for Alchemy apps — cold starts, cost shape, packaging, and how much of each Alchemy currently covers.
4 ---
5
6 Every Alchemy app on AWS needs somewhere for its code to run.
7 Alchemy ships four runtimes, all driven by the same pattern —
8 bundle an Effect program, deploy it as a resource, bind building
9 blocks to it:
10
11 - **Lambda** — serverless functions. **Use this by default.**
12 - **Lambda Web Functions** — serverless HTTP servers. **Use these for APIs
13 and web apps.**
14 - **ECS** — long-running containers on Fargate.
15 - **EKS** — containers as Kubernetes workloads on a managed
16 Auto Mode cluster.
17 - **EC2** — virtual machines you fully control.
18
19 ## At a glance
20
21 | | Lambda | Lambda Web Functions | ECS | EKS | EC2 |
22 | ---------------- | ------------------------------------------ | ------------------------------------------- | ------------------------------------------ | -------------------------------------------- | ---------------------------------------- |
23 | Execution model | Per-request, event-driven | HTTP server, many requests per environment | Always-on containers | Kubernetes objects (Deployments, Jobs) | Always-on machine |
24 | Cost shape | Pay per invocation; scales to zero | Requests + active CPU + memory; scales to zero | Pay per running task | Control plane + Auto Mode nodes | Pay per running instance |
25 | Startup | Cold starts (ms–s), then warm | Cold starts, then warm; fewer under load | Task launch (tens of seconds), then steady | Cluster create (~10 min), Pods in seconds | Instance boot (minutes), then steady |
26 | Packaging | Bundled zip (Rolldown) | Bundled zip or a built server; Node.js only | Docker image, built + pushed for you | Docker image, built + pushed for you | Bundled program on an AMI you choose |
27 | Networking | None required (Function URL) | Built-in HTTPS endpoints; optional VPC | VPC required (awsvpc), optional ALB | VPC required, `LoadBalancer` Services | VPC required, you own every primitive |
28 | Alchemy coverage | Fully documented | Fully documented | Cluster/Service/Task resources | Cluster/Deployment/Job/Manifest/Helm | Instance + full VPC primitives |
29
30 ## Lambda — the default
31
32 Serverless, event-driven, and the runtime this documentation is
33 written around. You get the [`Function`](/providers/aws/lambda/function)
34 resource with a public Function URL, typed bindings that mint
35 least-privilege IAM policies from your call sites, and
36 `Stream`-shaped event sources for SQS, Kinesis, DynamoDB
37 Streams, S3 notifications, SNS, and EventBridge. Cold starts and
38 the 15-minute execution cap are the trade; per-request pricing
39 and zero idle cost are the payoff.
40
41 Choose Lambda unless you have a specific reason not to. For an API or
42 web app, start with a Lambda Web Function instead.
43
44 → [Lambda](/aws/compute/lambda)
45
46 ## Lambda Web Functions — HTTP servers
47
48 For anything that answers HTTP, a
49 [`WebFunction`](/providers/aws/lambda#webfunction) runs your server on
50 Lambda. Bring an Effect `fetch` handler or your own server (Hono, Express,
51 Fastify), which Alchemy deploys unchanged.
52
53 Responses stream. A Web Function sends each chunk as your handler
54 produces it, so token-by-token AI responses and server-sent events just
55 work. A Lambda Function's `fetch` buffers the whole response, up to 6 MB,
56 before the caller sees any of it.
57
58 One environment serves many requests at once (up to 128). A traffic spike
59 starts fewer environments, requests share warm connection pools, and you
60 pay for the CPU your code uses rather than the time it spends waiting on a
61 database.
62
63 Each endpoint has its own URL, auth, rate limit and environment cap, and
64 can sit behind CloudFront so only your distribution may call it.
65
66 Stay on a Lambda Function for queues, streams, S3 notifications,
67 schedules and direct invokes: Web Functions only receive HTTP. Stay there
68 too when you need another language or a container image, memory other
69 than the fixed 2 GB per environment, a Region Web Functions don't run in
70 yet, or local emulation under `alchemy dev`. Many apps use both: a Web
71 Function for HTTP that hands work to a Lambda Function through a queue.
72
73 → [Lambda Web Functions](/aws/compute/web-functions)
74
75 ## ECS — long-running containers
76
77 When your workload doesn't fit a request/response window — a
78 WebSocket server, a worker that holds connections open, anything
79 that should be always-on — run it as a container. Alchemy models
80 ECS with three resources:
81
82 - [`Cluster`](/providers/aws/ecs/cluster) — an ECS cluster for
83 running tasks and services.
84 - [`Task`](/providers/aws/ecs/task) — bundles an inline Effect
85 program, builds and pushes a Docker image to a generated ECR
86 repository, provisions task + execution IAM roles and a
87 CloudWatch log group, and registers a Fargate task definition.
88 Tasks can serve HTTP directly and accept the same
89 binding contract (env + IAM policy statements) as Lambda.
90 - [`Service`](/providers/aws/ecs/service) — keeps a task
91 definition running with awsvpc networking; set `public: true`
92 and Alchemy provisions a public ALB + listener + target group
93 for you.
94
95 You pay for running tasks whether or not they're serving
96 traffic, and you bring a VPC (subnets + security groups) — the
97 [`Network`](/providers/aws/ec2/network) helper builds one in a
98 single call.
99
100 → [ECS](/aws/compute/ecs)
101
102 ## EKS — when your platform is Kubernetes
103
104 When the workload is container-shaped but you want Kubernetes
105 itself — Helm charts, operators, raw manifests, or teams already
106 speaking Deployments and Jobs — Alchemy targets **EKS Auto Mode**,
107 where AWS manages the control plane, nodes, storage, and
108 load-balancer integration. Alchemy models it with:
109
110 - [`Cluster`](/providers/aws/eks/cluster) — the control plane;
111 `compute: "auto"` turns on Auto Mode with sensible defaults.
112 - [`Deployment`](/providers/kubernetes/deployment) — a replicated
113 Kubernetes server (the Kubernetes analog of `AWS.ECS.Service`)
114 with the same three image sources as ECS: a registry `image`, a
115 Dockerfile `context`, or an inline Effect program via `main`.
116 - [`Job`](/providers/kubernetes/job) — run-to-completion work, or a
117 `CronJob` when you set `schedule`.
118 - [`Manifest`](/providers/kubernetes/manifest) and
119 [`HelmChart`](/providers/kubernetes/helmchart) — any raw Kubernetes
120 object or a rendered Helm chart, applied via server-side apply.
121
122 Bindings work the same as on Lambda and ECS — env vars plus IAM
123 policy statements, delivered through an EKS Pod Identity role —
124 and there is no YAML and no `kubectl` step. You pay for the
125 control plane and the nodes Auto Mode provisions, you bring a VPC
126 (the [`Network`](/providers/aws/ec2/network) helper builds one),
127 and the control plane takes ~10 minutes to create.
128
129 → [EKS](/aws/compute/eks)
130
131 For ML training fleets specifically — persistent, health-checked
132 GPU clusters rather than application containers — EKS pairs with
133 [SageMaker HyperPod](/aws/compute/hyperpod): the HyperPod nodes
134 join your EKS cluster, and `Deployment`/`Job` opt onto them with
135 the `hyperpod` prop.
136
137 ## EC2 — when you need the machine
138
139 Full-control VMs for workloads that need an OS, a GPU, custom
140 daemons, or just predictable dedicated capacity. The
141 [`Instance`](/providers/aws/ec2/instance) resource can act as a
142 low-level compute primitive or run a bundled long-lived Effect
143 program directly on the machine (including serving HTTP), and
144 Alchemy ships the complete networking toolkit around it:
145 [`Vpc`](/providers/aws/ec2/vpc),
146 [`Subnet`](/providers/aws/ec2/subnet),
147 [`SecurityGroup`](/providers/aws/ec2/securitygroup), NAT and
148 internet gateways, route tables, EIPs, and VPC endpoints (see
149 [VPC & networking](/aws/networking)).
150
151 You own patching, scaling, and availability.
152
153 → [EC2](/aws/compute/ec2)
154
155 ## Rule of thumb
156
157 1. Start with **Lambda**. Per-request cost, no servers, and the
158 whole documented binding/event-source surface.
159 2. Serve HTTP from a **Lambda Web Function** — streaming responses,
160 many requests per environment, and endpoint-level auth and limits —
161 unless you need a non-Node runtime, a container, or a Region it
162 doesn't run in yet.
163 3. Move a workload to **ECS** when it's long-running, needs more
164 than 15 minutes, or is already a container.
165 4. Pick **EKS** over ECS when you want Kubernetes itself —
166 Helm charts, operators, raw manifests — not just a container
167 runner.
168 5. Reach for **EC2** when you need the machine itself — kernel
169 access, GPUs, custom networking, or software that expects a
170 host.
171
172 ## Where next
173
174 - [Lambda](/aws/compute/lambda) — deploy a function with a public URL.
175 - [AWS overview](/aws) — resources and recipes.
176 - [Providers reference](/providers) — generated docs for every
177 ECS, EKS, and EC2 resource.