Install

npx starwisp init puts Starwisp into your own GitHub organization and Cloudflare account, using your own sign-ins. Only your signed license key is shown to our download service. Nothing you create passes through our servers.

Requirements: Node.js 20 or newer. The installer has no dependencies.

Commands #

Options for init:

Progress is saved in ~/.starwisp/install.json (private to you). It holds progress and non-secret facts only.

Before you run it #

Run these once:

gh auth login
gh auth refresh -s repo,workflow,read:org
npx wrangler login

You should now see gh auth status say you are logged in, and npx wrangler whoami show your account.

Want to preview first? npx starwisp init --dry-run --org my-company changes nothing.

The ten steps #

1. Check prerequisites #

The installer checks Node 20+, git, npm, gh (signed in, with repo, workflow and read:org), wrangler (signed in), and that the organization exists, is an organization, and that you are an owner of it.

The installer prints a line for each check, for example:

[1/10] Check prerequisites
  ✓ Node 20 or newer
  ✓ git, npm, gh, wrangler found
  ✓ gh is signed in with repo, workflow and read:org
  ✓ you own the organization my-company

You should now see a line with a check mark for each prerequisite.

2. Verify your license #

Paste the key when asked. It is verified on your computer. You should see Licensed to you@acme.com (standard), updates until <date>. If your updates period has ended, the installer tells you and tries the newest release you are entitled to.

3. Get the release #

The installer sends your license to the update service and receives a short-lived download link and a checksum. It prints the host your key goes to. The download is verified against the checksum before anything is unpacked. With --from this step uses your local file instead.

You should now see Release <version> ready.

4. Your domain (optional) #

The installer asks Your domain, like example.com (press Enter for none):. A domain is optional. If you have one on Cloudflare, give it: it is checked for shape only here, saved as house_domain in .factory/identity.json in your new factory repo, and used as <app name>.<your domain> for every app. You can also pass --domain acme.com. Press Enter if you have none: apps then go live free at <app name>.<your-subdomain>.workers.dev and app email stays off (see presets). In the console, save your workers.dev subdomain as the Free web address in Settings → Identity (the form fills it in for you), or add a domain there later. If your factory repo already exists, the installer leaves it alone, so set these in the console.

5. Create your repos #

It creates two private repositories in your organization: factory and app-template (marked as a template). If a repo already exists it is left alone.

Each repo is uploaded in two pushes: the code, then the workflows. GitHub only switches on a workflow's automatic triggers (new issues, pushes, schedules) reliably when the workflow arrives after the first push. The installer then waits up to 2 minutes for GitHub to start a run. If none starts, it prints a warning and goes on; run npx starwisp doctor --fix afterwards.

You should now see factory and app-template (private).

6. Wire up updates #

It saves your license as the Actions secret STARWISP_LICENSE in <org>/factory (sent over stdin, never on a command line) and the update service address as the variable STARWISP_UPDATE_URL. The Update button needs both. See updates.

You should now see STARWISP_LICENSE (secret) and STARWISP_UPDATE_URL (https://api.getstarwisp.com) saved in <org>/factory.

7. Deploy the console #

It runs npm ci and npm run deploy in factory/console and reads your console's workers.dev address.

On a brand-new Cloudflare account this step can stop with Your Cloudflare account has no workers.dev address yet. Open Workers & Pages in the Cloudflare dashboard once (that assigns <name>.workers.dev; you don't need to create anything), then run the installer again. It picks up here.

You should now see Console at https://…workers.dev.

8. Set the console's settings #

It stores four settings in your Cloudflare Worker: AUTH_SECRET (random), AUTH_URL, FACTORY_ORG, FACTORY_REPO.

You should now see AUTH_SECRET, AUTH_URL, FACTORY_ORG, FACTORY_REPO.

Then it asks Anthropic API key (sk-ant-api03-…, hidden), or press Enter to skip:. This is optional. If you paste your key (typing is hidden), it is saved in two places at once: the Actions secret ANTHROPIC_API_KEY in <org>/factory (the Vault, which runs use) and a secret of the same name on the console Worker (the Idea Studio on Home, which talks to Claude from the console itself and can't read GitHub secrets back). It goes over stdin and is never written to disk. If you skip it, add the key in Settings → Vault later and follow the Setup row Idea Studio: Anthropic key on the console. You can also set ANTHROPIC_API_KEY in your shell before running the installer.

9. Create the GitHub App #

Your browser opens to GitHub with a prefilled App. Click Create GitHub App, then on the next page click Install and choose All repositories.

If GitHub asks you to confirm it's you (password, passkey or 2FA), it can lose the prefilled App and show an empty Register new GitHub App form for your personal account instead. Don't fill that in. Go back to the installer's local link (http://127.0.0.1:<port>/, printed in the terminal) and open it again: it re-sends the prefilled form for your organization.

Choose "All repositories", not "Only select repositories". Each app you build gets its own new repository. A selected-repositories install cannot see it, so the run would fail at that point. If you chose wrong, change it at https://github.com/organizations/<org>/settings/installations (open the App, set Repository access to All repositories, Save). The Setup page also checks this and links straight to the setting. Then the installer waits (up to 10 minutes) until GitHub says the App is on your organization. If an earlier run already created the App and stopped, the installer instead shows the install link and asks Press Enter after you chose "All repositories" and clicked Install:. Finish the install on GitHub, then press Enter.

The installer then stores APP_ID (a variable), APP_PRIVATE_KEY and APP_WEBHOOK_SECRET (secrets) in <org>/factory, and the App's sign-in id and secret in your console. The private key goes straight from memory into GitHub over stdin. It is never written to disk. See security.

You should now see App installed.

10. Finish #

It prints your repo and console addresses and opens <console>/setup. Save keys on Settings → Vault and test them on the Setup page (see the quickstart).

You should now see Starwisp is installed.

Check any time with npx starwisp doctor.

Every error the installer prints #

Every expected error prints four lines: what went wrong, why, the fix, and a link. Your progress is always saved, so after the fix, run the same command again. Errors are listed here in the order you could hit them.

Options and commands #

Step 1: prerequisites #

The error reads Prerequisite not met: <name>. The first failing check is shown.

Step 2: license #

The "Why" line is one of:

An expired updates date does not make the key invalid. It only limits which releases you can download. See updates.

Step 3: release #

Step 4: repos #

Two warnings (not errors) can show here:

• GitHub has not started any workflow for the push to <org>/<name> in 2 minutes: finish the install, then run npx starwisp doctor --fix.
• <org>/<name> has no .github/workflows, but this installer did not make its last commit: the repo was there before the installer, so it is left alone. Run npx starwisp doctor to see what it needs.

Step 5: deploy #

Step 6: console settings #

Step 7: GitHub App #

A warning (not an error) says The App is installed on selected repositories only. New app repos need All repositories. Change it at https://github.com/organizations/<org>/settings/installations.

Anything else #

Something unexpected went wrong: … is a bug in the installer, not something you did. Run the same command with --debug and send the output to support (see support). Do not paste keys.

If doctor fails #

npx starwisp doctor re-runs the prerequisite checks and then checks your install. Each failure prints a fix.

Start over #

npx starwisp init --restart forgets saved progress. It does not delete your repos or Cloudflare Worker. Existing repos are left alone.

Plain-text version of this page: /docs/install.md. This page is copied from the product's own docs, so it matches the release you install.

Next: Presets