Quickstart: managed GPU

This page is for running an open model on a GPU. To run tests against a disposable copy of your Compose services, start with the Compose quickstart instead.

Choose Managed GPU for a model hosted in Chalupa’s account, or bring your own cloud account for direct provider billing. Both use SSH tunnels. GPU inference is experimental.

Managed GPU

Run these commands from your project directory:

curl -fsSL https://chalupa.run/install.sh | bash
chalupa setup
chalupa open billing       # activate Solo or Crew if needed
chalupa balance --top-up 10  # after activating a plan, 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 the PATH line to add if your shell cannot find chalupa, then chalupa doctor and chalupa setup as the next commands, and reminds you that chalupa up asks before it creates anything. If the shell cannot find chalupa, add ~/.bun/bin and ~/.local/bin to your PATH and open a new terminal.

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, temporary model storage, and inference.agents.default: opencode. Context is omitted so it uses auto negotiation. Set inference.cache.sizeGb only to request a retained cache.

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.

Before launching, use chalupa open billing to activate Solo or Crew if needed, then finish the top-up Checkout and run chalupa balance to verify credit. The USD balance is checked at launch; it is not reserved or automatically debited and does not enforce a spending cap.

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 or chalupa launch crush 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. Deleting that data is deliberately not part of the CLI and is never routine cleanup; see Data and seeds.

What to expect

• Install: prints the installed version, a PATH hint, and the next commands, chalupa doctor and chalupa setup, plus a note that chalupa up asks before it spends money.
• Setup: shows the provider choice, prerequisite results and local key location, then account linking and the config result. It prints the balance separately and chooses the next command from your account state: Community gets the plan page URL and Next: chalupa open billing; an eligible plan with no balance gets Next: chalupa balance --top-up 10; a funded eligible account gets Next: chalupa up. If balance is unavailable, it prints Next: chalupa balance. After payment, check chalupa balance before up. The terminal summary ends with Project setup complete. 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. With the default temporary storage, every launch downloads the model. An explicitly retained cache can avoid repeat downloads; compute still needs to provision and boot. 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. Use chalupa status --json to retain the 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. Explicitly retained model cache storage remains billable. BYOC persistent data also survives compute teardown.

Check what reached the console

Open your environment in the console after launching. These signals arrive separately:

See Missing GPU metrics, logs or turns for the next diagnostic step. A provisioned host can still be downloading its model.