stacktape init reads the project you already have and writes a Stacktape configuration for it.
It opens a wizard in your browser and reads your code on your machine using a coding agent you already have installed — Claude Code or Codex. It does not interview you: where your code does not say, it picks the sensible answer, then shows you what it picked and the line behind every resource it proposes, so you can change any of it. No source, filenames, or configuration contents are sent to Stacktape, and no account is needed.
To be precise about where your code goes: an agent works the way it always does — it sends the file contents it chooses to read to its own model provider, under the account you already have with it, with read-only tools (it cannot run scripts or install anything). If you would rather no AI read the code at all, pick Files only — the built-in scanner reads manifests locally and sends nothing anywhere.
Usage
Run it in the directory of the project you want to deploy. The command prints a http://127.0.0.1:…
address and opens it; the wizard runs there and the terminal keeps the session alive until you close it
with Ctrl+C.
What happens, in order
- Start. The wizard opens with nothing read yet. It shows which directory it will read and which agents it found, and waits. Reading starts when you press the button — never before.
- Read. The agent opens files and you watch it happen: every file it reads appears as it reads it. Only the names of your environment variables are ever kept or shown. Before the agent starts, a deterministic pass has already read the manifests that state the deployment most clearly: Docker Compose, Dockerfiles and Procfiles; Render, Fly.io and Heroku app manifests; and literal declarations in Serverless Framework, SAM, SST, CDK and Terraform. It also notices when one of those tools already deploys the project.
- Review. Every resource, with the reason it exists, the line of your code behind it, and what it costs — a real monthly estimate per resource and in total, priced from AWS list prices. Anything the code could not settle was decided for you, listed under "Decided for you", and can be changed with one click — the configuration is rebuilt from your choice, and the price updates with it. Nothing blocks. You choose YAML or TypeScript, and the file is written.
- Try it locally (optional). With your explicit click, the wizard can build and start supported services in Docker. Building may download dependencies and run their install hooks. The started app receives throwaway settings and has no network. Every result says whether the service passed, failed, was inconclusive, or could not be checked. A proven startup failure holds the Deploy button until you fix it or explicitly set the result aside; a skipped check is never shown as a pass.
- Deploy. The wizard checks that the CLI is signed in to Stacktape. The first click is read-only:
a short-lived CLI process resolves the same connected AWS account or profile that deploy will use,
then shows the exact account, region and stack name. You separately confirm creating a new stack or
updating a specific existing Stacktape stack. Foreign, mismatched and unsafe stacks are blocked. The
deploy child checks that target again before it creates secrets or changes AWS, then reports progress,
warnings and typed HTTPS URLs. This step is optional and clearly marked as the one that costs money.
If your Stacktape organization has multiple connected AWS accounts and no saved default, start with
stacktape init --aws-account <account-name>. That account selection is carried through the target check, deploy, and typed URL lookup. If the deploy fails for a reason that could be our reading of your code — a wrong start command, a missing build step — the agent re-reads the project against the actual error, the configuration is rebuilt, and the deploy runs again. At most twice, and never for problems with the AWS account itself.
Who reads your code
init drives a coding agent that is already installed and already paid for — your subscription, your
machine. It never sends your code to Stacktape.
The preview has no Stacktape-hosted AI fallback. If neither local agent is available, the No agent mode below performs deterministic file analysis instead of uploading source or snippets elsewhere.
| Agent | How it is used |
|---|---|
| Claude Code | Every built-in tool is switched off; the only tools it has are the ones Stacktape gives it, all read-only. You can pick the model. |
| Codex | Runs read-only in a scratch working directory, because its patch tool cannot be disabled. |
| No agent | Reads package manifests, Compose, Dockerfiles, Procfiles, Render/Fly.io/Heroku manifests, supported IaC declarations, lockfiles, environment-variable names, and whatever already deploys the project. Free, instant, and leans on defaults more often. |
An imported deployment file describes what the project expects; it does not give init access to
the provider account or prove that the deployment is currently running. The Review step says when it
found such a file. A Stacktape deploy creates a separate stack: it does not take over, change or delete
resources managed by the existing tool.
The agent cannot write to your repository, cannot reach the network through us, and cannot put words in front of you: it reports findings from a fixed list of kinds, and every word you read in the wizard is written by Stacktape.
Important flags
--coding-agent
Which agent reads the project. auto (the default) takes the best one installed. Naming one that is not
installed fails rather than quietly using another.
--headless
Runs the whole thing in the terminal instead of opening a browser. Use it over SSH, in a container, or in CI. Nothing prompts: the terminal prints what was decided for you, and the configuration is written.
--no-browser
Starts the wizard and prints its address without opening anything. Use it when the browser you want is not this machine's default, or when the port is forwarded from somewhere else.
--infrastructure-type
How much infrastructure to create: low-cost, standard (the default), or production. It sets every
size and safety setting in the generated configuration, and it is the only thing reading your code
cannot tell us.
- low-cost — one small copy of everything. Trying it out, a side project, staging.
- standard — room for real traffic, a week of backups, deletion protection on your database.
- production — two copies of your app so one failure changes nothing, and a standby database in a second datacentre.
--config-format
yaml (the default) or typescript. In the browser this is chosen on the Review step instead, once you
have seen what is in the file.
--project-directory
The project to read. Defaults to the current directory.
--starter-id, --starter-project
Initialize from a ready-made project instead of reading yours. These skip the wizard entirely.
--initialize-project-to
Where a starter project's files are placed.
If the directory is not empty, its contents are deleted first. Point it at a new or empty directory.
Existing and generated configuration files
Init preserves stacktape.yml, stacktape.yaml and stacktape.ts. When one exists, it writes stacktape.generated.yml or .ts beside it, replacing any previous file at that generated path. Review or save edits to an existing generated file before rerunning init. For a TypeScript config in a project with package.json, init also adds or updates the stacktape dependency to match the CLI and prints the install command; it does not run the package manager. Deploy the generated config with --config, or merge it yourself:
Examples
Read the project with Claude Code's most careful model:
No agent, no browser, cheapest infrastructure — a configuration in one step:
Related commands
deploy— deploy the configurationinitwrote.dev— run the project locally against a minimal dev stack.delete— remove everything a deploy created.
init FAQ
Does my code leave my machine?
If you choose Claude Code or Codex, that local agent sends the file contents it selects to its own model provider under your account, just as it normally does. Stacktape receives no source, file names, or configuration contents. If you choose Files only, no AI provider receives code either.
Stacktape does receive anonymous outcome statistics — which frameworks were detected, whether the
deploy succeeded, how long the analysis took — so we can see where generation fails and fix it. Set
STP_DISABLE_TELEMETRY=1 to turn that off. What the CLI sends
lists everything else.
What about my .env files?
Only the names are kept. DATABASE_URL tells the analysis that a database exists — and its value is
looked at once, in memory on your machine, for two things and two things only: whether the scheme says
postgres:// or mysql://, and whether the host belongs to a provider like Supabase, so we do not
propose replacing a database that is already live. Both reduce to a single word before anything is
stored. The value itself is never written to the facts, never quoted in a citation, never logged and
never shown — every citation from an environment file stops at the =.
Do I need an AWS account before running init?
Not to run it. You need one to deploy. The wizard can use local AWS credentials or an AWS account connected to your Stacktape organization. Before any AWS change it resolves the same credentials the deploy command will use and shows the exact account, region and stack target for confirmation.
Do I need a Stacktape account?
Not to analyze your project or to get the file — that all happens on your machine, with no account
and nothing sent to us. Deploying from the wizard does go through Stacktape, so the Deploy step
checks whether this machine is signed in and tells you to run stacktape login if it is not.
What does “Try it here first” run?
Only after you click it, init runs your project's build and start commands using disposable Docker
images and containers. The image build may access the network to download dependencies and may run
package-manager install hooks from the project. The started application receives throwaway values
instead of your secrets and has no network access. This is not supported for every packaging and
resource type yet: the wizard labels each service Passed, Failed, Inconclusive, or Not
checked and never presents a skipped check as proof. Docker is optional; if it is missing, your
generated file is unaffected and the wizard says that AWS would be the first full run.
How do I run init non-interactively, in CI or from an AI coding agent?
--headless, optionally with --agent for JSONL output. Nothing prompts: everything the code cannot
answer is decided, and the terminal prints what was decided.
Why does it barely ask me anything?
Because almost nothing needs asking. Where your code does not say, there is nearly always an answer a careful person would pick — so it picks it, shows you on the Review step, and lets you change it. The one real question is how big the infrastructure should be, which is why it is shown alongside the resources and monthly estimate on the Review step.
Which agent should I choose?
Whichever you already have. Claude Code and Codex both produce a better result than static analysis, because they read the code rather than pattern-matching over it. If you have neither, "Files only" still produces a working configuration — it just falls back to defaults more often.
What happens when the deploy fails?
The failure is read first. If it is about your AWS account — expired credentials, a missing permission, a quota — it is shown to you plainly, because no change to the configuration can fix it. If it could be about the code, the same agent that read your project reads it again with the actual error in hand, corrects what we believed, and the deploy runs again with the rebuilt configuration. The wizard names exactly which resources the repair rewrote, and the file in your project is always the version that deployed. It stops after two repairs and shows the real error rather than looping. If you chose "Files only", nothing is ever handed to an agent — the deploy just fails, plainly.
Does init deploy anything?
Only after two explicit actions on the last step: a read-only target check, then confirmation to create the absent stack or update the exact existing StackId that was shown. The deploy child repeats that check and stops if the account, region, name, ownership, status or StackId changed. Everything before the final confirmation is a file on your disk or a read-only AWS check.
Will init overwrite files in my project?
Init preserves canonical config files but can replace a previous stacktape.generated.yml or .ts and update the stacktape dependency in package.json; see existing and generated configuration files. The --initialize-project-to flag empties the target directory before placing a starter project there.