Skip to content
extraorbital
Documentation ExtraOrbital
Browse documentation

Start here

Deploy and rotate

Get your project's variables to production with push, see what reads them with remote, and replace secrets with rotate.

Three commands cover everything after provision:

CommandJob
push [target]Send the variables to where the app runs
remoteSee and remove what reads them
rotateReplace secrets, and put the new ones where they are used

Every destination gets credentials of its own, so revoking or rotating one never breaks your laptop, your teammates or another environment.

Deploy to Vercel

Link the folder with vercel link once, then:

sh
npx extraorbital push vercel --dry-run      # see what would be sent
npx extraorbital push vercel                # production
npx extraorbital push vercel --environment production,preview

You'll see each variable marked + (new) or ~ (replaces the value on Vercel), then one line per resource with the credential minted for it. Redeploy for the values to take effect. They are sent as sensitive and cannot be read back from Vercel.

Let the app read them keylessly instead

Nothing stored on the platform, and every credential handed out expires within the hour:

sh
npx extraorbital push vercel --keyless      # proven at once with your Vercel login
npx extraorbital push github --keyless      # prints a CI job to run once

In the app, read the variables with fromOIDC():

ts
import { fromOIDC } from "@extraorbital/neon/oidc"
const db = await fromOIDC()

In GitHub Actions or GitLab CI, npx extraorbital run --oidc -- npm test runs a command with them. Keyless access has the details, including Google Cloud.

Any other host

Netlify, Railway, Cloudflare Workers, Render, a VPS: write the variables to a file only you can read, then copy them into the host's settings:

sh
npx extraorbital push ./prod.env     # written 0600, with credentials minted for this file
npx extraorbital push                # a temporary file; its path is printed

Delete the file once you've copied what you need. Its credentials stay valid until you revoke them with remote remove, or replace them by pushing to the same file again.

See and remove what reads your variables

sh
npx extraorbital remote
Output
NAME                        KIND                READS              LAST
acme/web                    Vercel · keyless    every resource     used Nov 10
vercel:acme-web:production  Vercel · pushed     neon/db, redis/c…  pushed Nov 9 from ada-laptop
file:ada-laptop:tmp         File · pushed       neon/db            pushed Nov 8 from ada-laptop
sh
npx extraorbital remote remove vercel:acme-web:preview   # revoke what was pushed to preview
npx extraorbital remote remove acme/web                  # take an app's keyless access away

Removing revokes at once, so whatever runs with those credentials stops working. Values pushed to a host stay there until you delete them or push again.

Rotate after a leak

Rotate on the machine whose .env may have leaked, in the project's folder:

sh
npx extraorbital rotate --dry-run           # what would change
npx extraorbital rotate                     # every resource in .env, this machine's credentials
npx extraorbital rotate neon/db --grace 24h # one resource; the old secret works 24h more

rotate replaces this machine's own credential on each resource and rewrites its block in .env, printing only the variable names. Credentials other machines and destinations hold are untouched. A resource where this machine reads the shared primary is skipped and named: rotate <resource> rotates it, for every machine that shares it.

Rotate production

sh
npx extraorbital rotate remote vercel                          # production
npx extraorbital rotate remote vercel:acme-web:preview         # preview, by its remote name
npx extraorbital rotate remote acme/web                        # a keyless app: what it holds is revoked

rotate remote mints new credentials for the destination and pushes them there at once; the previous ones stop after 24 hours, or after --grace. A keyless app needs nothing pushed: its credentials are revoked, and it fetches new ones on its next request.

Rotate everything

After a leak you can't pin down, or when someone leaves the team, an admin or owner replaces every credential of the project in one go, from the folder linked to it:

sh
npx extraorbital rotate --all --dry-run       # what would change, nothing changed
npx extraorbital rotate --all --grace 24h     # every machine, production, keyless apps
Output
✓ Rotated 8 credentials of web, revoked 1, 1 pushed credential retiring
  neon/db · machine ada-laptop · rotated
  neon/db · machine bob-desktop · rotated
  neon/db · shared primary · rotated
  neon/db · keyless acme/web · revoked
  …
✓ Pushed new credentials to vercel:acme-web:production
  Other machines put their new secrets in .env by themselves, on their next extraorbital command

Every machine's own credential and the shared primary are rotated. Each machine gets the new secret in its .env on its next command, and yours gets it at once. Keyless apps have what they hold revoked and fetch new credentials on their next request. The Vercel project the folder is linked to is pushed to again. Any other destination keeps its old credential for the grace (24 hours by default) and is named, with the command to push to it before then. A sensitive resource is skipped and named: rotate <resource> rotates it with its password.

A member who runs rotate --all is refused. Members rotate their own machines' credentials with rotate.

What other machines see after a rotation

When someone else rotates a credential a machine reads (an admin's rotate --all, the dashboard, another folder of yours), that machine needs nothing done by hand. The next extraorbital command it runs in the project's folder notices that the secret in .env no longer matches and rewrites the block:

Output
↻ neon/db was rotated elsewhere: its new secret is in .env now

It checks at most every ten minutes per folder. A sensitive resource's secret takes its password, so .env is left alone and the line says so: extraorbital run <resource> -- <command> uses the new secret. Set EXTRAORBITAL_NO_ENV_REFRESH=1 to turn the check off.