Appearance
Agents and approvals
An agent is a machine identity of kind "Agent (AI tool)". You create it in the web app under Settings → Agents & automation → Agents & CI: you choose the Vaults it may reach and a lifetime, and the web app shows its token (gsm_…) once. The agent never sees your password or any other Vault; it can list the names and types of items in the Vaults you give it, never their values.
A CI job uses a different kind of identity, a service account. It is not an agent and is not approved per read; see CI and GitHub Action.
Profiles on this machine
sh
geslar agent add ci-bot # a person only, in a terminal: paste the token at the hidden prompt
geslar agent list # profiles on this machine and their state on the server
geslar agent remove ci-bot # delete the local profile
geslar agent remove ci-bot --revoke # also revoke the identity on the server (from your signed-in session)- Enrol within 15 minutes of creating the token; an agent that is not enrolled in time is revoked.
- The token is read only from the hidden prompt (or
--stdinfrom a pipe), never from an argument or the environment. The profile is stored sealed on this machine; the token cannot be shown again. If the local key is lost (for example after a restart on a system without a persistent key store),agent listsays so and you create a new agent. - On Linux an agent profile needs a persistent key store: a Secret Service such as GNOME Keyring, KWallet or KeePassXC. Without one,
agent addstops before the token is used (exit code 7). On Windows and macOS the OS keychain is used. - Create a separate Vault for the agent and give the identity access to that Vault only.
Using a profile
A profile is selected with --agent <name> or GESLAR_AGENT:
sh
geslar --agent ci-bot item list # names and types only, never a secret field
geslar --agent ci-bot run --reason "run the test suite" -e DB_PASSWORD=geslar://Test-agent/Database/password -- npm testUnder an agent profile, and with a service account, a Vault is given by its name: the keywords personal, osobno, family, company and work are not resolved (a Vault that is itself named like that is found by its name; otherwise it is an error).
An agent profile deliberately cannot print a value: read and inject are refused. run works only for a command that you have allowed (see MCP), always with masking, and with a reason of 1 to 200 characters that the person who approves can see.
Approvals
The boundary is a person's approval on the server, given with a fresh 2FA code. The first time an agent needs to read items of a Vault, a person has to approve it. run stops with exit code 8, prints a link and a short code, and starts nothing:
sh
geslar --agent ci-bot approval request Test-agent --reason "run the test suite" --ttl 1h --uses 5
geslar --agent ci-bot approval status <requestId>
geslar --agent ci-bot approval list- Open the link (or Settings → Agents & automation → Approvals), check that the short code is the same as in the terminal, read the reason, and approve with your password and a fresh 2FA code, every time. You can approve less than was asked (shorter time, fewer reads), never more.
- A request is valid for 10 minutes. The CLI does not wait for the decision and has no way to approve or deny anything; it never opens the browser by itself.
--itemlimits a request to one item (name orid:<id>; repeatable),--ttlsets how long the approval lasts (at most 8 hours),--useslimits the number of uses.
Exit code 8 means "a person must approve first": wait, do not retry blindly. It is deliberately different from 5 (access denied or outside the scope), so a script or an agent can tell "wait for a person" from "no". All exit codes are in the reference.
Plans and limits
- Signing in as a person (
geslar login, thenread,run,inject) needs a Premium, Family, Business or Enterprise plan; the Free plan does not include it. - Agent profiles and CI service accounts (machine identities) need the same plans, and their number is limited. Agents and service accounts count together; only an identity that is neither revoked nor expired counts.
| Plan | Machine identities |
|---|---|
| Free | 0 |
| Premium | 5 |
| Family | 5 |
| Business | 20 |
| Enterprise | 50 |
- On Premium and Family the limit is per person, across their personal and family organizations; on Business and Enterprise it is per organization.
- Family: only the payer. For a personal or family organization, the plan that counts is the plan of the issuing person's own personal organization. On a Family plan, that is the person who pays and holds it, so the Family plan gives agents and service accounts to the payer only. A member of the family counts only with a paid plan of their own.
- The plan is checked every time an identity is used, not only when it is created: when it lapses, the identity stops working.
What this does not protect against
An agent that is allowed to run a program that can run code can send that program's secrets elsewhere. Limit what you give it, and approve with care. Anything that runs as you can also use your own unlocked session, which no agent profile or approval stops: see Limitations.