getting started
Two windows. ~30 minutes.
Single binary. No dependencies. No Docker. Plan to spend ~10 min collecting credentials in your browser, ~20 min watching the provisioning ladder run. The TUI walks you through every prereq in-line — no separate checklist. Resumable from any prior install if you just want to re-run the post-install actions.
Step 1 of 4
Download the installer
Pick the binary for your platform. The page below auto-detects your OS+arch and highlights the right one. The detected card glows in the accent color.
Each link above serves the latest stable build. Files are SHA-256 pinned — verify against /binaries/checksums.txt if you want the receipts. Linux builds are on the way; the installer runs on your Mac and provisions a Linux host, so for now macOS is the only client we ship.
Or, one command in a terminal
Skips the macOS Gatekeeper dance entirely — files fetched with
curl don't get the com.apple.quarantine
attribute Finder downloads do, so no "unidentified developer"
dialog. Open Terminal (⌘+Space → "terminal") and paste:
curl -fsSL https://kartaa.pages.dev/install.sh | bash
Detects your arch, drops the binary at
~/.local/bin/kartaa-install, and launches the TUI.
Inspect the script first if you want —
/install.sh is plain bash.
Step 2 of 4
Or, if you clicked the card
Browser downloads land in ~/Downloads/ with macOS's
quarantine flag set. Two extra steps and you're past it:
# 1. clear the quarantine attribute Safari/Chrome attached xattr -d com.apple.quarantine ~/Downloads/kartaa-install-* # 2. mark runnable + launch chmod +x ~/Downloads/kartaa-install-* ~/Downloads/kartaa-install-*
Prefer clicks over xattr? Right-click the file in
Finder → Open → Open in the security dialog.
One time only — macOS remembers afterward.
Step 3 of 4
Pick a path on the Welcome screen
Three boards greet you on launch — privacy / unlock / ownership — plus an optional Resume row above the "Press Enter" CTA if you've installed on this Mac before.
If this is your first install
Press Enter. Walks you through host pick (AWS or
Hetzner), prereq check, plan input (hostname + secrets),
review, and a 14-min provisioning ladder.
If you've installed Kartā here before
Press r. Skips the entire fresh-install pipeline
and jumps straight to the post-install action checklist for the
most recent successful install. Saves 14 minutes when all you
want is to re-run a Codex / GitHub / Telegram action.
Step 4 of 4
Wire the cockpit to your accounts
Once the install finishes (or if you resumed), the Done screen shows a four-row checklist. Each row is one keypress; the TUI surfaces output inline so you never have to context-switch to a shell.
-
[c]
Codex device-auth
SSHes into the cockpit and runs
codex login --device-auth. Opens a chatgpt.com URL with an 8-digit code; sign in to your ChatGPT account → done. Required for Codex sessions to spawn. -
[g]
GitHub App registration
Asks for a globally-unique App name (validates live against
api.github.com/apps/<slug>), opens a Kartā-branded splash that auto-POSTs the manifest to GitHub, you click "Create" + "Install on your repos", callbacks come back automatically. Two clicks. Zero credential pasting. -
[T]
Telegram bot notifications
Paste a bot token (from @BotFather) + your chat_id (from @userinfobot). Cockpit DMs you when sessions are ready. Optional but recommended.
-
[o]
Open the cockpit
Launches your default browser at the tailnet HTTPS URL — something like
https://kartaa-aws-prod.tailXYZ.ts.net/. Bookmark it; this is your driver's seat.
Press [?] on the Done screen, then any of
c / g / T / o
to open per-action docs inline. Press [u] to
tear down all AWS resources at the end (cost-aware confirm).
When all four flip to ✓, the post-install ladder folds away and this lands in its place — your driver's seat, your benediction:
Troubleshooting
Common issues + fixes
"Connection refused" probing the cockpit
Tailscale isn't connected on your Mac. Open the Tailscale app → make
sure you're logged in to the same tailnet that owns your kartaa
host. Run tailscale status in a shell to confirm.
"App name already taken" on [g]
GitHub App names are globally unique across all of github.com.
Pick a fresh suffix — kartaa-bot-personal,
kartaa-bot-staging, etc. The TUI checks live before
opening the manifest URL.
AWS install hangs at "Waiting for Tailscale join"
Phase 6 is normally 90-180s. If you re-used a hostname from a prior failed install, the old node may be ghosting on your tailnet. Paste a Tailscale API key in the PlanInput's 4th field and the installer auto-cleans the ghost. (Tailscale API keys: login.tailscale.com/admin/settings/keys.)
Cockpit URL won't load in browser
HTTPS lives on the tailnet — Tailscale must be running on the device you're browsing from. The URL doesn't work over public internet by design. Use Tailscale's mobile app for phone access.
Need to start over
Hit [u] on the Done screen for cost-aware AWS teardown,
then re-launch. State lives in
~/.config/kartaa-install/runs/<timestamp>-<uuid>/state.toml;
delete it for a totally fresh slate.
Heads up
What it'll cost you
-
$0
First year on AWS Free Tier
t3.micro / t4g.micro covers 750 hours/month for 12 months, plus 30 GB EBS. Free Tier expires after a year; eligible instances ~$8-10/month after that.
-
€8
Hetzner CPX21
3 vCPU AMD, 4 GB RAM, 80 GB SSD. EU-friendly, no free tier but no cold-start latency either. Recommended once your AWS Free Tier lapses.
-
$20
ChatGPT Plus subscription
Required — Kartā uses your subscription's Codex quota rather than a per-token API spend. No additional API billing.