Use the Dev Mode

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:

stacktape dev --stage dev --region eu-west-1

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:

stacktape dev --stage dev --region eu-west-1 --resources all

To run only specific resources:

stacktape dev --stage dev --region eu-west-1 --resources myApi,myDatabase

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 typeWhere it runsHow changes work
Container workloads (web-service, private-service, worker-service, multi-container-workload)Docker on your machineRebuilt on file change (with --watch) or manually (rs command)
Lambda functionsPackaged locally and code updated on AWSRepackaged 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 serverAutomatic hot reload via the framework's built-in HMR
Hosting buckets (with dev config)Local dev serverAutomatic hot reload
Databases (PostgreSQL, MySQL, Redis, DynamoDB, OpenSearch)Docker-backed local emulatorsPersistent 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:

export default defineConfig(() => {
  const myDatabase = new RelationalDatabase({
    credentials: {
      masterUserPassword: "$Secret('database', 'password')"
    },
    engine: new RdsEnginePostgres({
      version: '16',
      primaryInstance: { instanceSize: 'db.t4g.micro' }
    })
  });

  const api = new LambdaFunction({
    packaging: new JsBundleLambdaPackaging({
      entryfilePath: './src/handler.ts'
    }),
    connectTo: [myDatabase],
    environment: { STAGE: '$Stage()' }
  });

  return {
    resources: { myDatabase, api }
  };
});

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:

  1. Starts a local PostgreSQL emulator (Docker container on your machine)
  2. 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
  3. Injects environment variables so your code can connect — for a database resource named myDatabase, the connection string is available as STP_MY_DATABASE_CONNECTION_STRING

Now edit ./src/handler.ts, save, and either:

  • With --watch flag: Stacktape detects the change and automatically repackages and updates the Lambda code
  • Without --watch: Type rs and 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:

stacktape dev --stage dev --region eu-west-1 --resources all --watch

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 typeLocal emulator type
PostgreSQL / Aurora PostgreSQLpostgres
MySQL / Aurora MySQLmysql / mariadb
Redisredis
DynamoDBdynamodb
OpenSearchopensearch

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):

stacktape dev --stage dev --region eu-west-1 --fresh-db

To skip local emulation and connect to an already-deployed database on AWS:

stacktape dev --stage dev --region eu-west-1 --remote-resources myDatabase

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:

CommandAction
rsRebuild all workloads
rs myApiRebuild a specific workload
c or clearClear the log output
q or quitStop 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.

FlagDescription
--resourcesWhich resources to run (all or comma-separated names)
--skip-resourcesExclude specific resources
--watchAuto-rebuild on file changes
--fresh-dbDelete local database data before starting
--remote-resourcesConnect to deployed AWS resources instead of local emulation
--no-tunnelPrevent 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:

stacktape dev --stage dev --region eu-west-1 --resources all --agent

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 workloads
  • stacktape 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.