envshed agent session

Give an AI agent short-lived, read-only access to one environment, optionally limited to specific keys, without handing it your login. The limits are enforced by the server, and every read is recorded in the audit log under the agent's name.

Usage

terminal

envshed agent session --env <slug> --ttl <duration> [options]
envshed agent session list [-o <org>] [--output json]
envshed agent session revoke <id> [-o <org>]

terminal

envshed agent session --env development --ttl 2h --keys API_KEY,DATABASE_URL
envshed run -e development -- npm test

Options

Option	Description
-o, --org <slug>	Organization. Defaults to the project config.
-p, --project <slug>	Project. Defaults to the project config.
-e, --env <slug>	Environment. Defaults to ENVSHED_ENV, then the project config.
--ttl <duration>	How long the session lasts, such as 30m or 2h. Default 1h, minimum 1 minute, maximum 24 hours. The server enforces the maximum.
--keys <list>	Comma-separated keys the session may read. Without it, every key in the environment.
--agent <name>	Name recorded in the audit log. Defaults to ENVSHED_AGENT_NAME, then claude-code inside Claude Code, then cli. It is self-reported, so treat it as a label, not proof of identity.
--reason <text>	Why the session is needed, shown to whoever approves it. Do not put a secret here.
--timeout <duration>	How long to wait for a production approval. Default 10m.
--no-wait	Do not wait for a production approval. Exits with code 2.
--output json	Machine-readable output. It never contains the token.

The token stays out of sight

The command does not print the token, and no flag makes it do so. It is stored in the OS keychain, or in ~/.envshed/sessions.json (mode 0600) where there is no keychain, and envshed run uses it from there.

There is one local session per environment. Starting another replaces the local copy of the old one. The old one keeps working on the server until it expires or you revoke it, so revoke it if you no longer trust it.

What uses a session

Only envshed run picks up a stored session, and only for the organization, project and environment it was started for, against the same API URL. Other commands, such as pull and secret get, keep using your own login.

ENVSHED_TOKEN still comes first. If it is set, the stored session is ignored.

When a session has expired, envshed run stops with an error instead of quietly using your own login, which would give the agent more access than you meant. To go back to your login, run envshed agent session revoke <id>.

What a session can do

Sessions are read-only and limited to one environment, with or without --keys. The server refuses them on every route by default and admits them only on the routes below:

Route	What a session gets
Read an environment's secrets	Only allowed keys. ${REF} expansion stays inside the allowed keys of that environment: a reference to anything else is left as literal text and listed in referenceErrors.
Read one secret	The value for an allowed key, 403 for any other key, whether it exists or not.
Secret requests (envshed request)	Ask about allowed keys and see their requests.
Environment version (run --watch)	The version number.
Who am I (whoami)	The token's type and scope.

Everything else answers 403: version history, snapshots, secret links, share links, environment and project management, writes, and creating more tokens. A session also stops working as soon as its creator loses access to the environment.

Production approval

Environments have no separate tier setting, so Envshed reads the words in the slug and name, and any name it does not recognize is treated as production. A session starts without approval only when a word says the environment is not production (such as dev, local, test, qa, staging, homolog, preview or sandbox, with an optional trailing number) and no word says it is (production, prod, prd, live, producao, produccion). So main and eu-prod ask for approval, and dev2 does not. Renaming an environment changes the result.

When approval is needed, the command prints a link and waits. A person who can edit secrets in that environment approves or declines in the dashboard, where the request also appears in the notification bell. There is no API or CLI to approve, so an agent holding your CLI token cannot approve its own request. Approving your own request in the browser is allowed.

The token does not exist until the approved command collects it. It is generated on that one poll, returned once to the person who asked, and stored on the server only as a hash. The session's time starts then, so waiting for approval does not shorten it. An unanswered request closes after 30 minutes, and an approval nobody collects closes after 15.

If the command times out or you used --no-wait, run the same command again with the same options to pick up the same request.

Exit codes

Code	Meaning
0	The session is active and stored
1	Error, such as bad input, no access, or a token that was already collected
2	Waiting for approval, with --no-wait
3	Declined
4	Stopped waiting, or the approval request expired

List and revoke

envshed agent session list shows live sessions. Members see their own, and organization owners and admins see all of them. Sessions also appear in the dashboard under Settings > Service Tokens while they are live.

envshed agent session revoke <id> ends a session on the server, effective on its next request, and removes the local copy. The session's creator or an organization owner or admin can revoke it. Revoking cannot be undone.

What this does not protect against

This reduces accidental exposure. It is not a barrier against an agent that has shell access on your machine. Such an agent can read your keychain entries with the same tools the CLI uses, and it can use your own login to run other commands. The limits that hold regardless are the ones the server applies to the session token: expiry, revocation, the environment and the keys.

Anything the session can read, the agent can see, for example by running envshed run -- printenv. Limit --keys to what the task needs.