Set codeSwap: true on a web service to let stacktape deploy update eligible code inside its running containers. It is off by default and can be used in any stage, including production, within the task cap. Stacktape still builds and pushes an image for every code change, so image fallback and rollback stay available.
Deploy as usual with stacktape deploy --stage production --region eu-west-1. The first deploy installs the supervisor and uses an image rollout. Later code-only changes can swap inside the same tasks. The CLI reports whether it swapped code or used an image deploy, and explains a fallback.
Supported services
Supports several opted-in web services per stack on x86 Fargate, behind the default HTTP API Gateway or an application load balancer (loadBalancing.type: application-load-balancer). Behind the default HTTP API Gateway, WebSocket connections are not possible and SSE responses are buffered; use an application load balancer for them. Node.js uses js-bundle packaging. Dependencies are bundled or kept in an independent generated install in the image; a change to that installed image uses an image deploy. Python uses the standard buildpack path with a complete transitive requirements.txt lock: every dependency must use == and SHA-256 hashes. Generate it with uv pip compile requirements.in --generate-hashes --output-file requirements.txt. The build enforces --require-hashes; an incomplete lock falls back to an image deploy with a CLI explanation. Python swap identity includes a hash of the installed virtualenv, interpreter and system libraries, so a changed installed environment requires an image deploy. Python source swaps run without local/URL dependencies, custom build/install commands or custom Railpack configuration. The startup command must directly run uvicorn, gunicorn or python, without shell command chains or an absolute /app source path. Other Python dependency managers and packaging paths use images. Python and Node.js with installed dependencies currently require local Docker caching; a registry-cache builder uses images. The app must listen on PORT, allow a writable working directory, and keep child processes under its process tree. State that must survive a deploy belongs outside the process and its local release directory.
Configured internalHealthCheck, network load balancers, blue/green deployments, side containers, tracing sidecars, remote sessions, EC2, arm64, source-dependent dependency installs, custom Dockerfiles, prebuilt images, Bun and Deno use image deploys. Remove the opt-in if you only need image deploys. Unsupported combinations do not inherit the qualified runtime's guarantees.
Each service's autoscaling maximum, scheduled overrides and deployment surge must fit within 10 simultaneous tasks. Unknown bounds use images. minimumHealthyPercent must be 100, and surge must allow at least one replacement. With the default 200% maximum, use maxInstances: 5 or fewer. A ten-task desired count with no room for a replacement uses images, even before the first swap. No coordinator admits larger fleets. A custom CloudFormation transform that invalidates the protected role or capacity checks is refused before deployment; correct it or remove the opt-in.
Python bundles the source and assets selected by the buildpack, using the same exclusions as its image. The image keeps the interpreter and virtualenv; each activation starts the buildpack's command from the new release directory. Read application files relative to that working directory. An absolute /app/... path still reads the image's files. Python projects that install their own source or compile it during a build use images.
A deploy prepares every changed service before switching any. If a changed service cannot swap, all changed services use image deploys. A failure during switching also converges all changed services through images. Unchanged services keep their tasks and serving code during ordinary code deploys. Repairing an interrupted operation can replace every opted-in service. Services switch independently after preparation; there is no atomic switch across their public endpoints. Keep ordinary API compatibility between service versions.
Memory and request failures
During a switch, the old and new processes share the task's memory. A sudden increase in the new code's memory use can kill a candidate after it starts serving, failing some in-flight requests. Memory screening and OOM preferences reduce the risk; they do not isolate the processes or guarantee that the old process survives extreme pressure.
Before starting a candidate, each task reads its kernel lifetime peak and checks:
2 × 1.25 × peak + 64 MiB ≤ 0.9 × memory limit
An unknown or unreadable peak, an unsupported memory layout, or a failed screen causes an image deploy. The lifetime peak includes startup, workers, caches and overlap from earlier swaps. A successful swap can therefore raise the peak enough that the next edit uses images. Increase resources.memory (for example, from 512 to 1024 MiB), reduce memory use, or continue with image deploys. A larger limit is not a promise that any new code will fit.
Completion and fallback
A small supervisor owns the HTTP port, starts the candidate, verifies proxy reachability, switches new requests, then waits for the old process to drain and exit. The old process gets up to 65 seconds to finish requests that were already in flight, about the time an image deploy allows (a 35 s HTTP API routing drain or a 30 s load balancer deregistration delay, plus the 30 s default stop timeout). It receives SIGTERM as soon as its last request finishes, so a swap with no open requests does not wait. Requests still open after 65 seconds are closed. The application then has its stopTimeout (default 2 s) to exit before it is killed. Without an authored application check, any complete HTTP response, including 500, counts as reachability. There is no default application health check and no fixed observation window.
Behind an application load balancer, the supervisor also runs the target group's health check. Before the switch, the candidate must answer GET on loadBalancing.properties.healthcheckPath (default /) with status 200 within healthcheckTimeout (default 4 s); it gets up to 30 seconds to pass. The same check runs on the new code right after the switch, every second while the old process drains, and once more before completion. The load balancer's own checks reach whichever process serves, with no gap during the switch. If a check fails, the task switches back to the old process and the deploy uses an image, which the load balancer and ECS then check as usual.
The CLI reports success only after every current task completes, the fleet remains healthy and routable, old process trees exit (except one that only holds long-lived connections), and release history is durable. Candidate failure, OOM, task replacement or fleet changes prevent swap success and trigger image convergence. If candidate cleanup cannot be confirmed, the command fails and the next deploy repairs the service, as described below. A later crash is an ordinary application incident; use your existing monitoring and rollback procedure.
Dependency, environment, runtime, supervisor and base configuration changes use image deploys. --full also forces an image rollout. Scaling without a new task revision keeps the committed code; replacement tasks load that code before reporting ready. Opted-in image rollouts and new tasks pay the ECS supervisor-readiness delay. Normal services without the opt-in keep their existing resources and behavior.
WebSocket and SSE connections
WebSocket connections and Server-Sent Events streams do not delay a swap. Two kinds of connection count as long-lived: a connection upgraded through the HTTP Upgrade mechanism, such as a WebSocket, and a response whose Content-Type is text/event-stream (parameters such as charset are ignored). The supervisor classifies an event stream when its response headers arrive. Every other request counts as ordinary and keeps the old process waiting as described above. This includes streamed text/plain or NDJSON responses (such as AI SDK text streams), long polling, downloads, gRPC and any request whose response headers have not been sent yet.
When only long-lived connections remain, the swap completes and the CLI exits. It reports how many connections still run on the previous code. They stay on the old process until they close or the same 65-second deadline passes, as on an old task after an image deploy. Then WebSocket clients receive close code 1001 (going away), event streams end, and the old process gets its stopTimeout to exit. Clients must reconnect to reach the new code. A browser EventSource reconnects automatically; WebSocket clients need their own reconnect logic.
While the old process holds these connections, it is the first choice of the kernel's out-of-memory killer, and the swap can no longer revert to it. If it crashes or is killed, only its connections end; the swap stays complete. A redeploy within 65 seconds closes the remaining connections early, before the next candidate starts. A task stop closes them at the end of the task's routing drain.
Rollback, disabling and interrupted deploys
Use stacktape rollback to deploy a retained release's exact image as a new task revision. Rollback uses images rather than reversing a swap. Deployment artifact retention follows deploymentConfig.previousVersionsToKeep; the current committed bundle stays available for task replacement. Successful deploys remove status rows for tasks ECS confirms have stopped. Live task status has no expiry.
Set codeSwap: false or remove it, then deploy, to return to image-only operation. stacktape delete also removes the runtime table and code bundles.
A stack runs one deploy, rollback or delete at a time. Once a stack is opted in, the operation holds the stack's lock from its start, because preparing a swap already starts new code in the running tasks. If you interrupt the CLI (Ctrl+C, or a cancelled CI job) before it starts changing the stack, it aborts any prepared swap and releases the lock. After it has started changing the stack, and whenever the CLI is killed, the lock stays until it expires, within two minutes. A command that starts before then waits and names the holder. Once the lock expires, it takes over and repairs an interrupted swap through an image deploy; it never reports the interrupted attempt as a successful swap. If that repair also stops before it finishes, the following command repairs the swap the same way.
The application has permission to write its own supervisor status. A malicious application can forge its own completion and cause a false success report. It cannot write the release record or another task's status. Code bundles, images, release records and task status stay in your AWS account; this feature adds no external data service.