Skip to content
Clonit

How Clonit Works

Clonit is a single binary (the agent) that snapshots, sanitizes, and shares databases. It works fully standalone; the optional Clonit Cloud adds team features on top. This page explains the moving parts from the outside — what runs where, where your data lives, and what leaves your machine.

The pieces

Section titled “The pieces”
graph LR
  A[clonit CLI] --> B[local metadata db]
  A --> C[your databases]
  A --> D[your S3/R2 bucket]
  E[web UI - clonit serve] --> A
  A -. optional .-> F[Clonit Cloud]
  • The agent (clonit) — the CLI you install. It runs the native database tools (pg_dump, pg_restore, psql, and the MySQL equivalents) against databases you point it at, and keeps track of everything it has built.
  • The web UI (clonit serve) — a browser interface embedded in the same binary. It talks only to your local agent; nothing extra to install or deploy.
  • Clonit Cloud (optional) — a hosted catalog for teams: shared snapshots, org-wide targets and storage profiles, and cross-device access. Every core workflow works without it.

Where your data lives

Section titled “Where your data lives”
Data Where Notes
Targets, snapshots records, storage profiles, analyses <config-dir>/clonit.db Local metadata database
Settings (log level, defaults, cloud connection, secret key) <config-dir>/config.yaml Settings only — no target or snapshot data
Snapshot files Your working directory, and optionally a bucket you own Via a storage profile
Cloud catalog (optional) Your org in Clonit Cloud Names and metadata — see below

Sensitive fields in the local metadata database — connection URLs (which contain credentials) and storage access keys — are encrypted at rest; they are never stored in plaintext. See Encryption for details.

What leaves your machine

Section titled “What leaves your machine”
  • Standalone: nothing, unless you push. clonit push uploads snapshot files to a bucket you own, using credentials that never leave your machine.
  • With Clonit Cloud: clonit cloud sync uploads target metadata — names, database types, and non-secret configuration. Passwords stay local unless you explicitly choose a secret mode that shares them (see Push & Pull via Cloud). Snapshot uploads and downloads go through short-lived presigned URLs, so your browser and teammates never handle storage credentials.
  • AI analysis: clonit analyze sends schema information (table and column names and types — never row data) to the configured LLM to propose a sanitization query. See AI Sanitization Analysis.
  • The web UI never talks to the cloud directly. It calls your local agent, and the agent forwards cloud requests using its own API key — one authentication boundary, managed in one place.

The life of a snapshot

Section titled “The life of a snapshot”
  1. Build — clonit build dumps the target’s source database with the native tools and records the snapshot in the local metadata database.
  2. Sanitize — clonit sanitize (or clonit ephemeral, which does the work in a throwaway Docker container so your databases are never touched) applies your sanitization query and produces a sanitized snapshot.
  3. Push — automatically or via clonit push, the snapshot uploads to your bucket or your org’s managed cloud storage, with checksum verification and retries.
  4. Share / Pull — teammates pull it by index (your bucket) or snapshot ID (cloud), then clonit load it into their own database.

See also

Section titled “See also”