Concepts

Chalupa avoids maintaining a second infrastructure definition alongside your project. Compose continues to describe the services; chalupa.yml declares only which part of the stack should travel and which adjustments the remote environment needs.

Compose as the source of truth

The engine reads docker-compose.yml and derives:

• definitions for the selected services;
• ports that must cross the tunnel;
• named volumes used by those services;
• valid dependencies after unselected services are pruned.

Ports are not duplicated in a second list. If they change in Compose, the next preview picks up the change.

chalupa.yml as intent

chalupa.yml contains decisions specific to the remote environment:

• included services;
• overridden memory limits, variables, and commands;
• droplet region, size, and health check;
• persistent volume size;
• idle window;
• seed command;
• optional control-plane URL.

You should be able to integrate a new project by adding configuration, not a special branch inside the engine.

Ephemeral compute

The compute stack includes the droplet, cloud-init, and containers. It starts with chalupa up and is destroyed with chalupa down. Both commands delegate to the Taskfile, which owns the Pulumi lifecycle.

“Ephemeral” means replaceable, not unattended. While it exists, it:

• incurs compute cost;
• accepts SSH connections;
• exposes services only on loopback;
• emits heartbeats when the control plane is configured.

When it sinks, Chalupa retains the history and marks the environment as ended or without a signal, based on the evidence it received.

Persistent data

When you declare persist, block storage lives in a separate Pulumi stack, conventionally named <stack>-data. The droplet mounts it and maps named volumes to subdirectories.

By design:

• task down destroys compute, not data;
• a new task up can mount the same volume again;
• task data-nuke is the only operation intended to delete it;
• storage can continue to incur cost after the droplet no longer exists.

This separation lets you restore a seed once and reuse it across multiple test cycles.

Data stores have separate owners

The word “database” can refer to different systems in a Chalupa deployment. Keep their ownership and credentials separate:

Chalupa does not copy a Compose database into its control-plane Postgres. file.cheap does not share Chalupa's runtime or migration credential. Deleting one store must never be presented as cleanup for another.

The tunnel as a boundary

Chalupa rewrites every published port to bind to 127.0.0.1 on the droplet. task tunnel creates the matching ssh -L forwards and presents them as localhost on your machine.

The model reduces the public attack surface, but it does not replace basic practices: protect SSH keys, keep secrets out of the repository, and review the inferred Compose output.

Agent and control plane

Vercel does not open SSH connections to droplets or read local Pulumi state. The flow is push-based:

1. cloud-init installs the agent;
2. the agent observes containers, disk, uptime, and the idle window;
3. it signs the payload;
4. it posts to the ingest endpoint;
5. the control plane validates, persists, and derives the visible state.

If the signal ages, the environment becomes stale or unknown. Chalupa does not invent a healthy state.

Costs are estimates

The console combines the observed hourly rate for a resource with provider inventory and deployment history. Every monetary value is labeled estimated.

It shows these values separately:

• ephemeral compute;
• persistent storage;
• approximate month-to-date cost.

The provider invoice is authoritative. Price changes, taxes, credits, rounding, and unobserved resources can produce differences.

Suites and artifacts

A suite run describes its result, duration, metric, and environment. Large files do not belong in the control-plane database: a run stores references to a local fcheap stash, a committed private hosted file.cheap artifact, or a stable external link.

This lets the control plane answer “what happened, and where is the evidence?” without becoming an incomplete object store.