Quickstart

Managed GPU

Run these commands from your project directory:

curl -fsSL https://chalupa.run/install.sh | bash
chalupa setup
chalupa balance --top-up 10  # only if the balance is empty
chalupa up
chalupa launch
chalupa down

The installer installs Bun, go-task, and the latest published @thelacanians/chalupa-cli. It prints chalupa setup and chalupa up as the next commands. If the shell cannot find them, add ~/.bun/bin and ~/.local/bin to your PATH and open a new terminal. Releases are tagged by the maintainer; the published package can lag the repository's package.json.

Setup offers Chalupa managed GPU (recommended: no cloud account needed) first, followed by DigitalOcean and Hetzner. Managed uses Chalupa's cloud account and your prepaid balance. It needs an eligible Solo or Crew plan, Bun, Task, and OpenSSH; it does not need Pulumi, TinyVault, or a provider token on your laptop. Install your chosen coding agent separately and make sure opencode is on PATH for the default starter.

Setup prepares ~/.config/chalupa/ssh/id_ed25519, links your console account, and writes ./chalupa.yml. It reuses a valid linked account and leaves an existing config untouched. The starter selects provider: chalupa, compute.size: gpu-large, a 60-minute session, qwen3.8:27b, a 60 GiB model cache, and inference.agents.default: opencode. Context is omitted so it uses auto negotiation.

chalupa setup signs you in with your email and a code, creating a hosted account if needed, and stores its session in ~/.config/chalupa/account.json. chalupa login remains the operator-only terminal approval flow. See Local CLI for the distinction.

up reads your project config, shows the hourly rate, session estimate and balance after the estimate, and asks one yes/no question. It detects your current public IPv4 for SSH access. launch opens its own tunnel and runs the configured agent locally against the GPU model. Exiting the agent closes the tunnel; compute remains running until down succeeds or the console enforces expiry.

Use chalupa preview for an offline estimate, chalupa status for host status, and chalupa exec -- your-command for another local tool. A standalone chalupa tunnel is optional; stop it before using launch or exec.

Commands use ./chalupa.yml, then CHALUPA_CONFIG, then search parent directories up to the repository boundary. --config PATH overrides that choice. Legacy CHALUPA_TASK_CONFIG, CONFIG, and CHALUPA_STACK_FILE still take precedence for existing Taskfile workflows. chalupa launch omp overrides the default agent; --context native or --context 64k overrides context for one invocation. Managed scripts need chalupa up --yes and chalupa down --yes.

Bring your own cloud account (BYOC)

Run chalupa setup and choose DigitalOcean or Hetzner. To skip the provider question, use chalupa setup --provider digitalocean or chalupa setup --provider hetzner. DigitalOcean GPU inference additionally uses chalupa setup --inference --provider digitalocean; Hetzner supports CPU environments.

BYOC has extra prerequisites and setup steps:

1. Install Pulumi and TinyVault in addition to Bun, Task, and OpenSSH. Unlock TinyVault. Pulumi uses local state; protect that state as sensitive data.
2. Supply your provider token in setup's hidden prompt. Setup validates and stores it in TinyVault, and registers only Chalupa's dedicated public key with that provider.
3. Link a console account with email verification, or use --no-console to skip linking. For DigitalOcean inference, the optional console reaper needs a separate token with only droplet:read and droplet:delete. The console stores that token encrypted. --no-reaper-token skips that prompt.
4. Confirm the bounded IPv4 SSH allowlist. Review the generated config. For a Compose project, declare the Compose path and selected services; see chalupa.yml.
5. Run chalupa preview and correct any errors before provisioning. For a BYOC inference session, install and check the local expiry scheduler with chalupa teardown schedule:install and chalupa teardown schedule:doctor. Keep the scheduler's machine awake and TinyVault unlocked when it owns expiry.
6. Run chalupa up, then chalupa tunnel for Compose services or chalupa launch opencode for inference. BYOC also asks yes/no for launch and sink. Scripts use an explicit --config and the exact --confirm phrase shown in Local CLI.
7. Finish with chalupa down, then chalupa status.

If your Compose config declares persist, run chalupa data-up once before launching. Seed through the tunnel with chalupa seed when needed. down keeps the separate data stack. Never use task data-nuke for routine cleanup; it deletes the persistent data irreversibly.

What to expect

• Install: prints the installed version and the two next commands, chalupa setup and chalupa up.
• Setup: shows the provider choice, prerequisite results and local key location, then account linking and the config result. On a linked managed account with no credit, it prints Balance $0.00 — top up with: chalupa balance --top-up 10, then Next: chalupa up. Rerunning preserves your key and config.
• Top up: prints a Checkout link (and opens it on supported terminals). Complete payment, then use chalupa balance to verify credit.
• Up: prints the tier, hourly price, duration, estimate and balance after that estimate before its yes/no prompt. It follows job phases, then prints Ready in …, the host IP, expiry, and connection/stop commands. The first launch downloads roughly 18 GB of weights; allow several minutes, with actual time depending on capacity and network. Later launches reuse the cache volume and usually avoid that download, but still provision and boot compute. The CLI stops waiting after 25 minutes; a pending job may continue.
• Launch: prints the chosen agent and model, checks the tunnel and negotiates context, then hands you the agent terminal. If no default is configured, the error lists opencode, omp, and local-agent; set inference.agents.default or name one explicitly.
• insufficient_balance: no launch is queued when the local balance check fails. Run chalupa balance --top-up 10, finish Checkout, check chalupa balance, and retry chalupa up. A server-side admission check can also reject a launch if balance changes between requests.
• host_cap: the account has reached its host limit. Run chalupa down from an existing host's project directory (or select its config), wait for completion, then retry. Do not create another project to work around the cap.
• Failed job: read the error and run chalupa status to check hosts and recent jobs. Check the console's job details. A failure can leave resources running; use chalupa down to clean up after the pending job finishes. Save the error and job ID for the maintainer. Do not assume failure means compute stopped.
• Stop: exit the agent or standalone tunnel, run chalupa down, answer yes, and wait for Managed GPU stopped. Then run chalupa status to confirm there is no managed host. Model cache storage remains and can still cost money. BYOC persistent data also survives compute teardown.