stack setup
Reconcile the project: report, confirm, apply
stack setup
Show the same report as stack doctor, decide pending
adoption offers, preview what adopting them generates, then apply everything
after confirming. Think terraform apply: it shows the plan first.
On a directory that is not a stackpanel project yet, setup first writes the
scaffolding (flake.nix, .envrc, .stack/) from the stackpanel flake's
lib.initTemplates.<template> - the same file set nix flake init -t copies -
and registers the project with the agent. Existing files are left alone unless
--force. With a unified reconciler there is no difference between
initializing a project and reconciling one from empty, so this command replaces
the former stackpanel init.
The flow
- Diagnose. Every reconciler runs read-only:
scaffold,codegen,files,fileops,checks,addons,register. The report is rendered. - Decide offers. Each pending adoption offer is asked once (or answered by
--yes,--with,--without,--addon). Declining records "shown, said no" in.stack/reconcile.jsonand writes nothing else. - One speculative evaluation. The accepted config mutations are overlaid
on the module system and the resulting
files.entriesare diffed against disk. One evaluation for the whole accepted set, none if nothing was accepted. Pure: nothing is written or built. - Confirm, then apply: scaffolding and registration, generated files,
file ops, then the config mutations. When a mutation was written, the new
generation's
write-filesand preflight manifest are realized withnix buildand run, so the adopted module's files materialize without re-entering the shell.
Adoption is one-way: the reconciler cannot undo it, because config is the
input that decides what the reconciler does. Undoing adoption is an edit of
.stack/config.nix.
Usage
stack setup # interactive
stack setup --yes # take every default, no prompts
stack setup --json # print the plan, apply nothing
stack setup --only files # reconcile generated files only
stack setup --with playwright # accept an offer without prompting
stack setup --without editorconfig # decline an offer without prompting
stack setup --addon deploy=fly # answer a select offer explicitly
stack setup --reconsider # re-offer declined addons
stack setup --flake path:/path/to/sp # scaffold from a local checkout
stack setup --tmp # scaffold into a temporary git repo
stack setup --experimental-agent=auto # discover an installed coding agent
stack setup --experimental-agent=codex --yes # accept its onboarding plan automaticallyExperimental agent onboarding
Embedded Pi Go experiment
Use the pinned sky-valley/pi Go library directly, without launching an agent
CLI. Select a provider/model explicitly and supply its API key in the environment:
# OPENAI_API_KEY must be set in your environment (API usage is metered).
nix run .#stackpanel-go -- setup --experimental-agent=pi \
--agent-model=openai/gpt-5 --tmp --template minimal --restart
# Alternatively, set ANTHROPIC_API_KEY and select an Anthropic model.
stack setup --experimental-agent=pi --agent-model=anthropic/claude-sonnet-4-5Pi reuses the same questions, plan review, deterministic doctor, and Studio
connection flow. Its conversation and tool results are checkpointed into the
private setup manifest; rerun the same command to resume. --restart discards
the conversation and reviews a fresh plan. The current setup instructions are
supplied as a system prompt instead of repeated in each saved user message.
This experiment exposes Pi's read, ls, write, and edit tools, confined
to the repository, with checks for symlinks and private state. It does not
expose shell tools or load Pi hooks, skills, or parent configuration
automatically. These checks are application policy, not an OS sandbox.
Stackpanel runs Nix and doctor on the host.
The Go port currently requires Go 1.26 and does not implement Codex subscription
transport or OAuth login. This backend reads OPENAI_API_KEY or
ANTHROPIC_API_KEY; it never imports subscription tokens or saves API keys in the
manifest. Choose --experimental-agent=codex or claude explicitly to fall back
to an installed CLI. Plain auto retains CLI discovery; auto with
--agent-model selects Pi. There is no automatic backend switch after edits.
Installed CLI backends
--experimental-agent delegates repository inspection and configuration to an
installed coding agent, then checks the result with stack doctor. Codex and
Claude Code are supported. Setup checks that the CLI runs, but not that it is
signed in; sign in to the chosen CLI before running setup. Its configured model
and authentication are reused.
With auto, a single installed agent is selected automatically. Multiple agents
produce a picker in an interactive terminal; noninteractive runs use the first
one found (Codex). --yes and --non-interactive accept the proposed
onboarding plan.
The wizard runs full screen, centered in the terminal, and uses the CLI's shared terminal theme, with a stage indicator, elapsed time, and a scrollable plan. Use arrow keys to choose, Space to toggle multiple selections, and Enter to continue. Text answers support cursor editing and paste. PgUp/PgDn scroll the plan while Apply, Revise, and Cancel remain visible. Ctrl+D shows recent agent activity during setup; Esc or Ctrl+C cancels. When the wizard closes, the terminal returns to its previous contents, followed by the outcome and any warnings.
The wizard asks questions when choices are unresolved and lets you apply, revise,
or cancel a concrete plan. Question rounds preserve previous answers. --yes and
noninteractive runs take each question's default; a question without one is
left for the agent to decide. Full provider event logs are available through
--agent-log /path/to/new-log.jsonl (created privately, never overwritten). On
resume, an existing log is preserved and a new sibling .resume-*.jsonl log is
created.
Agents are not held to an exact reply format. Setup reads the first usable JSON object in a reply, including one wrapped in prose or Markdown fences or cut off before its last braces, and drops plan entries it cannot use, such as a command outside the repository. If an inspection reply contains no JSON at all, its text becomes the plan summary for you to review. A write turn's reply only reports what the agent did; doctor checks the result either way.
The agent first inspects the repository without writing and returns a plan,
which you review. After you accept it, Stackpanel writes any missing scaffold
files from the already-fetched template, and the agent makes the changes. It
may edit any file in the repository, including existing and uncommitted ones;
setup never commits, stages content, or reverts anything, so review the result
with git diff. The agent does not run Nix, enter a devshell, or invoke
scaffolding itself. Explicit addon selections become configuration checks; in
this experiment --without requires the addon's enable switch to be false.
Unknown addons and choices are rejected. Git framework sources are pinned. Dirty
local framework checkouts are rejected: omit --flake or select a committed
revision with git+file:///absolute/path?rev=<commit>. This avoids copying
ignored local state into the Nix store through directory inputs.
The host supplies repository-onboarding option names, types, and descriptions
from the pinned framework's lib.getOptions, including Nix-only app tooling and
command fields omitted by starter templates. This lookup uses pure Nix evaluation
independently of the target repository, so a broken configuration can still be
repaired. Older saved sessions gain this schema before the next agent invocation;
their answers, accepted plan, template, and framework revision are retained.
A plan can list host preparation commands, such as bun install, for the
dependencies and lockfiles the agent should not produce itself. The plan review
shows them, and accepting the plan approves them. Stackpanel runs them unchanged
in the repository devshell, with network access, after reconciliation and before
every doctor run. Doctor itself never installs anything, so doctor --onboarding
does not run them.
Flakes in a Git repository only see files Git knows about. Before each Nix step,
setup marks the files it created, the files the plan lists, and untracked Nix
inputs (*.nix, flake.lock, .stack/) with git add --intent-to-add. That
records the paths without staging their contents; generated output and private
state under .stack/ are never added.
Stackpanel then enters a fresh Nix shell (which creates or extends flake.lock
as needed), reconciles generated files, runs the plan's host preparation, and
runs:
stack doctor --strict --scope repo,build --build --expectations /path/to/expectations.json --jsonIf entering the shell, reconciliation, host preparation, or doctor fails, the agent gets one repair turn with the failure, followed by another fresh check. Checks doctor cannot run here, which it reports as skipped, are not treated as failures. If doctor still reports problems after the repair turn, setup lists them and continues to runtime and Studio setup; rerunning the same command checks the repository again. If a step before doctor still fails, setup stops with the error.
Claude uses native read and edit tools; shell commands run on the host. When Claude reports a tool request it was denied, setup shows it as a warning and continues. Each agent or shell step has a one-hour limit, and interruption cancels its subprocesses.
--dry-run and --json retain the ordinary read-only setup report and never
launch an agent. Agent onboarding cannot be combined with --only, --skip, or
--reconsider. Shell entry still executes the repository's normal hooks, including
generation and project registration; this also applies to --tmp repositories.
Create a new repository
stack setup --experimental-agent=auto --new ./my-appThe target must be absent or empty on its first run. A saved setup can resume in
that same directory once it contains files. The wizard asks what you want to build, uses
Stackpanel templates for the environment, and generates the application starter.
New flake plans follow the framework's pinned Nix inputs unless other versions
were requested, keeping the framework and its dependencies compatible.
The reviewed plan lists the files and build/test commands doctor checks.
--new cannot be combined with --tmp, --json, or --dry-run.
Resume an interrupted setup
Run the same command again:
stack setup --experimental-agent=auto --tmp --template minimal
# If interrupted, repeat this command from the same working directory.Setup saves a versioned JSON manifest beside the user config, normally
~/.config/stackpanel/setup/<repository-hash>.json. The wizard and errors display
the exact path. It respects XDG_CONFIG_HOME and STACKPANEL_USER_CONFIG. Files
are private, written atomically, and kept outside the repository. The manifest
records the selected agent, template and addon choices, question/answer transcript,
proposed or accepted plan, the last failure, the untracked files that predate the
setup, and runtime handoff. Full provider event logs remain opt-in through
--agent-log. A manifest this release cannot read is replaced by a new setup.
Repeating --tmp from the same directory reuses its latest unfinished repository.
Repeating --new ./my-app resumes that target. You can also enter the recorded
repository and run stack setup --experimental-agent=auto. A completed temporary
setup does not prevent the next --tmp run from creating a new repository.
Saved answers are not asked again, and an accepted plan is not reviewed again. If the agent was interrupted, it receives the choices and plan and inspects the current files to continue. If it finished its changes, setup resumes the host check without invoking the coding agent. Reconciliation and doctor run again against the current repository; saved progress never counts as verification. A valid Studio handoff is reused, with live readiness checked again.
Omitted configuration flags inherit saved selections. Changing --template,
--flake, --agent-model, or addon choices starts a new plan. Runtime options
such as --agent-port, --studio-url, and --no-runtime=false can be changed
on retry; an explicit agent selection can also replace the saved provider.
Use --restart to discard saved choices and plan a new setup while keeping
existing repository files. With --tmp, it creates a fresh temporary repository
and keeps the old one.
Local agent and Studio
After repository verification, setup registers the project, starts or reuses its local agent, and starts the services selected in the plan. It opens Studio and guides browser pairing. Completion requires an authenticated project configuration load and a live event connection from that browser, followed by a runtime doctor pass. Browser evidence expires and is bound to this setup session, agent, origin, and repository. Pairing uses the existing user approval page.
A running agent serving another repository is not reused: select --agent-port
or restart the agent for the intended repository. Setup-started agents continue
running with logs beside the user config in agent.log. --studio-url selects a
local or hosted Studio containing the setup handoff feature. Hosted Studio must
be updated with that feature before it can acknowledge readiness.
--no-browser verifies the local runtime and explicitly leaves Studio unverified.
--no-runtime performs repository verification only, suitable for CI. Neither
option reports browser readiness. Runtime setup does not invoke the coding agent
again or let it decide whether verification passed.
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--yes, -y | bool | false | Skip confirmation and take every default answer |
--json | bool | false | Print the plan as JSON and exit without applying |
--dry-run | bool | false | Show the report and exit without applying |
--only | strings | none | Run only these reconcilers (repeatable) |
--skip | strings | none | Skip these reconcilers (repeatable) |
--reconsider | bool | false | Re-offer addons that were declined at their current revision |
--force | bool | false | Overwrite existing scaffolding files and rewrite generated files |
--flake | string | none | Stackpanel flake reference used for scaffolding (default: github:darkmatter/stackpanel) |
--template | string | default | Scaffolding template name |
--tmp | bool | false | Create the project in a temporary git repository and print its path |
--non-interactive | bool | false | Never prompt (same as --yes) |
--with | strings | none | Accept an addon by id without prompting (repeatable) |
--without | strings | none | Decline an addon by id without prompting (repeatable) |
--addon | strings | none | Answer an addon explicitly as id=value (true/false, a choice value, or comma-separated values) |
--build | bool | false | Also realize build-scope doctor checks with nix build |
--new | string | none | Scaffold a new repository in an absent or empty directory |
--studio-url | string | hosted Studio | Studio URL for the browser handoff |
--agent-port | int | agent default | Local agent port |
--no-browser | bool | false | Verify runtime without opening the browser |
--no-runtime | bool | false | Verify repository only |
--agent-log | string | none | Private raw provider debug log; path must not exist |
--experimental-agent | string | none | Experimental repository onboarding using auto, codex, claude, or pi |
--agent-model | string | none | Pi API provider/model, saved for resume; requires an API key |
--restart | bool | false | Review a new agent onboarding plan; with --tmp, create a fresh repository |
The discovery ledger
.stack/reconcile.json records what the user has been shown at which revision:
{
"version": 1,
"seen": { "playwright": { "revision": 1, "answer": false, "at": "2026-09-04T01:22:11Z" } }
}An offer is re-shown only when its author bumps revision, or with
--reconsider. .stack/addons.json from older releases is migrated
automatically.
Global Flags
These flags are inherited from parent commands.
| Flag | Type | Default | Description |
|---|---|---|---|
--daemon, -d | bool | false | Run in daemon mode (no TUI, for background processes) |
--no-color | bool | false | Disable color output |
--no-tui | bool | false | Disable interactive TUI mode |
--verbose, -v | bool | false | Enable verbose output |