Copies and variants

A copy is a second environment built from the same chalupa.yml. A variant is a copy with a different shape. Any command that takes --config accepts the @COPY selector, which is described below.

Copies of one environment

One chalupa.yml can run several copies side by side, for example one per branch, per ticket or per agent. Select a copy with @COPY, or with -i COPY / --instance COPY, on any command that takes --config:

chalupa up @2              # a second copy: stack <name>-2, its own box
chalupa urls @2            # its services, on their own local ports
chalupa ssh @2
chalupa share port-8080 @2
chalupa down @2
chalupa instances          # the primary and every copy of this file

• The copy is the environment <name>-COPY everywhere: its Pulumi stacks, its console page, its confirmation phrases (launch shop-2) and its session.
• A copy gets leased local ports (tunnel.local: leased) so its tunnel does not collide with the primary's; the file's ssh.localPorts pins stay with the primary. If the file sets tunnel.local itself, every copy follows it as written, pins included, and copies can then collide.
• With persist:, a copy has its own <name>-COPY-data volume, created on its first up from the primary's newest data snapshot (take one with chalupa data-snapshot --rate <usd> on the primary: it shows the plan and its id, and --plan <id> creates it), or empty when there is none. instances.data: clone refuses the launch instead of starting empty. The plan printed before the confirmation says which.
• With cache:, a copy gets its own image cache, created from the primary's cache snapshot when there is one, so its first build does not start from zero. Take that snapshot with chalupa cache-snapshot while the primary is down (it is refused while a box has the cache attached).
• A copy's volumes outlive chalupa down @COPY like any volume. Remove its cache with chalupa cache-nuke @COPY; its data volume goes only through the deliberate path in deleting data, with @COPY on the config path.
• --config chalupa.yml@2 is the same as --config chalupa.yml @2. Write @COPY before a --: everything after it belongs to the child command.
• A file that pins instance: itself cannot select another copy.

Naming a copy:

chalupa up --new                       # the next free number, reserved for you
chalupa instances reserve --json       # agents: reserve first, get the exact phrase
chalupa up @3 --confirm "launch shop-3"
chalupa up --from-branch               # named after the current git branch

A number that was ever launched on this machine is not handed out again by --new, so a new copy never lands on an old copy's data.

Variants are copies with a different shape. Declare them in the file and select them like any copy:

variants:
  light:
    services: [api, postgres]
    compute:
      size: s-2vcpu-4gb

chalupa up @light    # stack <name>-light with the overlay merged in

chalupa instances lists the primary, its copies, reservations and declared variants, and MCP clients see each copy as its own environment.