Sessions and policy

Integration preview

Session management follows the implemented control-plane branch.

A session is a short-lived grant for one agent objective. It is not a copy of a provider credential and should not be treated as a permanent API key.

Create the smallest useful session

vops agent session create \
  --client codex \
  --objective "Deploy the current repository to staging" \
  --repository . \
  --target web-1 \
  --environment staging \
  --expires 60 \
  --max-operations 30 \
  --max-spend-eur 0

The dimensions are independent:

Dimension	Question it answers
Objective	Why does the session exist?
Repository	Which project context may it use?
Target	Which hosts or resources may it affect?
Environment	Development, staging or production?
Expiry	How long can the path remain open?
Operations	How many brokered operations may run?
Spend	How much provider creation may be proposed or executed?

Zero provider spend is the correct default for deployment to an existing host.

Handle the token

The raw token is returned once. The local store keeps its hash. Give the token only to the intended local client process and do not put it in:

• flui.yaml;
• repository files;
• chat transcripts;
• shell history;
• logs or issue reports.

The token identifies the session; it does not contain provider or SSH secrets.

Public and private capabilities

Public product knowledge and capability metadata can be read without a session. Private inventory and all mutations require an authenticated session.

Policy then evaluates:

• session status and expiry;
• requested capability;
• target and environment;
• current operation count;
• provider-spend limit;
• whether an immutable plan and approval are required.

The outcome is allow, deny or approval required. A denial must occur before the core executor resolves credentials.

Lifecycle

vops agent session list
vops agent session show <session-id>
vops agent session pause <session-id>
vops agent session resume <session-id>
vops agent session revoke <session-id>
vops agent session stop-all

• Pause blocks new work but preserves the session for review and later resume.
• Resume reopens a paused session only if its other limits remain valid.
• Revoke permanently closes that session.
• Stop all revokes every active or paused session.
• Expiry closes the grant automatically; it is not a substitute for revoking a completed task.

Production

Production should not inherit staging authority implicitly. Create a separate session with a production environment and a specific objective. Keep explicit plan approval even if the same application was previously deployed to staging.