Quickstart: run a test on a disposable environment

You will run your own tests against the Docker Compose services you pick, on a private server in your own cloud account, then tear the server down. You need a DigitalOcean or Hetzner account and an API token for it. The CLI is free; your provider bills the server at an hourly rate.

Looking for a model on a GPU instead? That is the managed GPU quickstart.

Before you start

1. Install

curl -fsSL https://chalupa.run/install.sh | bash
chalupa doctor

If your shell cannot find chalupa, add ~/.bun/bin and ~/.local/bin to your PATH and open a new terminal. chalupa doctor is free and offline: it checks your tools and tells you what to install.

2. Add your provider token and SSH key

Run this from your project directory, next to its docker-compose.yml:

chalupa setup --provider digitalocean   # or: --provider hetzner

Setup asks for your provider API token in a hidden prompt, validates it and stores it in TinyVault, never in a file. It creates Chalupa's own SSH key, registers only the public half with your provider, and writes a starter chalupa.yml if you do not have one. It never overwrites an existing file. Linking a hosted console account is optional; --no-console skips it.

3. Describe the services you want

Edit chalupa.yml to point at your Compose file and list the services to copy. This example copies a web app, Postgres and Redis:

name: shop-test
provider: digitalocean
compose: ./docker-compose.yml
services: [web, postgres, redis]

overrides:
  postgres:
    mem_limit: 1g

compute:
  region: sfo3
  size: s-2vcpu-4gb
  health:
    url: http://127.0.0.1:8080/
    status: 200
    timeoutSeconds: 300

ssh:
  keys: [chalupa-my-laptop]
  allowedCidrs: [203.0.113.10/32]

• compose and services are the source of truth: ports, volumes and dependencies are read from your Compose file, not copied by hand. Services you do not list are not copied, and a depends_on that points at one is removed.
• ssh.keys names the key setup registered with your provider (chalupa-<your hostname>), and ssh.allowedCidrs is the only door in. Replace the example address with your own; setup proposes your current public address, and chalupa allow-me refreshes it when your address changes.
• compute.health must point at a port one of your selected services publishes.

Chalupa copies the Compose services you pick. It refuses build, env_file, networks and profiles, so use prebuilt images. See the chalupa.yml reference and stack recipes.

4. Preview for free

chalupa preview

Preview renders the exact Compose that would run, the ports that would be tunnelled, the readiness probes and the services. chalupa inspect shows the server size and region. Preview is offline: it contacts no provider and creates nothing. Fix anything it reports before you continue.

5. Launch

chalupa up

chalupa up asks one yes or no question. Nothing is created until you answer yes. It then creates the server, applies a firewall that opens only SSH, and starts your services. Every service port binds to 127.0.0.1 on the server.

If your config declares persist, run chalupa data-up once first. It creates the separately billed data volume, and asks you to type a confirmation phrase.

6. Open the tunnel and run your tests

chalupa tunnel

Your services now answer on localhost on your laptop. In another terminal, run your test suite, browser flows or AI agent against them unchanged. Use chalupa status at any time to see what is running.

7. Keep what you need

Evidence from a run depends on how you ran it. Some of it is local and some is beta; what a run leaves behind says which is which.

8. Tear down

chalupa down
chalupa status

chalupa down destroys the server. Compute billing stops. A data volume you declared stays for the next run, and bills until you delete it on purpose. chalupa status confirms the server is gone.

Next

• Copy a recipe for your stack
• Give your agent an environment
• What a run leaves behind
• Troubleshooting