The stacktape dev command runs containers, frontends and supported database emulators on your machine. Lambda functions and Batch jobs run in AWS. Dev mode injects connection settings and credentials into workloads and streams their logs while you iterate on code.
Usage
stacktape devCLI options-r, --regionrequired"us-east-2" | "us-east-1" | "us-west-1" | "us-west-2" | "ap-east-1" | "ap-south-1" | "ap-northeast-3" | "ap-northeast-2" | "ap-southeast-1" | "ap-southeast-2" | "ap-northeast-1" | "ca-central-1" | "eu-central-1" | "eu-west-1" | "eu-west-2" | "eu-west-3" | "eu-north-1" | "me-south-1" | "sa-east-1" | "af-south-1" | "eu-south-1"AWS Region
The AWS region for the operation. For a list of available regions, see the AWS documentation.
Inside a project whose config declares region, the flag is optional and overrides the config.
-s, --stagerequiredstringStage
The stage for the operation (e.g., production, staging, dev-john). You can set a default stage using the defaults set command. Stage names use lowercase letters, numbers and dashes, with at least 2 characters. The project name, a dash and the stage form the CloudFormation stack name, which can have at most 128 characters. Stacktape shortens an AWS resource name that would be too long and adds a hash.
--agentbooleanAgent Mode
For coding agents: runs dev mode in the background with a local HTTP API for status, logs, rebuilds and database queries.
The command returns once the session is ready. Its result names the API port, the token file and the log file, and the session keeps running until stacktape dev stop. Agent mode does not confirm anything: when the project does not exist yet, creating it fails with CONFIRMATION_REQUIRED unless you add --yes. See Agent mode in dev.
--agent-portnumberAgent Port
The port of the agent mode HTTP API. Implies --agent. By default, the first free port from 7331.
-y, --yesbooleanAuto-Confirm Operation
Confirms an operation that would otherwise ask first: deleting a stack, an update that may delete stateful resources, creating a project that does not exist yet, and the other deletions that ask.
Without a terminal to ask in (CI, --agent, machine-readable output), such an operation fails with CONFIRMATION_REQUIRED unless this flag is set. --agent does not confirm anything.
--aws-accountstringAWS Account
The name of the AWS account to use for the operation. The account must first be connected in the Stacktape Console.
Without it, the account is chosen by --profile, AWS_PROFILE or AWS credentials in environment variables, then by your saved default, then by your organization's only connected account. --aws-account takes precedence over all of them, but AWS credentials in environment variables must then belong to that account.
-c, --configstringConfig File Path
The path to your Stacktape configuration file, relative to the current working directory.
Without it, Stacktape uses the one stacktape.ts, stacktape.yml, stacktape.yaml or stacktape.js in the working directory. When there are several, the command stops and asks you to choose one with this option.
--cwdstringCurrent Working Directory
The working directory for the operation. All file paths in your configuration will be resolved relative to this directory. By default, this is the directory containing the configuration file.
--no-emulationbooleanDisable Emulation
Affects selected local directive-resolution behavior. Dev mode still deploys its AWS dev stack and uses normal container role credentials and connection variables; this flag does not make it offline or suppress credential injection.
--docker-argsarrayDocker Arguments
Additional arguments to pass to the docker run or docker build commands.
--fresh-dbbooleanFresh Database
If true, deletes data, schema and local credential/identity files for databases prepared during startup, including unselected relay dependencies. Other persisted databases are untouched. DynamoDB Local shares storage: resetting it removes every persisted table there. The stage password can be reused.
-h, --helpstringShow Help
If provided, the command will not execute and will instead print help information.
--log-level"info" | "debug" | "error"Log Level
The level of logs to print to the console.
info: Basic information about the operation.error: Only errors.debug: Detailed information for debugging.
--no-tunnelbooleanNo Tunnel
Disables tunnels from deployed Lambda functions to your locally emulated databases. Without this flag, functions that use a local database reach it through the dev box of your account's dev network, over an encrypted AWS Systems Manager session from your machine. With it, they cannot reach local databases; use --remote-resources to connect them to the deployed databases instead. VPC functions still run in the dev network.
--keep-temp-filesbooleanPreserve Temporary Files
If true, preserves the temporary files generated by the operation, such as the CloudFormation template and packaged resources. These files are saved to .stacktape/[invocation-id].
-p, --profilestringAWS Profile
The AWS profile to use for the command. You can manage profiles using the aws-profile:* commands and set a default profile with defaults set.
For commands that use a connected AWS account, --profile (or AWS_PROFILE) selects the connected account the profile belongs to, unless --aws-account is set. The command fails if that account is not connected.
--projectstringProject Name
The name of the Stacktape project for this operation.
Commands that target a stack take it from projectName in the project's config when the flag is absent.
--quietbooleanQuiet
Hide progress, banners, success messages and hints. Command output, warnings and errors are still printed.
--remote-resourcesarrayRemote Resources
Databases and Redis run locally by default. Use this flag to connect selected resources to their deployed AWS counterparts instead. Useful when you need to test against real data or when local emulation is insufficient. Examples: --remote-resources myDb, --remote-resources postgres,redis.
--resourcesarrayResources
Specify which resources to run in dev mode. Select functions, local containers, frontends and emulated databases. Batch jobs run in AWS and cannot be selected or skipped. Unselected functions remain in the dev stack without configured triggers. Selection limits session rebuild/watch. A dev-stack update does not build unselected functions: they keep the code they run, and status lists them with when that code was deployed. They are built when the dev stack has no code for them yet or their configuration changed, and then an unselected function that does not build fails the start. If not provided, an interactive picker is shown. Use all to run all resources without prompting. Examples: --resources myApi, --resources myApi,myDb, or --resources all.
--skip-resourcesarraySkip Resources
Exclude selectable functions, local containers, frontends and emulated databases from dev mode. Unselected functions remain deployed without their configured triggers. Selection limits session rebuild/watch. A dev-stack update does not build unselected functions: they keep the code they run, and status lists them with when that code was deployed. They are built when the dev stack has no code for them yet or their configuration changed, and then an unselected function that does not build fails the start. Batch jobs cannot be skipped with this flag. All other compatible resources will run. Useful when you want to run most resources but exclude a few. Examples: --skip-resources myHeavyDb, --skip-resources fn1,fn2.
--take-overbooleanTake Over
Moves a stage that another stacktape dev session runs, on another machine or in another terminal, to this session. Without this flag, stacktape dev refuses to start a stage that runs elsewhere. With it, deployed functions reach the databases on this machine, their open database connections to the other session are closed, and the other session stops itself.
--watchbooleanWatch
If true, rebuilds a function or container when one of its source files changes: functions are redeployed to the dev stack and containers restart with the new build.
Frontend dev servers reload on their own. A change to the configuration file that a rebuild cannot apply is reported as needing a restart.
What it does
The dev command deploys a dev stack to AWS. It includes Lambda functions, Batch jobs and configured cloud resources allowed by the dev deployment policy, such as gateways, queues, topics and buckets. Selecting workloads does not limit all cloud resources to their dependencies. The dev stack has no alarms: errors you cause on purpose while developing do not notify anyone.
- Runs containers and frontend workloads locally; Lambda functions and Batch jobs execute in AWS
- Emulates databases (PostgreSQL, MySQL, MariaDB, DynamoDB, OpenSearch) and Redis locally using Docker
- Keeps local databases on your machine, published on
127.0.0.1only; deployed Lambda functions and Batch jobs reach them through the dev network. Use--remote-resourcesfor deployed database connections - Creates the dev stack automatically on first run — no pre-deployment required
- Injects environment variables, secrets, and AWS credentials into local workloads
Supported resource types
The dev command can run the following resource types locally:
| Category | Resource types |
|---|---|
| Containers | web-service, private-service, worker-service, multi-container-workload |
| Frontends | nextjs-web, astro-web, nuxt-web, sveltekit-web, solidstart-web, tanstack-web, remix-web, hosting-bucket (with dev config) |
| Databases (locally emulated by default) | PostgreSQL, MySQL, MariaDB, DynamoDB, Redis, OpenSearch |
Important flags
--resources / --skip-resources
Select Lambda functions, local containers, frontends and emulated databases. Without these flags, an interactive picker appears. Unselected functions remain in the dev stack with their configured triggers removed. Selection limits session rebuild/watch. A dev-stack update does not build unselected functions: they keep the code they run, which may not match your source, and status lists them with when that code was deployed. They are built when the dev stack has no code for them yet or their configuration changed, and then an unselected function that does not build fails the start. Batch jobs cannot be selected or skipped: they run in AWS when triggered, and their images update only when dev mode starts. Use a dev-specific configuration to omit a job or disable its triggers.
Run all resources without prompting:
Run only specific resources:
Run everything except a heavy database:
--watch
Enables automatic file watching. When source files change, Stacktape automatically re-executes the affected compute resource.
--remote-resources
Databases and Redis run locally by default. Use --remote-resources to connect selected resources to deployed AWS resources instead. This is useful when you need to test against real data or when local emulation is insufficient.
--fresh-db
Deletes data, schema and local credential/identity files for databases prepared during startup, including deployed-workload relay dependencies that may be unselected. Other persisted databases are untouched. DynamoDB Local shares storage across tables, so resetting it removes every persisted table in that storage. See reset scope.
--no-tunnel
Skips the tunnels from deployed Lambda functions to local databases. Without it, functions that use a local database reach it through the dev box of your account's dev network; see Connecting to local databases. VPC functions still run in the dev network.
--take-over
Moves a stage that another stacktape dev session runs, on another machine or in another worktree, to this session. Without it, stacktape dev refuses to start a stage whose deployed functions already reach another session's databases, and names that session. With it, the functions reach the databases on this machine, their open database connections to the other session are closed, and the other session stops itself with a message that names this one, so it cannot redeploy functions over yours.
--no-emulation
--no-emulation affects selected local directive-resolution behavior. Dev mode still deploys its AWS dev stack and uses the normal container role-credential and connection-variable paths. This flag does not make dev mode offline or suppress credential injection.
--agent / --agent-port
The --agent flag runs dev mode as a detached daemon and enables the agent HTTP server for programmatic control. Agent mode is intended for programmatic/LLM consumption and AI coding-agent workflows. The daemon spawns in the background and the parent process exits after confirming the agent is ready.
Agent mode does not confirm anything. When the project named with --project does not exist yet, dev --agent fails with CONFIRMATION_REQUIRED before it deploys. Check the name and run it again with --yes to create the project:
Providing --agent-port also enables agent mode, so --agent is optional when you pass a port. Use --agent-port to specify a custom port for the agent HTTP server:
Stop a running agent with dev stop.
Interactive commands
While running in interactive mode, you can control dev mode with the following text commands:
| Command | Action |
|---|---|
rs | Rebuild all workloads |
rs <name> | Rebuild a specific workload by name |
q or quit | Stop dev mode and exit |
c or clear | Clear the log output |
Examples
Basic dev mode with file watching:
Run only the API function and database, skip everything else:
Run locally but connect to a deployed database instead of emulating it:
Start a dev agent for AI coding assistant integration:
Start with a fresh database (deletes existing local data):
dev FAQ
Does stacktape dev require Docker?
Dev mode uses Docker to emulate databases (PostgreSQL, MySQL, MariaDB, DynamoDB, OpenSearch) and Redis locally. You need Docker installed and running for local database emulation. If you use --remote-resources for all databases, Docker is not required for database emulation, though container workloads may still use it for local builds.
When should I use stacktape dev vs stacktape deploy?
Use stacktape dev for iterating on code locally with fast feedback loops — it runs workloads on your machine and emulates databases without a full deployment cycle. Use stacktape deploy when you need to ship to AWS, test in a real cloud environment, or validate production behavior. Dev mode is for development; deploy is for staging, production, or integration testing.
How can I connect to a real deployed database instead of the local one?
Use --remote-resources with a comma-separated list of resource names (for example --remote-resources myPostgres,myRedis). Databases and Redis run locally by default; this flag points the selected ones at their deployed AWS counterparts when local emulation is insufficient or you need to test against real data.
What is agent mode and when should I use it?
Agent mode (--agent) runs dev mode as a detached daemon with an HTTP server for programmatic control. It uses JSONL output and disables the interactive terminal UI. Use agent mode when integrating with AI coding agents, automation tools, or any workflow that needs to control dev mode programmatically. Stop a running agent with dev stop.
Why does stacktape dev stop with "Free Plan Limit Reached"?
Dev mode deploys and updates a dev stack in your AWS account, so it follows the same
Free plan cost limit as
stacktape deploy. When a Free organization's managed AWS costs this month are
above $100, dev mode stops before it creates or deploys anything and prints the costs and the upgrade link. Upgrading
to the Flexible plan lifts the limit immediately. Running infrastructure is not affected, and
dev stop and delete keep working.
Related commands
dev stop— stop a running dev agentdev network— see or delete the dev network that connects deployed functions to local databasesdeploy— deploy your stack to AWSlogs— fetch logs from deployed resources