Stacktape dev mode runs your workloads locally while connecting them to real or locally emulated AWS resources. Container workloads run in Docker, databases start as local emulators, SSR frontends use their native dev servers, and Lambda function code is built and pushed to AWS. Edit code, save, and see results without redeploying.
Already familiar with dev mode? Skip ahead to Deploy your first stage.
What you need
You should have a stacktape.ts from step 1. You also need:
- Docker running on your machine — needed for container workloads and local database emulation. Not required if your config only has Lambda functions without locally emulated databases
- Stacktape CLI installed (
npm install -g stacktape) - An AWS account connected — dev mode initializes AWS credentials and deploys a dev stack when one does not already exist
Start dev mode
Start Stacktape dev mode from the directory containing your stacktape.ts:
On first run, Stacktape deploys a lightweight dev stack to AWS (IAM roles, secrets, and routing needed for local development). Unchanged starts reuse it. A restart can update the stack after cloud configuration or cloud-image changes, or when required outputs are missing.
An interactive picker lets you choose which resources to run. To skip the picker and run everything:
To run only specific resources:
Dev mode watches your stacktape.ts. Code changes are rebuilt, but a configuration change (new resources, environment variables, connections) needs a restart: dev mode tells you so and refuses rebuilds until you restart it. The restart updates the dev stack with the new configuration.
When multiple developers work on the same project, use a unique stage name per developer (e.g., --stage dev-alice, --stage dev-bob). Each stage gets its own dev stack and local data directory.
What runs where
Stacktape dev mode splits your stack between local execution and AWS, depending on resource type:
| Resource type | Where it runs | How changes work |
|---|---|---|
| Container workloads (web-service, private-service, worker-service, multi-container-workload) | Docker on your machine | Rebuilt on file change (with --watch) or manually (rs command) |
| Lambda functions | Packaged locally and code updated on AWS | Repackaged and updated on file change or manual trigger; logs stream to your terminal |
| SSR frontends (Next.js, Astro, Nuxt, SvelteKit, SolidStart, TanStack Start, Remix) | Local dev server | Automatic hot reload via the framework's built-in HMR |
Hosting buckets (with dev config) | Local dev server | Automatic hot reload |
| Databases (PostgreSQL, MySQL, Redis, DynamoDB, OpenSearch) | Docker-backed local emulators | Persistent data in .stacktape/dev-data/{stage}/ |
Lambda functions have their code built and pushed to AWS, where they run. They reach the databases running on your machine through the dev box of your account's dev network (see Connecting to local databases); use --remote-resources to connect them to deployed databases instead. Logs from Lambda invocations stream directly to your terminal.
A container workload counts as running once its port accepts connections, so a test started when dev mode reports it ready reaches the app. All local DynamoDB tables run in one DynamoDB Local, and workloads, local scripts and frontends connected to them get AWS_ENDPOINT_URL_DYNAMODB, so unchanged AWS SDK code uses the local tables.
The edit-save-see loop
The edit-save-see loop is the core Stacktape dev mode workflow. Here is an example config that shows a typical setup:
The version property selects the PostgreSQL engine version and the local Docker image, subject to the adapter's supported tag mapping. The AWS instanceSize controls the deployed RDS compute tier; it does not size the local Docker database. See relational databases for supported versions and sizing.
With this config, running stacktape dev --stage dev --region eu-west-1 --resources all:
- Starts a local PostgreSQL emulator (Docker container on your machine)
- Builds and updates the Lambda function code on AWS. The function runs in AWS and reaches the local database through the dev box, a small EC2 instance in your account's dev network. To use the deployed database instead, run with
--remote-resources myDatabase: the dev stack then includes the database, and the function connects to it - Injects environment variables so your code can connect — for a database resource named
myDatabase, the connection string is available asSTP_MY_DATABASE_CONNECTION_STRING
Now edit ./src/handler.ts, save, and either:
- With
--watchflag: Stacktape detects the change and automatically repackages and updates the Lambda code - Without
--watch: Typersand press Enter in the terminal to trigger a rebuild
For SSR frontends (Next.js, Astro, etc.), changes are picked up instantly through the framework's built-in hot module replacement — no rebuild step needed.
Enable file watching
Stacktape dev mode can automatically rebuild workloads when source files change. Add --watch to enable this:
Container workloads are rebuilt and restarted. Lambda functions are repackaged and updated on AWS. Frontends handle their own watching natively regardless of this flag.
Local database emulation
Stacktape dev mode starts Docker-backed local emulators for supported database resources:
| Config resource type | Local emulator type |
|---|---|
| PostgreSQL / Aurora PostgreSQL | postgres |
| MySQL / Aurora MySQL | mysql / mariadb |
| Redis | redis |
| DynamoDB | dynamodb |
| OpenSearch | opensearch |
Database data persists between sessions in .stacktape/dev-data/{stage}/. This means you can stop and restart dev mode without losing your test data.
To reset databases prepared at startup, including relay dependencies (DynamoDB Local tables share storage; see reset scope):
To skip local emulation and connect to an already-deployed database on AWS:
Environment variables
Stacktape dev mode injects STP_* environment variables into local workloads, pointing to local endpoints. For a resource named myDatabase, the connection string is available as STP_MY_DATABASE_CONNECTION_STRING. The exact host and port values are assigned by dev mode at startup and visible in the dev-mode TUI output.
For connected resources, dev mode keeps the same STP_* environment variable names while pointing them at local or AWS endpoints depending on how the resource is run. Other database parameters (host, port, database name) are available via the $ResourceParam() directive when needed.
Terminal commands
Stacktape dev mode accepts interactive commands while running. Type a command and press Enter:
| Command | Action |
|---|---|
rs | Rebuild all workloads |
rs myApi | Rebuild a specific workload |
c or clear | Clear the log output |
q or quit | Stop dev mode |
Useful flags
The stacktape dev command accepts flags to control which resources run, how rebuilds work, and whether databases are emulated locally or connected remotely.
| Flag | Description |
|---|---|
--resources | Which resources to run (all or comma-separated names) |
--skip-resources | Exclude specific resources |
--watch | Auto-rebuild on file changes |
--fresh-db | Delete local database data before starting |
--remote-resources | Connect to deployed AWS resources instead of local emulation |
--no-tunnel | Prevent deployed functions from receiving local-database relay variables. Stacktape normally manages the dev-box connection; VPC functions still use the dev network. Use --remote-resources for deployed database connections |
Run stacktape help dev to see all available flags and their short aliases.
Agent mode
Stacktape dev mode includes an HTTP API for programmatic control — useful when working with AI coding assistants like Claude Code, Codex or Cursor. Pass --agent to start it as a background daemon:
The agent server starts on port 7331 by default (or the next available port). See Agent mode in dev for the full endpoint reference and usage guide.
Debugging
Stacktape provides CLI commands for inspecting logs and metrics from your running resources, both during dev mode and against deployed stacks:
stacktape logs— Stream or search logs from your Lambda functions and container workloadsstacktape metrics— View CloudWatch metrics for any resource
For deeper coverage of debugging workflows, see Dev mode overview.
Next step
Your code works locally. Time to ship it.