Adjoint Docs Product ↗
Menu

Getting started: admin

This walks through the full admin journey: create your org, provision the AWS data plane, curate a golden snapshot, and invite your team. Budget 30–40 minutes — most of it is the (unattended) cluster provision.

If you were invited by someone else's admin, you don't need this page — see Getting started: developer instead.

Prerequisites

1. Create your org

$ adj signup
Server URL: https://api.stagdb.com
Organization name: Acme Inc
Org slug (short id used at login): acme
Admin email: [email protected]
Password (min 8 chars):
Created org "Acme Inc" (acme); logged in as [email protected] (admin).

Next steps:
  adj init                      # guided cluster + data onboarding
  adj invite create <email>     # invite a developer

You're now logged in as the org's founding admin. Admins are developers too — this same account can clone and use instances like anyone else.

2. Register a cluster

$ adj cluster register prod
Registered cluster prod (ad202dff-61e6-4239-b905-004ba07913de).

⚠  Agent join token (shown once — store it now):
3BHKXgIATasePOcLdEmySwoMDevYuJ8xdFs2D2B2e7Q

The token is consumed automatically by the provision step below — you don't need to copy it by hand unless you're bootstrapping the agent manually.

3. Provision the data plane

Run this from anywhere — no checkout needed:

$ ADJ_REGISTRY_PASSWORD=*** adj cluster provision prod --developers 8
This provisions real AWS infrastructure for cluster prod — 3 nodes (m6i.xlarge), FSx 512 MB/s / 480 GiB (sized for ~8 developers) — and rotates its join token. [y/N]: y
AWS identity: arn:aws:iam::123456789012:user/ops-admin
IAM permissions OK (30 actions verified).
Provisioning started in the background (pid 41217), ~20–30 min.
  status: adj cluster status ad202dff-61e6-4239-b905-004ba07913de
  log:    tail -f /home/you/.config/adj/provision/ad202dff-61e6-4239-b905-004ba07913de.log
  kubeconfig (on success): /home/you/.config/adj/kubeconfigs/acme.yaml

Before touching anything it verifies your AWS credentials and simulates the IAM permissions the module needs — a definitive gap prints exactly which actions to grant, then exits. --developers sizes node count and FSx throughput/storage with tight defaults; override individual knobs with --nodes, --node-type, --fsx-storage-gib, or --fsx-throughput if you need to. --agent-image/--operator-image default to the published data-plane images, so you only need to pass them to pin a different version. The apply runs detached by default — add --foreground to stream it in your terminal instead.

Poll status until it's done:

$ adj cluster status prod
ID:            ad202dff-61e6-4239-b905-004ba07913de
Provisioning:  succeeded
Started:       2026-07-19T09:14:02Z
Log:           /home/you/.config/adj/provision/ad202dff-61e6-4239-b905-004ba07913de.log
Name:          prod
Agent health:  connected
Instances:     0
Last seen:     2026-07-19T09:38:41Z

On success, the cluster's kubeconfig is written to the adj-owned path ~/.config/adj/kubeconfigs/<context>.yaml (mode 0600) — your own ~/.kube/config is left untouched. adj kubeconfig prints the path for the active context.

4. Connect a source

Point Adjoint at the Postgres database you want to curate golden snapshots from (e.g. an RDS read replica):

$ adj source create --host prod-replica.abcdef.us-east-1.rds.amazonaws.com \
    --dbname app --username adjoint_ro
Read-only DB password:
Source 6167f95c-11b9-47f4-a1c1-ddca639fe715 registered (endpoint metadata only).
Credentials Secret adjoint-import/adjoint-src-app applied to the data-plane cluster.

Next: adj import run --source 6167f95c-11b9-47f4-a1c1-ddca639fe715 --golden <name>

The endpoint and the name of a credentials Secret are registered with the control plane; the actual username/password are written directly into your data-plane cluster as a Kubernetes Secret (namespace adjoint-import) via kubectl. Credentials never transit or persist in the Adjoint control plane.

5. Import a golden snapshot

$ adj import run --source 6167f95c-11b9-47f4-a1c1-ddca639fe715 --golden prod-pg16 --pg-major 16 --wait
waiting for import c333d541-b468-476f-954e-7632052de120: Pending -> Probing -> Provisioning -> Importing.... -> Snapshotting -> Registering -> Cleaning -> Succeeded
ID:        c333d541-b468-476f-954e-7632052de120
Source:    6167f95c-11b9-47f4-a1c1-ddca639fe715
Golden:    prod-pg16
Version:   v1
PG Major:  16
Phase:     Succeeded
Message:
Size:      42.0Gi
Created:   2026-07-19T10:02:11Z
Finished:  2026-07-19T10:08:52Z

The import spins up an ephemeral Postgres in the data plane, streams a dump from the source, snapshots the volume, and registers the result as the next immutable golden version. Re-run adj import run later to build a new version from a fresh dump — existing clones of older versions keep running.

6. Share it with your team

Newly imported goldens are admin-private by default:

$ adj catalog share prod-pg16
Golden "prod-pg16" is now shared with the org.

7. (Optional) pre-warm clones

If developers clone often, keep a pool of ready-to-claim clones so adj clone fast-claims one in ~15–30 seconds instead of the on-demand FSx provisioning path (typically ~2 minutes; up to ~10 under FSx load):

$ adj pool create prod-pg16 --target-warm 5
Pool d866a56e-da6f-4b61-9d2a-1fa8e0486acf created for prod-pg16 v1 (target 5 warm). Filling in the background.

A pool pins the latest ready version of the golden at creation; it does not auto-follow newer versions — refresh it by removing and recreating it.

8. Invite your team

$ adj invite create [email protected] --ttl 168h
Invite for [email protected] (user) created. Token (shown once):

  dd14fc5f12254de9143c2e461dc52b826d959dc35895566f4f1871e0b9858209

Send them ONE command:

  adj join adj1.eyJ2IjoxLCJzIjoiaHR0cHM6Ly9hcGkuc3RhZ2RiLmNvbSIsIm8iOiJhY21lIiwidCI6ImRkMTRmYzVmMTIyNTRkZTkxNDNjMmU0NjFkYzUyYjgyNmQ5NTlkYzM1ODk1NTY2ZjRmMTg3MWUwYjk4NTgyMDkifQ

(legacy form: adj join --server https://api.stagdb.com --org acme dd14fc5f12254de9143c2e461dc52b826d959dc35895566f4f1871e0b9858209)

That single adj join adj1.... line is everything the invitee needs — it encodes the server, org, and token. Forward it as-is. --ttl accepts 15m–720h (default 72h); --role admin invites another admin instead of a developer.

9. Set quotas

Cap how many instances each developer (and the org as a whole) can run at once:

$ adj quota set --per-user 3 --per-org 30
Quota updated: 3 per user, 30 per org.

Keep an eye on things

Next

Your team is ready to self-serve. Point developers at Getting started: developer.