chalupa.yml reference

This file belongs to the target project and sits next to its Compose file. Commands find it in the current directory or pass it with --config; the name field defines the Pulumi stack names.

Complete example

name: demo-harbor
compose: ./docker-compose.yml

services:
  - api
  - worker
  - postgres
  - redis

overrides:
  api:
    env:
      LOG_LEVEL: info
    mem_limit: 768m
  worker:
    command: ["bun", "run", "worker"]
    mem_limit: 1g

compute:
  region: nyc3
  size: s-2vcpu-4gb
  image: ubuntu-24-04-x64
  prebaked: false # true when image is a golden snapshot with Docker and tools pre-installed
  health:
    url: http://localhost:8080/health
    status: 200
    timeoutSeconds: 300

ssh:
  keys:
    - demo-operator
  allowedCidrs:
    - 198.51.100.24/32

persist:
  sizeGb: 20

idleShutdownMinutes: 45
seed: bun run seed:demo

cloud:
  url: https://chalupa.example.com
  heartbeatSeconds: 30

Do not put tokens in this file. The control-plane URL is not a secret; ingest keys are secrets and are delivered at runtime.

Top-level fields

Every key chalupa.yml accepts is in this table. Unknown keys are refused when the config loads, so a typo cannot silently change a deployment.

provider: chalupa

Managed GPU provisions host Ollama through the console in Chalupa's account. The laptop authenticates with its account session; it needs no provider token.

• compute.size must be gpu-small, gpu-large, or gpu-max; raw provider slugs and auto are not accepted.
• compute.region defaults to ca-east; accepted values are us-east, ca-east, eu-west, and us-south, subject to capacity. Older configs that spell a region by its provider slug still work.
• inference is required, including its context size and weight ceiling; the model defaults to qwen3.8:27b.
• session.expiresAfterMinutes is required and must be 15–480. The console enforces expiry; session.purpose is optional for managed hosts.
• ssh is optional. ssh.identityFile defaults to ~/.config/chalupa/ssh/id_ed25519; up reads its .pub file and detects the current public IPv4 /32. Account key selectors and configured CIDRs are not required. ssh.localPorts[11434] defaults to 11435.
• persist, compose, and services are not allowed. Managed hosts run host Ollama only. inference.cache.sizeGb optionally requests a weights cache.

See Managed GPU for a complete config and CLI commands.

compose and services

compose must point to the actual file. services uses the exact keys under services: in Docker Compose:

compose: ./docker-compose.yml
services:
  - api
  - postgres

The preview fails if a service does not exist. When depends_on points to an unselected service, Chalupa removes that reference; it does not include the service implicitly.

Compose service labels

Compose remains the source of truth for databases, one-shot initialization, and log selection. Chalupa recognizes only these labels:

Unknown run.chalupa.* labels fail validation so a typo cannot silently alter the deployment plan. Known database image families are classified as advisory metadata when labels are absent. Image inference never creates a database, changes a command, generates SQL, or supplies credentials. All services remain explicit entries in services.

Logs are excluded by default, including database and cache logs. An included service receives a deterministic local journald sink. Chalupa rejects a conflicting logging driver before provisioning; set the service to exclude when its project-owned logging driver must remain unchanged. Only the allowlisted classification is reported to the console. Arbitrary Compose labels, environment values, container images, commands, and host identity are not included in heartbeat metadata.

An environment can keep the same selection in chalupa.yml instead of the project Compose file:

session:
  purpose: test
  expiresAfterMinutes: 120
  logs:
    services:
      api: include
      noisy-support-service: exclude
    retentionDays: 7

Both forms are supported. session.logs.services wins when it names the same service as run.chalupa.logs; a service named by only one source retains that source's value. Every configured service must also appear in the top-level services selection.

One-shot database initialization

Initialization stays inside the project's Compose model:

services:
  database:
    image: postgres:17-alpine
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER"]
      interval: 2s
      timeout: 3s
      retries: 30
    labels:
      run.chalupa.role: database
      run.chalupa.database.kind: postgresql
      run.chalupa.database.primary: true

  initialize:
    image: ghcr.io/example/demo-initializer:2026-07-24
    command: ["/app/initialize"]
    labels:
      run.chalupa.role: initializer
      run.chalupa.initializes: database
    depends_on:
      database:
        condition: service_healthy

  api:
    image: ghcr.io/example/demo-api:2026-07-24
    labels:
      run.chalupa.role: application
      run.chalupa.logs: include
    depends_on:
      initialize:
        condition: service_completed_successfully

The initializer image, command, migrations, seed data, and credentials belong to the target project. Chalupa validates the dependency graph but never synthesizes them. Every selected service, including an initializer, must use a published image; see What Compose features are supported.

Compose $VAR and ${VAR...} interpolation is resolved from the operator environment. chalupa up captures only names referenced by selected services and their command/env overrides, then replays that exact snapshot inside the Pulumi program. Unselected-service variables and unrelated shell state are not forwarded. Runtime-owned names (CONFIG, CHALUPA_*, PULUMI_*, and TVAULT_*) and known DigitalOcean credentials are forbidden. $$ remains a literal Compose dollar escape. Volume mappings must remain literal so persistent storage identity never comes from ambient state. The preview redacts non-empty application values read from the shell; resolved tunnel ports remain visible because they define the SSH command.

What Compose features are supported

Chalupa copies the selected services to a server whose only open port is SSH, so it refuses Compose features that need files, privileges or networks the server does not have. Every refusal happens offline, in chalupa preview, before anything is created. Fields that are not listed here are copied to the server unchanged.

Every selected service needs an image. Services are never built on the server by Compose: publish the image first, or declare it under apps so chalupa apps can build it.

Refused service fields. The preview stops with compose_feature_unsupported when a selected service declares any of these:

env_file is the refusal people hit most. Pass values with overrides.<service>.env instead; see Application secrets.

Refused top-level keys. configs, include, networks and secrets.

Refused or rewritten at the service level.

ulimits accepts only nofile, nproc, core, memlock and stack.

overrides

Available overrides are env, mem_limit, and command:

overrides:
  api:
    env:
      NODE_ENV: test
      LOG_LEVEL: warn
    mem_limit: 768m
    command: ["bun", "run", "start:test"]

Entries under env replace Compose values with the same key. Use this mechanism for non-sensitive behavior. Resolve secrets outside the versioned file.

Four more overrides cover what a replay stack usually needs on its first boot:

overrides:
  mongo:
    ulimits:
      nofile: { soft: 65536, hard: 65536 }
  postgres:
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      retries: 30
  temporal:
    waitFor: { postgres: healthy }
    restart: on-failure:3

• ulimits is merged over the Compose ulimits key by key. Only nofile (0–1,048,576), nproc, core, memlock and stack are accepted, as an integer or {soft, hard}; -1 means unlimited except for nofile. Compose files may declare the same subset directly.
• healthcheck replaces the service's Compose healthcheck (test, interval, timeout, start_period, start_interval, retries).
• waitFor maps another selected service to started, healthy or completed, and becomes Compose's own depends_on condition, so docker compose up holds the service until its dependency is ready. Waiting for healthy on a service without a healthcheck, and wait cycles, are refused offline.
• restart: on-failure (or on-failure:N, N = 1–20, default 5) restarts the service after a non-zero exit, at most N times per boot. It is not a Docker restart policy: those stay stripped, because the Docker daemon starts policy-bearing containers before Chalupa's metadata guard is in place. A host unit (chalupa-restart-supervisor) that starts only after the Compose stack, and therefore after the guard, does the restarting and logs each attempt to the journal. A clean exit (code 0) is never restarted. Before stopping a supervised service by hand, run systemctl stop chalupa-restart-supervisor, or it is started again.

Two more overrides adjust what is copied and how logs are written:

• omitBindMountTargets is a list of absolute container paths (1 to 64, unique). Each must match exactly one host bind mount of the service, which is dropped from the server's copy with a warning. Bind mounts are otherwise refused; named and anonymous volumes cannot be omitted this way.
• logging: keep stops Chalupa rewriting the service's logging driver to journald when its logs are collected. Use it only when the logging behaviour itself is what you are measuring.

chalupa preview shows the resulting Compose and lists supervised restarts on their own line.

agentAccess

Optional, metadata-only grants per selected service. readOnly: true is the only value — there is no write grant to express:

services: [api, worker, postgres]
agentAccess:
  api:
    readOnly: true
  postgres:
    readOnly: true

A grant marks which services an agent may inspect (chalupa connect --format app-brief renders the brief). It changes nothing at provision time: no port, credential or permission is derived from it, and services without a grant simply do not appear in the brief. Grants may only name selected services, and a workspace environment (no compose) has none.

expose

Optional, metadata-only, like agentAccess: it changes nothing on the server (the Compose project and the firewall are untouched; only SSH is ever exposed). It tells chalupa urls, chalupa open, chalupa exec --format env and the launch report how to present a service you already forward.

services: [gateway, postgres, redis]
expose:
  gateway:
    protocol: http
    open: /docs
  postgres:
    scheme: postgres
  redis:
    protocol: tcp
    scheme: redis
    visibility: private

Keys are the service names chalupa urls prints: a selected Compose service, ollama (with inference), or port-<n> for a tunnel.extraPorts entry. Any other name is a config error. A key that parses but matches nothing that is forwarded (a service that publishes no port, or a port-<n> whose port a Compose service already publishes) is ignored with a warning on stderr from chalupa urls and the launch report, because only the Compose inference can tell. The key is optional and has no defaults, so a config without it behaves exactly as before. open is also sent to the console (except with cloud.services: hidden); scheme never leaves your machine. A shared service's hostname label, <service>--<environment> (plus ---public for auth: none), must fit in 63 characters after lowercasing and turning _ into -, neither name may contain --, and a two-letter service name is refused (it would look like an internationalized label); the config is refused before anything runs otherwise. A top-level share: { provider: ngrok } picks the share provider (ngrok, the only one available; naming vercel-ssh, which is reserved, is refused when the config is validated). Not allowed with provider: chalupa.

probes

Optional, at most 6. A probe is a command that runs inside a selected compose service on every heartbeat and prints one flat JSON object of numeric counters on stdout; the environment page charts the counters next to the container timeline:

services: [api, worker]
probes:
  orders:
    service: api
    command: "curl -fsS http://127.0.0.1:3000/metrics/counts | jq -c '{completed, queued}'"
  queue:
    service: worker
    command: "redis-cli --raw --json LLEN jobs"
    timeoutSeconds: 12

• service must be one of the selected services; anything else is a config error before a server exists.
• command (max 500 chars) runs through sh -lc inside the service container. It must print a single JSON object whose values are finite nonnegative numbers — strings, objects and arrays are dropped, and only the first 10 keys (sorted by key) are kept. Anything else — unparseable output, a non-object, a nonzero exit — is reported as an error reading, never a failed heartbeat.
• timeoutSeconds is an integer 1–30, default 5. The heartbeat runs probes sequentially, so the sum of the timeouts bounds how long a beat can take; a slow probe suite delays the next beat rather than overlapping it.
• Probes are read-only by construction: the agent runs the command and parses its stdout, nothing more. They are refused for managed hosts and workspace (no compose) environments.
• Probes require cloud.url — the readings travel in the heartbeat, and the charts live on the environment page of the console.

The command travels shell-quoted in /etc/chalupa/probes.json, so the quoting you write is the quoting the service shell sees. The errors the page can show are timeout, invalid (not a flat JSON object of numbers) and exitN (the command exited with status N).

diagnostics

Optional, at most 32. A recipe is a named, read-only command you declare once so chalupa diagnose and chalupa evidence can run it on the box, instead of a campaign script re-implementing the same collector:

services: [mongodb, elasticsearch, api]
diagnostics:
  mongo-rs-status:
    service: mongodb
    description: Replica set health
    run: [mongosh, --quiet, --eval, "JSON.stringify(rs.status())"]
    readOnly: true
  es-health:
    service: elasticsearch
    run: [curl, -fsS, "http://127.0.0.1:9200/_cluster/health"]
    readOnly: true
    timeoutSeconds: 10

• service must be one of the selected services. The command runs inside that service's container (docker compose exec -T).
• run is an argv array, never a shell string: there is no interpolation, no pipe and no sh -c. Shells and state-changing programs (sh, bash, env, xargs, sudo, rm, kill, chmod, ...) are refused at load, and curl and wget refuse their write flags (-X, -d, --data, -F, -T, -o, ...), so a recipe can only GET.
• readOnly: true is required. It is the author's statement that this recipe only reads state; leaving it out is a config error.
• timeoutSeconds is an integer 1-60 (default 20) and maxBytes caps the captured output (1024-1048576, default 65536). JSON output is parsed and shown as JSON; anything else is shown as redacted text.
• Only recipes declared here can ever run. The MCP server does not run them; chalupa diagnose, chalupa evidence --live and the snapshot down takes before the sink do. Recipes are refused for managed hosts and for workspace (no compose) environments.

Declare recipes for state you would otherwise open a shell to check; see Logs, diagnose and evidence.

compute

compute describes the host to provision. region, size and image are opaque provider slugs, so the same block works for any provider Chalupa grows support for.

This block was called droplet in earlier versions. That spelling still parses and is canonicalized to compute, but it raises a compute_key_deprecated warning and will be removed. Setting both is an error rather than a silent preference.

compute:
  region: nyc3
  size: s-2vcpu-4gb
  health:
    url: http://localhost:8080/health
    status: 200

The health check runs inside the server, so it can use localhost. The schema requires HTTP(S), loopback, and a URL without embedded credentials. It must target a port published by one of the selected services; the preview fails if the URL's port does not appear among the inferred tunnels. The check runs in two places. On the server, cloud-init starts it (chalupa-health.service) and the boot overlays that follow wait for it. After provisioning, chalupa up opens a temporary tunnel, waits for the forwarded ports and for this URL to answer with status, for up to timeoutSeconds, and fails if it never does. A failed up leaves the server running and billing: inspect it, or run chalupa down. chalupa test, chalupa exec and chalupa launch run the same check through their own tunnel before they continue. It is a single endpoint check, separate from compute.readiness, which up waits for only with --wait.

The size directly affects estimated cost. Check the current provider price before creating the resource.

compute.prebaked is a boolean, default false. When true, the image field must point to a golden snapshot that already ships Docker, tools, static scripts, system users, and pre-enabled systemd units. cloud-init then skips package installation and static provisioning entirely, writing only the per-environment payload. Build the golden image with chalupa snapshot build --config PATH --confirm "bake <name>" (it prints the estimated cost and time first, and changes nothing without --confirm; with no ssh.identityFile or CHALUPA_TASK_SSH_IDENTITY the ssh-agent must hold a key registered in the account, checked before anything is created). The agent, forwarder and Monitor on a prebaked box are still refreshed over SSH on every chalupa up, so a golden image no longer freezes them at the day it was baked; see how the runtime reaches the box.

Set compute.image: golden:latest (with prebaked: true) to follow the newest golden this machine baked for the environment and region, instead of pasting a snapshot id after every bake. chalupa snapshot status lists the goldens with their age and the Chalupa and Monitor versions that built them, and chalupa doctor --config warns when the one in use is older than 30 days or was baked by an older Chalupa or Monitor than the config pins.

The golden image masks apt-daily and unattended-upgrades, so boxes booted from it never run apt in the background; picking up OS updates means re-baking. It also carries /etc/chalupa/golden.json (Chalupa version, bake time, provider, Monitor version), so you can cat it on a box to see what the image contains and how old it is.

compute.readiness

Typed probes a stack must ALL pass before it counts as up — the replacement for hand-written wait-*.mjs scripts. Five shapes, not a DSL:

compute:
  readiness:
    - tcp: { service: postgres }
    - http: { service: web, path: /healthz }
    - http: { service: api, path: /, expect: { status: [200, 401] } }
    - mongo: { service: mongo }
    - amqp: { service: rabbit }
    - cmd: { command: "node scripts/wait-es.mjs", timeoutSeconds: 30 }

A network target names a compose service — resolved to the same local port chalupa tunnel forwards for it —, a remotePort that the tunnel forwards (the way a tunnel.extraPorts entry is addressed, since it has no service name), or an explicit host/port on your machine. The cmd probe runs locally and exits 0 when ready; it is the escape hatch for app-specific readiness. http passes on a 2xx or 3xx answer (redirects are not followed), so a 404 or an error page is not ready. When a healthy app answers something else, list the accepted codes with expect.status ([200, 401]); the list replaces the default range. mongo sends the driver handshake (an OP_MSG hello, answered by MongoDB 3.6 through 8) and amqp sends the 0-9-1 protocol header and expects the server's Connection.Start (what a healthy RabbitMQ answers), so no client libraries are needed.

A 200 is not always ready

An http probe can also read the body. json selects one value by a dotted path (status, nodes[0].state) and compares it with in (a list) or equals (one value) — exactly one of the two:

compute:
  readiness:
    - name: elasticsearch
      http:
        service: elasticsearch
        path: /_cluster/health
        json: { path: status, in: [yellow, green] }

A cluster that answers 200 while its status is red is not ready. The status check runs first, then the body; a body that is not JSON, or a path that is missing, fails with the value it found.

When the probe counts

Three options sit beside the probe kind (not inside it) and work on every kind:

compute:
  readiness:
    - name: mongo
      mongo: { service: mongo }
      stable: { count: 5, intervalSeconds: 2 }
    - name: web
      http: { service: web, path: /healthz }
      timeoutSeconds: 600

Wait with chalupa wait once the tunnel is up: it polls every probe until all pass together (a service that reboots during seeding is re-checked), prints one line per probe with the time it became ready, and exits 1 on timeout. chalupa preview shows the declared probes offline. The same probes gate chalupa up --wait, the specs of chalupa test, and the command of chalupa exec. See Make servers ready faster.

tunnel

tunnel:
  extraPorts: [8080, 9005, 9012]
  onReuse: none
  afterUp: none

With local: leased, chalupa proxy start adds readable names for the web services: http://<service>.<environment>.localhost:7355. See chalupa proxy.

Each field is optional, and tunnel: { onReuse: none } on its own is valid. Ports reach the tunnel through the stack's recorded outputs, so adding extraPorts to a running environment takes effect on the next chalupa up, not on the live server. How the supervised tunnel behaves, and why you would set onReuse or afterUp, is in Supervised tunnels.

ssh

For DigitalOcean, ssh.authorizedKeys accepts inline ssh-ed25519 … public key lines. Each entry creates a deterministic account SSH key named chalupa-<environment>-operator-<index>; its ID joins any keys selected by ssh.keys or ssh.useAllAccountKeys on the server. Inline keys can also be used alone. Private keys and authorized_keys command options are not accepted. When omitted, account-key behavior is unchanged.

Authorize specific keys whenever possible:

ssh:
  keys:
    - demo-operator
  allowedCidrs:
    - 198.51.100.24/32

keys accepts names, IDs, or fingerprints from the account. allowedCidrs controls the port 22 firewall and is required; Chalupa never supplies a world-wide default. The example range belongs to RFC 5737. Replace it with the narrowest operator-controlled source range, normally a /32 for one IPv4 address or /128 for one IPv6 address.

An isolated demo can use this explicit opt-in instead:

ssh:
  useAllAccountKeys: true
  allowedCidrs:
    - 198.51.100.24/32

keys and useAllAccountKeys are mutually exclusive. Chalupa never implicitly authorizes every account key. Explicit 0.0.0.0/0 or ::/0 entries produce a high-visibility validation warning and are reserved for isolated synthetic diagnostics, not real environments.

identityFile names the private key every lifecycle SSH uses (tunnel, bootstrap, teardown), absolute or ~/-relative to the operator home. chalupa setup writes it as ~/.config/chalupa/ssh/id_ed25519, Chalupa's own keypair: it never reuses a personal key, and only the public half is registered with the provider. An explicit SSH_IDENTITY environment variable still wins over the config value.

boot

Host-level tweaks that used to be SSH hand-edits — an nginx socket override, a memory bump, a replica set — declared in the config so they survive every up instead of dying with the server on down:

boot:
  files:
    - path: /etc/nginx/conf.d/upstream.conf
      content: |
        upstream app { server 127.0.0.1:8080; }
    - path: /etc/systemd/system/redis.service.d/override.conf
      content: |
        [Service]
        Environment=REDIS_MAXMEMORY=1g
  commands:
    - command: docker compose --project-directory /opt/chalupa exec -T api app reload
      timeoutSeconds: 60
  mongoReplicaSet: true

files (at most 16, 64 KiB each) are written by cloud-init as root with 0644 permissions before anything runs. Destinations are restricted to an allowlist of drop-in locations: /etc/nginx/conf.d/*.conf, /etc/systemd/system/ (drop-in shape only — a .conf inside a *.d directory or a plain .conf; never a full unit, which would be a second, unreviewed way to execute code at boot), and /etc/chalupa/overrides/ for anything an app command reads. Any other path is a config error at load time, offline, before a server exists.

commands (at most 8, 2000 characters each, timeoutSeconds 10–600 defaulting to 120) run once, as root, through bash -lc, after the stack health probe has passed. A systemd oneshot guards them with a marker file, so reboots and repeated provisioning never re-run what already succeeded; the marker is written only after every command exited 0, so a half-applied overlay retries on the next boot — write idempotent commands. Each command's exit status lands in the journal (journalctl -u chalupa-overlays.service), and the first failure stops the unit without blocking the stack itself: nothing in the Compose stack depends on it.

mongoReplicaSet: true configures a selected MongoDB service (detected from its image or its run.chalupa.database.kind label) as a single-node replica set named rs0, so transactions and change streams work. mongod gets --replSet rs0 at Compose generation time, and a one-time unit initiates the set after the stack is healthy — idempotently, so a persistent data volume that was already initiated is left alone. The flag is refused offline when no MongoDB service is selected.

When the service already declares a command (in Compose or through overrides), the flags are appended rather than replacing it: --replSet rs0 unless a --replSet is already present, and --bind_ip_all unless a --bind_ip or --bind_ip_all is. This applies only to a command that is mongod's own argument list (it starts with mongod or a flag); a wrapper such as bash -c ... is still refused, because the flags would reach the shell instead of mongod.

persist

persist:
  sizeGb: 20
  backup:
    retentionCount: 3
    verifyCommand: ls -la /mnt/chalupa-verify
  onDemand:
    retireAfterIdleHours: 24

Increasing capacity and deleting a volume have different consequences; read Data and seeding before changing it. backup.consistency: quiesced is refused: snapshots are crash-consistent.

cache

cache:
  sizeGb: 50
  pruneAfterDays: 14
  retireAfterIdleHours: 12

A disposable volume that holds Docker's images and build cache, so repeat boots skip image pulls and rebuilds. It lives in its own <name>-cache stack, never in <name>-data, so deleting it can never touch your data.

chalupa cache-up creates the volume (confirmation phrase cache <environment>) and chalupa cache-nuke deletes it (drop cache <environment>); the next chalupa up attaches it when it exists, and boots from the boot disk when it does not. It bills monthly until you delete it, and cache-nuke refuses while a server is attached. Available on DigitalOcean and Hetzner; a managed GPU host and a workspace environment with no Compose stack are refused, and so is an environment whose name ends in -cache. See Reuse a server, a cache and a build.

To give copies (chalupa up @COPY) a warm start, run chalupa cache-snapshot while the primary is down (it is refused while a server has the cache attached, and asks for snapshot cache <environment>); a new copy's cache is created from that snapshot instead of empty. See copies.

apps

Images you build yourself. The Compose file Chalupa copies must use published images, so apps declares the ones you build instead and chalupa apps build and chalupa apps up print the script that builds and starts them. The scripts are printed, not run: running one is a separate step.

apps:
  context: .
  compose: ./docker-compose.apps.yml
  images:
    - name: web
      dockerfile: ./Dockerfile
      context: .
      target: runtime
      swap:
        build: bun run build
        workdir: .
        copy:
          - from: dist
            to: /app/dist
        keep: 3
  build:
    mode: remote
    cacheVolume: true
    memory: 8g

images[].swap fields, all optional except copy:

apps needs compose and services, and is refused for managed GPU hosts.

cleanupRecipes

Named, reviewed commands that clear or restore state between rounds. A recipe is written and reviewed once in the config, so an operator or an agent never has to type a free-form shell command to reset the box.

cleanupRecipes:
  clear-queue:
    description: Empty the jobs queue
    service: redis
    command: redis-cli FLUSHDB
    timeoutSeconds: 30
  load-orders:
    description: Restore the orders dataset
    restore:
      dataset: orders
      service: mongo
      command: mongorestore --host mongo --archive=/dataset --gzip --drop
      gate:
        kind: count
        command: mongosh --quiet --host mongo --eval 'db.getSiblingDB("shop").orders.countDocuments()'
        min: 1000

Each key is the recipe's name (lowercase letters, digits and -, up to 40 characters). A recipe needs exactly one of command or restore.

A restore recipe needs persist (the dataset lives on the protected volume) and its service must be in services. Run a recipe with RECIPE=<name> CONFIRM_CLEANUP="cleanup <name> <environment>" chalupa cleanup, or restore a dataset with CONFIRM_RESET="cleanup <name> <environment>" chalupa reset --dataset <dataset>. Both are authorized with an environment variable, not --confirm. Recipes are refused for managed GPU hosts. See Load a dataset once.

idleShutdownMinutes

idleShutdownMinutes: 45

Omitting the field disables idle observation. A value from 5 to 10,080 minutes is reported by the agent and lets the console derive an absolute deadline.

The server never receives a deletion credential. When the control plane's external idle reaper is deployed with DIGITALOCEAN_WRITE_TOKEN, the deadline is an automatic compute-shutdown policy: the worker rechecks the Chalupa tag and live-CI state before destroying the server, then records the transition. The protected data stack is never targeted. Without that worker configuration the deadline is informational and the operator still runs chalupa down. For a separate demo or test deadline, configure session and register the local expiry runner; it is independent from idle observation.

seed

seed:
  command: ./scripts/restore-orders.sh
  onBox: true

A bare string, seed: bun run seed:demo, still works and means a local command with onBox: false.

Run it with chalupa seed. An on-box seed needs no tunnel and makes no per-record round trip over SSH, which is what makes loading a large dataset slow through the tunnel. Do not embed credentials in the command: it is stored as a local Pulumi output. See Data and seeding.

test

test:
  runner: cairn
  config: ./cairntrace.config.yml
  environment: chalupa
  suitesRoot: ./flows
  suites:
    smoke: {}
    checkout:
      flows: ./flows/checkout-v2

Suites that chalupa test runs from your machine against the server's tunnelled ports. Beta. The full field list, the confirmation phrase, the options and the exit codes are on Run a suite with chalupa test.

cloud

cloud:
  url: https://chalupa.example.com
  heartbeatSeconds: 30

This enables agent installation and configuration. The URL must be an HTTPS origin without a path, query, or fragment. heartbeatSeconds accepts values from 15 to 300 seconds and defaults to 30. The chalupa up flow obtains the HMAC key from the secret store; it is never declared here.

services controls whether the launch report tells the console which services the environment forwards, so its Connect card can list them. named (the default) sends each service's name, protocol and remote port; the card then offers chalupa open <service>. hidden still sends protocol and port but replaces every name with service-1, service-2, ... in remote-port order and never sends an open path. It only covers the launch report and the Connect card: the box's heartbeat still names its containers and services, and the environment page shows them. Local ports are never sent.

cloud:
  url: https://chalupa.example.com
  services: hidden

credentials

credentials:
  tvault:
    project: acme-work

Names the TinyVault source for this config's own credentials, so an employer account and a personal account can use different projects. project defaults to chalupa. Environment groups are not supported (tvault reads them without its agent and from the group's own project). Only names live here; values stay in TinyVault. The control-plane runtime credentials (database, admin, cron) are not affected.

report

report:
  evidence:
    publish: local      # off | local
    when: failed        # failed | always
    maxBytesPerRun: 16777216
    retentionDays: 7

chalupa report (and the results phase of chalupa test) builds a small evidence pack for each failed run from the run directory the test runner wrote on your machine. Every field is optional and the values above are the defaults.

• publish: local keeps the files on your machine with fcheap save and a time-to-live of retentionDays; only a reference travels to the console, which shows the restore command. off keeps nothing. Uploading evidence so the run page can open it directly (cloud) is coming next and is refused for now.
• when: failed packs only runs that did not pass; always packs every run.
• include and exclude are run-relative globs. The defaults include report.json, run.json, agent_context.md, outcomes/*, clips/* (and videos/clips/*) and the screenshots of the failing step (the reserved entry @failing-step). They exclude network/**, traces/**, console/** and *.har, which carry cookies and request bodies. exclude always wins. Setting include replaces the default list.
• maxBytesPerRun caps one pack (default and maximum 16 MiB). When it bites, the failing screenshot and the structured results are kept and the largest low-priority files are dropped.

Symlinks are never followed, and a pack only ever contains regular files from inside the run directory. Evidence is best effort: if fcheap is missing or an upload is refused, the run is still reported and the report prints which evidence was not published.

session

An explicit session describes a disposable demo or test run:

session:
  purpose: test
  expiresAfterMinutes: 120
  maxLifetimeHours: 8
  maxExtensions: 2
  keepFor: 45m
  reuse: auto
  logs:
    retentionDays: 7
    maxTotalBytes: 67108864

Sessions require cloud.url. The deadline is control-plane metadata, not a deletion credential on the server: a local teardown runner is what destroys an expired server. See Expiry and the local teardown runner, Warm boxes and reuse, and chalupa status --json, which reports what is left as extensionsLeft.

session.logs

The effective retention is the smaller of retentionDays and your plan's cap: 7 days on Free and Solo, 30 days on Crew. A longer value is clamped, not rejected, so a lapsed plan shortens retention without breaking the run.

Other session.logs keys select what is collected: services (a map of service to include or exclude; the pseudo-service box selects the server's own units), projects (other Compose projects on the same box, up to 16) and filters (up to 32 entries of service, keep and drop regular expressions and a per-service maxBytes, applied on the server before anything is uploaded).

maxChunkBytes cannot exceed maxTotalBytes. Database and cache logs stay excluded unless a project opts them in. How the bytes are collected, shared between source sessions and retained is in Private log artifacts.

observability

Monitor is opt-in. With telemetry on (the default) it requires cloud.url:

observability:
  monitor:
    version: 2.2.0
    sha256:
      amd64: "1dc2311b80c1e7d0c34c038819dde1c19a87d9c64b18351a17667c3a542d4131"
      arm64: "2d9cd0d209cec0472c4406e4e829966a511d1a6fa6f30bbe333babba21f9c6f8"
    sampleSeconds: 5
    windowSeconds: 30

These independently verified digests pin the exact Linux archives published for Monitor v2.2.0. When changing the version, replace both values with the matching lowercase 64-character digests from that release's checksums.txt before validation. Chalupa derives the GitHub release URL; configuration cannot redirect the root installer to another host or path.

Instead of copying a version and two digests, write version: reviewed and leave sha256 out. It resolves to the Monitor release this Chalupa has verified, together with that release's digests, so the pin cannot rot; naming your own digests next to it is refused.

observability:
  monitor:
    version: reviewed

Fields, relative to observability:

On Hetzner the Monitor installer shares the 32 KiB user-data limit with the rest of the startup configuration, so a large Compose stack may not fit it.

The pieces that run on the box, and what each leaves the box with, are described in Performance telemetry:

• How the runtime reaches the box (delivered over SSH on every chalupa up, refreshed with chalupa box refresh, Beta).
• Crash capture (Beta, for container deaths in the Compose projects you list).
• Reading Monitor from your terminal (chalupa monitor VERB, a read-only pass-through).

Mandatory validation

Before chalupa up, preview the config:

export DEMO_CONFIG="$PWD/chalupa.yml"
chalupa preview --config "$DEMO_CONFIG"

The output must match the remote Compose stack you intend to operate. up also runs a lighter launch gate (preview and CI plan) by itself; CHALUPA_STRICT_GATE=1 makes it run the full chalupa validate gate instead.

Host-Ollama inference

The experimental inference block replaces the need for a legacy loop when Chalupa hosts the model; your agent harness runs locally:

inference:
  model: qwen3.8:27b
  pull: true
  maxModelBytes: 25769803776
session:
  purpose: test
  expiresAfterMinutes: 60

Weights use temporary host storage by default. Add inference.cache.sizeGb only when you want a separately billed retained volume.

Use chalupa setup --inference --provider digitalocean to generate the surrounding provider and SSH configuration. The weight limit is required; pull defaults to false. contextSize is optional: omitted or auto negotiates the session window at launch, while an integer from 1024 to 1,048,576 fixes the default window for BYOC. Managed fixed contexts are limited to 2048–262144 tokens; its cache is limited to 20–500 GiB. A small fixed window can trigger early compaction when an agent’s system prompt consumes most of it; prefer auto for coding agents. inference requires a session expiry and cannot be combined with loop. The default local tunnel port is 11435; the remote port is 11434. cloud is optional for this workflow. See inference setup and limits.

inference.agents

chalupa launch starts a coding agent against the tunnelled model. The model, endpoint and context always come from inference; agents holds the per-project knobs on top of the launcher's defaults:

inference:
  model: qwen3.8:27b
  maxModelBytes: 25769803776
  agents:
    default: opencode              # a bare `chalupa launch` starts this one
    opencode:
      args: [--agent, plan]        # appended before any `-- ARGS` at launch
      config:                      # deep-merged over the generated opencode.json
        small_model: chalupa/qwen3.8:27b
    omp:
      args: [--no-session]         # ephemeral sessions for throwaway runs
      config:                      # deep-merged into omp's per-run --config overlay
        modelRoles:
          smol: ollama/qwen3.8:27b

Model selectors inside config use each agent's own syntax: OpenCode sees the GPU as provider chalupa, omp as provider ollama. The primary model never needs to be repeated; it is filled in from inference.model. Keep separate configs (for example chalupa.e2e.yml) for scenarios that need a different model, context or agent defaults, and select one with --config.

For GPU inference reporting, cloud.ingestKeyId optionally identifies the per-environment ingest key. This public ID selects the organization and environment at ingestion; the matching secret remains in TinyVault. Scoped keys support heartbeat, Monitor and local reports. Configurations combining a scoped key with remote CI, loops or private-log collection are refused. Without it, the legacy key writes only to the platform organization. See GPU samples and model reports.

When inference.model is omitted, Chalupa uses qwen3.8:27b (~18 GB of Ollama weights). Allowing room for context and runtime requires gpu-large or gpu-max; preview and up reject this default on gpu-small (20 GiB VRAM).