Build settings

This page covers changing how your project builds after import: build command, output directory, production branch and framework, and the workflow PR that some changes open in your repo.

Prerequisite: a project.

Prompt for your agent

Copy this into Claude Code, Cursor or any agent that can run shell commands. Settings are saved in your browser; the agent works out the values, tells you what to change, then checks the result in your repo.

Read https://docs.stasho.xyz/guides/build-settings.md. My Stasho project builds from my GitHub
repo <owner>/<repo>. Read the repo and work out the build command, output directory and
production branch it needs, then tell me, in the page's words, what to change on the project's
Settings tab, and wait for me. When I say it is saved, check with gh for a settings pull request
from stasho-deploy. After it is merged, read the workflow file to confirm it carries the new
values, and watch the build the merge starts. Never ask for my wallet key, my seed phrase, a GitHub token or an agent key in chat.

What you can change

Open your project's Settings tab (/projects/<id>/settings):

Field	What it does
Build command	The command the workflow runs (e.g. npm run build). On a monorepo workspace it is read-only: the workflow runs that workspace's own build script
Output directory	Where the built site lives (e.g. out, dist)
Root directory	Where the app lives in the repo; empty means the repo root
Production branch	The branch whose pushes trigger deploys
Framework	Next.js (static export), Next.js, React, Vue, Astro, Nuxt, or None / static HTML
Deploy target	Static site (IPFS), or Server app (App VM) once your App VM is set up

If the panel shows "Unlock your encryption key" instead of the form, sign the unlock prompt on the Overview tab first: build settings live inside your project's encrypted record, so editing them needs the key.

Everything in the output directory is published, and a static site's files cannot be taken back. Stasho leaves .git out at any depth, and files named .env or .env.* too, and the deploy carries on without them. Every other dotfile is published, so point Output directory at the built site rather than the repo root wherever your project has a build step.

An uploaded site has no repo, so nothing here builds it: there is no Re-detect from repo and no workflow PR. You publish its built files instead (Your first deployment).

Saving can open a PR in your repo

Your build configuration is baked into the deploy workflow file committed in your repo. When you save a change that alters that file (build command, output directory, root directory, branch, deploy target), the app regenerates it and opens a pull request in your repo with the update. On a static site the framework alone is not in the file, so changing only that opens no PR. Until you merge it, deploys keep using the old configuration, except for a change of branch or deploy target, which applies at Save. A card on the Settings page links to the pending PR:

• Apply new settings, once the project has deployed. Merge & apply merges the PR. The merge is a push to your production branch, so a new build starts at once with the new settings and goes live if it succeeds. You don't need to Redeploy. Check the values before you merge: a static site's files cannot be taken back. Merging the PR on GitHub does the same.
• Finish setup, before the first deploy. Merge & deploy merges the PR and starts a deploy in one click.

If your change doesn't affect the workflow file, no PR opens and the save just applies.

If a warning says the workflow update failed, the settings are saved but the workflow file is not. Fix what the warning names. There is no retry button, and Save stays disabled until the form differs from what is saved, so change the Output directory, Save, change it back and Save again. Don't use Production branch or Deploy target for this: those apply at Save.

Changing the production branch

A branch change applies when you save, not when the PR merges. From then on, a run on the old branch fails with "Branch not authorized". That includes a run already in flight, whose deployment reads failed only once the stuck check catches it. Pushes to the new branch don't deploy until the PR merges, so merge at once: the PR targets the new branch, and its merge starts the first build there.

The old branch keeps its copy of the workflow file, which fires a failed run on every push until you delete it there.

Framework is sticky: use Re-detect

The framework set at import (or by you) never auto-updates, so a refactor in your repo can't silently change how your site builds. If your repo has changed framework (say you migrated to Next.js), click Re-detect from repo:

1. The app inspects your repo at the current branch head
2. A diff shows only what changed (e.g. "Framework: none → nextjs")
3. Apply fills the form. Review it, then Save as usual (Apply alone saves nothing)

Verification

• The Settings form reflects your saved values after a reload
• If a PR was opened: it's merged and the card is gone
• The build the merge starts uses the new configuration (check the build command in the Actions log)

What can go wrong

Symptom	Cause	Fix
Saved a change but deploys behave as before	The workflow PR isn't merged	Merge it: Merge & apply in the app, or on GitHub
Build fails right after changing settings	The new command or output dir doesn't match the repo	Check the Actions log; Re-detect from repo to get back to known-good values
Settings tab asks for an unlock	Encryption key isn't unlocked in this browser	Sign the unlock prompt on the Overview tab

Working with an agent

An agent cannot change these settings: they live in your project's encrypted record, and nothing on the agent API reads or writes them. What it can do is read your repo and work out the values, change the repo itself if it has access (a build script, a next.config), and check the outcome. It should not hand-edit the workflow file: the next save regenerates it.

What the agent hands you, in these words:

Open the project in the Stasho dashboard and click its Settings tab. If it asks you to unlock,
sign the unlock prompt on the Overview tab first. Set Build command to <command>, Output
directory to <dir> and Production branch to <branch>, then click Save. If an Apply new settings
card appears, click Merge & apply, or Review on GitHub and merge it there. The merge starts the
new build, so do not click Redeploy. If a warning says the workflow update failed, read me its
words. Tell me when it is done and which branch the project deploys from.

How the agent verifies it afterwards. The settings PR and the workflow file are readable on GitHub with no Stasho account. With gh signed in to an account that can read the repo:

gh pr list --repo $OWNER/$REPO --author app/stasho-deploy
gh api "repos/$OWNER/$REPO/contents/.github/workflows/stasho-deploy.yml?ref=$BRANCH" \
  --jq .content | base64 -d

An open PR means the workflow file doesn't carry the new settings yet, though a branch or deploy target change already applies. In the file, branches: names the production branch, the Build step runs the command and, on a static site, the Upload artifact step packs the output directory. A monorepo workspace's file carries a suffix after stasho-deploy, and its Build step runs the workspace's own script. The merge starts the build: gh run list --repo $OWNER/$REPO --workflow stasho-deploy.yml --limit 3 shows it, and with a read key stasho deployments --project $PROJECT_ID shows it go live. Don't add stasho deploy on top: that queues a second build and spends a deploy from the key's budget.