Skip to main content
Some projects only run on one person’s laptop. The .env file, the local database with its schema and test data, the xcconfig with the API host: they live there and nowhere else, so nobody else can build the app without asking that person, and when two people work on it their setups drift apart. orchestra setup share records what the repo needs on your machine and hands it to the teammates you name, encrypted to each of them. orchestra setup apply restores it into their own clone. When your setup changes (a new migration, a new env key), their agent is told, and apply catches them up without touching their own data. It works in Orchestra Local, through the repo’s own git remote and your own git credentials. Nothing goes through an Orchestra server.

Quick start

On the teammate’s laptop, once, in their clone:
That publishes their setup key to the repo’s git (it says nobody has shared with them yet). On your laptop, where the app runs:
Back on the teammate’s laptop, the first time, they check your key’s fingerprint with you (you see it with orchestra setup key; apply shows theirs) and name you:
After that, a plain orchestra setup apply keeps them up to date. It prints what it did, file by file and database by database, how you run the app, and what only they can do (for an iOS app: choose their own team under Signing and Capabilities in Xcode before building to their phone).

What is shared

Each database is shared as its schema plus a snapshot of its data, so the teammate starts with the same rows you test against. On the teammate’s laptop, only config files are written (an .env, an .xcconfig, a secrets plist), never a file git tracks and never through a link that leads out of the repo. A file you add with --include that is not a config file is listed for them but not written. A Postgres snapshot is loaded with pg_restore as a temporary database user that cannot run programs or touch files on their machine, and it is handed to their own user afterwards. A database URL must be on their machine. One risk stays with you: a snapshot can contain database functions, and if your app connects to its database as a superuser, those functions run with superuser power when the app calls them. Connect your app as an ordinary database user, and only apply setups from teammates you trust.

Who can read it

Everything except a short list of what is in the setup (file paths, database names, tool names) is encrypted before it leaves your laptop: values, file contents, schema, data and commands. It is encrypted to each person you name with --to, using a key that was made on their laptop and never leaves it, and to you. Anyone else who can read the repo, and the git host itself, sees only ciphertext. The encryption is the open, independently reviewed age format (age-encryption.org), with one recipient per person, so Orchestra adds no encryption of its own. Each setup is signed with your key. A teammate’s laptop remembers your key the first time they apply, and refuses a setup signed by any other key. Your laptop remembers each teammate’s key when you name them, so a different key appearing in git under their name is not used until you name them again. orchestra setup key shows your key’s fingerprint, to read out to each other.

Staying in step

When you change something and share again, your teammate’s agent sees one line at their next prompt, for example: “Vank’s setup changed: 1 new migration, 1 new env key (SUPABASE_ANON_KEY). Run orchestra setup apply to catch up.” orchestra setup status says the same. apply then:
  • adds env and xcconfig keys you added, and updates keys you changed;
  • keeps any key they changed themselves, and says so. --theirs takes yours;
  • runs only the new migrations against their own database, each all or nothing, so their own rows stay. Each migration runs from their own checkout, so they pull your commit first; apply says so when one is missing;
  • reports a schema change that came with no migration. Only --reset reloads a database from your copy, and their rows in it are lost;
  • loads a database that is new or empty.
A tool they lack (say psql) is named with how to install it, and everything else still applies. A setup for another repo, or an older copy of yours put back in git, is refused. So is a setup under your name with a key their laptop does not know for you: they check with you, then pass --trust-new-key.

Stopping

shares again without Sam. Sam’s next apply changes nothing and tells them. What Sam already received stays readable to them, so rotate those secrets (new API keys, new database passwords) and share again.

Without git

orchestra setup share --out setup.orchestra --to-key <key> writes the same encrypted setup to a file. The teammate runs orchestra setup key and sends you the line it prints, then applies the file with orchestra setup apply --file setup.orchestra.

For agents

In Orchestra Local your agents have two tools: get_setup_status and apply_setup. Once you have applied a teammate’s setup yourself, ask “set me up like Vank” and the agent catches you up, then passes on what only you can do. Neither tool ever returns a secret value. An agent cannot use a setup for the first time, trust a new key, take the teammate’s side of a conflict (--theirs) or reset a database: you run those in a terminal.

Not included

Apple signing identities and provisioning profiles stay with each person, and hosted environments are not copied.