Copying and moving

Four words, one job each:

A whole box packs the same way: see moving a box below.

#One project

tiffin projects duplicate shop shop-copy             # a copy on this box
tiffin projects export shop -o shop.tiffin           # one file
tiffin projects import shop.tiffin --name shop-2     # a new project from it
tiffin projects move shop --to prod                  # to another box (a name from `tiffin up`)

The dashboard has the same under a project's Settings › Copy & move (Duplicate, Export, and the move command to copy), and New project › Import a .tiffin file.

#Duplicate

A full copy on the same box: the database, buckets and files, KV keys, secrets, settings and apps (started again from the same images or files). The copy gets its own addresses: a box name that starts with the project's moves with it (shop → shop-copy, shop-api → shop-copy-api); an app served at its own app name (the old default) or only at custom domains gets the copy's default (shop-copy, shop-copy-<app>); any other name gets the new name added (www → www-shop-copy). Custom domains and GitHub deploys stay with the original; the job's notes say which. The copy starts its own History, with one first entry, "Duplicated from shop". To undo a duplicate, destroy the copy.

#Export

tiffin projects export <project> [-o file] writes one .tiffin file (a zstd-compressed tar) that streams to your computer as it is made. Inside, ordinary files you can use without Tiffin (tar --zstd -xf shop.tiffin):

Secrets stay sealed to the box key unless you pass --include-secrets: then anyone with the file can read them. The database is one consistent snapshot; files and cache keys are read live. An export needs full access to the project, since it hands out all of its data.

#Import

tiffin projects import <file> makes a new project from an export, beside the box's other projects; it never replaces one. A name already in use is refused: pass --name. Under another name the apps get that project's own addresses, as with a duplicate. The database loads as the new project's own Postgres role, so an archive can do nothing the project could not do itself. Then the apps start from the archive's images or files, and the project's History comes along if it was exported.

If an app does not start, the import fails (the CLI exits non-zero) though the project is there with its data: the result names the app, why its deploy failed and what to do. Deploy that app again once fixed, or destroy the project and import again.

Secrets sealed to another box need that box's key: --secrets-key-file <file> (its /var/lib/tiffin/platform/secrets.key). Or --without-secrets imports the rest and lists the secrets to set again (tiffin secrets set). Archives from the same box, and .env archives, need nothing.

A name destroyed less than 7 days ago is refused too: re-creating it would bring back the destroyed project's data (that is how its undo works).

#Move

tiffin projects move <project> --to <box> moves a project to another box this CLI knows (see ~/.tiffin/boxes.json). The export streams from this box straight into an import on the other (secrets travel inside it, never stored on your computer), with its History. Then it:

• prints each app's old and new address;
• re-points custom domains: with --update-dns the new box sets their DNS records where its DNS provider holds the zone; otherwise it prints the records to set;
• stops the project here: its apps go down, its data stays (tiffin projects start <project> brings it back). Destroy it here once you are happy with the move.

If the import fails, an app of it not starting included, nothing here changes. Agents get the same as the project_move tool of tiffin mcp, when the CLI knows more than one box.

#Stop and start

tiffin projects stop <project> stops every app of a project and keeps them stopped: deploys, restarts and rollbacks are refused until tiffin projects start <project>. The data and settings stay. Queued jobs and workflow turns wait without spending attempts, and crons do not fire; on start the jobs are delivered and each cron continues from its next tick (ticks that fell inside the stop are skipped). Both are changes in History, so undo works too.

#API

#Moving a box

A box packs into one file and unpacks on another box: same projects, data, apps, people and tokens.

tiffin box export shop.tiffin --key-out shop.key   # on the old box
tiffin box import shop.tiffin --key-file shop.key  # on a fresh box

#Export

tiffin box export [file] writes one archive (.tiffin, a zstd-compressed tar) and ends with its size and SHA-256. It streams to your computer as it is made, so the box needs no spare disk (--store writes it on the box first instead).

What goes in:

Left out unless you ask: logs, metrics, build logs and database snapshots (--with-history). Never included: caches, build caches, the box's backups.

Postgres travels as SQL rather than a physical copy, so it restores into any later Postgres and does not drag the old cluster's identity along.

Consistency. App containers and the object store pause while the snapshot is taken (usually well under a second; the export reports writesPausedMs). Every database dump reads the same instant; the rest streams afterwards while the box keeps serving.

The key. Secrets in the archive stay encrypted to the box key (/var/lib/tiffin/platform/secrets.key on the box), which is not in the archive unless you pass --include-key. Import needs it, so keep it before you delete the old box: --key-out shop.key saves it from a local box. With --include-key, anyone holding the file can read every secret.

#Import

tiffin box import <file> uploads the archive, verifies it on the box (every entry against the archive's own digest), then restores it: databases, Valkey, files and app images, then one restart of the box's service to swap in the state. It waits until every project has converged and ends with the box's status. A small box imports in seconds plus the upload.

• A box that already has projects is refused. --replace --confirm <box name> replaces everything on it, after taking a full backup of it.
• Archives from a newer Tiffin are refused: update the box first (tiffin up --name <box>, or Settings › Updates).
• The old box's tokens work on the new one, and so does the new box's own owner token.
• The new box keeps its own domain, Tiffin build, backups and backup schedule.
• The certificate authority becomes the old box's. The CLI updates its copy; run tiffin trust again for browsers.
• Deploys older than the live one cannot be rolled back to (their images did not travel).

#API

For the dashboard and agents (owner or admin; importing is owner only):