Colony & users
The colony is the people: your account, and the users allowed on each machine.
Identity
Every principal holds an ed25519 keypair. The public key is the NodeID, in
base32 without padding. Account keys live at ~/.ant/identity; a machine's key
lives on the machine.
ant colony signup # create an account (--name, --email)
ant colony login # sign in: --bundle, --identity, --passphrase
ant colony whoami # print your NodeID and account (--json)
ant colony profile # edit your own name/email (--name, --email)
ant colony export --out acct.json # portable bundle (--passphrase | --no-passphrase)
ant colony import acct.json # restore a bundle (--passphrase)
ant colony logout
The account's portable credential bundle is passphrase-encrypted by default (PBKDF2-HMAC-SHA256, 210k iterations, AES-256-GCM), and load re-checks that the key matches the profile NodeID. Because the NodeID is the key, the same identity logs in on any machine.
Roles
Each machine keeps a roster mapping NodeIDs to roles:
| Role | Capabilities |
|---|---|
owner | Everything, including ownership transfer |
admin | Everything but ownership transfer |
deployer | Read, deploy, OS-user management |
viewer | Read only |
ci | Read and deploy |
ant colony users list # list the roster (--json, --mirror)
ant colony users add <nodeid> --role viewer # add (links ant-<id> for OS roles)
ant colony users update <nodeid> --name "Ada Lovelace" --email ada@example.com
ant colony users update <nodeid> --system-user existing_unix_account
ant colony users update <nodeid> --no-system-user # detach the linked account
ant colony users update <nodeid> --role admin # change the role
ant colony users system-user <nodeid> --op lock # print create | lock | unlock | delete
ant colony users remove <nodeid> # remove (--purge deletes the account)
users list reads the machine daemon; --mirror reads the local roster copy
without contacting it. --json prints machine-readable output.
Adding a user with an OS-capable role (owner, admin, deployer) links the
deterministic ant-<id> unix account. users update can change the role
(--role), relink a different account (including one that already exists on
the machine) or detach it;
users system-user --op prints the root-run useradd / usermod --lock /
usermod --unlock / userdel command for the operator to apply. Ant records a
linked account; it does not create, verify, or own an account it did not make.
The local machine has one user, your account. Edit it the same way; with no
--machine the command targets this host, so you can link your own login:
ant colony users update "$(ant colony whoami --json | jq -r .nodeId)" --system-user "$USER"
User references (<nodeid> in the commands above) accept a full NodeID, an
unambiguous prefix of one, or an unambiguous display name or email, so
ant colony users update ezyj --name "Ada" works without pasting 52
characters. An ambiguous reference lists the candidates.
Your own account's name and email are separate from any roster: change them with
ant colony profile --name "…" --email "…" (the NodeID and key are unchanged).
Invites
An invite is signed by the inviter's account key and carries the destination machine NodeID, the role, and an expiry. Redemption is server-side: the daemon verifies the signature, expiry, that the invite is for this machine, the inviter's current role, and the grant matrix, and that the nonce is unused. Single-use is enforced by the daemon, and a leaked token can be revoked before it is redeemed.
ant colony invite --role deployer --machine prod # create (--email, --ttl)
ant colony invites # list pending (--revoke NONCE)
ant colony join --token ant_inv_… --alias prod # redeem on the other side
Ownership
The first owner is seeded out of band, ant-worker --owner <nodeid>, emitted
by ant nest bootstrap, or written into the machine's state.json as root.
Ownership can later move by election:
ant colony elect-owner <nodeid>
ant colony election-status
ant colony users update <nodeid> --role owner
ant colony recover --add-owner <nodeid> # break-glass restore if locked out