Getting started

RepoWrangler's primary guided deployment path is Ranch Hand Public Preview on Windows. Manual source-controlled deployment remains a supported alternative. Ranch Hand defaults every supported target to production data mode and offers demo mode as an explicit choice. The manual quick starts below use demo mode so you can explore the product before connecting anything.

Choose your path

Path	Choose it when	Start here
Recommended — Ranch Hand Public Preview for Windows	You want a standalone UI to verify a release, collect target inputs, run preflight/dry run, and deploy without cloning RepoWrangler or installing its build/deployment tools	Download and use Ranch Hand
Supported alternative — manual/artifact/CI deployment	You need production today, want the source, use a topology not yet supported by Ranch Hand, contribute code, or own the commands and CI/CD	Continue below and use the deployment guide

Ranch Hand is released independently. The current Windows build is an unsigned Public Preview, not a signed or production-supported GA installer. The RepoWrangler v1.0.18 release contains server and deployment artifacts; Ranch Hand consumes those artifacts for you.

Manual-path prerequisites

• Node 22 and pnpm (via corepack enable) for local development, or
• Docker for the one-command container path.

Manual option A — one-command demo (Docker)

The fastest way to see the whole app on your machine:

git clone https://github.com/WranglerLabs/repo-wrangler.git
cd repo-wrangler
docker compose up

Open http://localhost:8080. You get the full UI populated with mock data — the Command Center, Repositories, Branches, Change Requests, Security, Budgets & Usage — with sign-in bypassed (a synthetic demo viewer). Nothing is written to your GitHub or GitLab.

See deploy/docker/README.md for volumes and options.

Manual option B — local development (pnpm)

git clone https://github.com/WranglerLabs/repo-wrangler.git
cd repo-wrangler
corepack enable
pnpm install

# Cloudflare Worker dev server (Miniflare + local D1):
pnpm dev

# …or the Node host (SQLite, zero Cloudflare):
pnpm --filter @repo-wrangler/web build   # build the SPA the server serves
pnpm start:server

pnpm dev runs the Cloudflare Worker locally on http://localhost:8787. pnpm start:server runs the Node host on http://localhost:8080 (requires Node 22 — it uses node:sqlite behind --experimental-sqlite, which the script passes). Both default to demo mode.

Useful workspace scripts (run from the repo root):

Command	What it does
pnpm -r typecheck	Typecheck every package
pnpm test	Run the unit tests (vitest)
pnpm --filter @repo-wrangler/web build	Build the SPA to apps/web/dist
pnpm dev	Cloudflare Worker dev server
pnpm start:server	Node host (SQLite)

Going real

Demo mode never needs a secret. To monitor a real estate you connect a data provider and turn off demo mode:

1. Pick how and where to run it — use Ranch Hand for a supported guided Public Preview deployment, or see the deployment guide for every manual recipe. The cheapest is the Cloudflare free tier; the simplest self-hosted is docker compose.
2. Connect a provider:
   • GitHub → Providers → GitHub App
   • GitLab → Providers → GitLab
3. Set the infrastructure secrets (SESSION_SECRET and SECRET_ENCRYPTION_KEY), then set DEMO_MODE=false. On first boot the app opens directly to the connection wizard; no pre-existing sign-in is needed. The wizard stores provider credentials in the encrypted connection-secret store and setup mode closes as soon as a real sign-in provider works.
4. For an internet-facing first boot, set SETUP_TOKEN in the deployment's secret store. The wizard asks for it before any setup API is available. It is optional and no token is generated or required when the setting is absent.
5. Choose how people sign in — any configured provider in AUTH_PROVIDERS. Add yourself to its allowlist; after the wizard finishes, sign in normally. The first listed principal is the owner.

First sign-in and first sync are covered per provider in the provider guides, and operationally in operations.md.

Growing the estate

Your estate is never frozen at what you connected on day one. On Estate Scope:

• Add more organizations / groups — expand the disclosure row under a connection. For GitHub, Install on another organization opens your App's install page; after installing, Check for new organizations matches the App's installations and starts discovery automatically. For GitLab, add more groups to the existing token connection.
• New since your last review — repositories discovered after you last looked are listed at the top of Estate Scope. Mark all reviewed clears the list; anything found later shows up as new. Discovery also re-runs on a schedule, so repos created upstream surface here without any manual step.

Next steps

• Deployment guide — choose and stand up a target.
• Configuration reference — every setting.
• Architecture — how the pieces fit.
• Troubleshooting — if something doesn't come up.