AI agent session governance means every agent or human session on a server states its purpose before the work, and, for work done inside that session, the record of what ran comes from the session itself, not from the agent's own report. In Alpacon, that unit is the Work Session: you declare a purpose, choose the servers and features, set a deadline, and get approval where your workspace requires it. Then you run the task and read the record of what ran through Alpacon's governed channels. This walkthrough covers that first run, step by step.
The session states what it is for before the first command runs.
Step 1: open the request form
There are two ways in. On a server card or detail page, click Connect and the server is pre-selected. Or open Sessions under Access in the sidebar and click New session.
You will fill in four things:
- Accessible servers: at least one, and each must be commissioned and online.
- Session purpose: required.
- Session features: at least one.
- Session duration: how long the session may last.
If you are a Superuser you also see Assignee, which defaults to you. Details are in the Work Session docs.
Step 2: write a purpose someone can approve
The purpose is Markdown, up to 2,048 characters, and it is required. The approver reads it before approving the session, and it is shown beside the command line on the command-approval card. A purpose that says "maintenance" tells the approver nothing. One that says "rotate the nginx log files on web-03 and confirm disk usage drops below 80%" lets them judge whether a command fits.
A good purpose names three things: the task, the target, and what done looks like.
On the hosted web console, Generate drafts a purpose and suggests features from the servers you selected. Revert undoes the draft. Edit it before you submit; a generated purpose is a starting point, not a finished one.
Step 3: pick features and a duration
Features are the channel types the session can use. Web terminal, file transfer, execute commands, and privilege elevation are pre-selected. Code editor and port forwarding need the server owner to enable them on the server first. Uncheck what the task does not need. A log-rotation job does not need port forwarding.
For duration, pick 1, 2, or 4 hours, or choose Custom with a start time of Now or Scheduled and a length. The workspace maximum is 4 hours by default, and you cannot request longer. The approver can grant a shorter window than you asked for, so ask for what the task needs.
Click Request session.
Step 4: get it approved
An approver reviews requests that need approval: a Superuser, or another approver your workspace has assigned to those servers. A Superuser's own request is approved automatically, so if you are the Superuser, you skip this step for your own sessions. A session declared for an AI agent is the exception, below.
Unless your workspace admits it automatically, a request from anyone else starts as Pending (a deny policy can also refuse it). So does a session declared for an AI agent, by default. A Pending request's servers and features show as "requested" and cannot be used yet. You can Cancel a pending request at any time. A session declared for an AI agent needs a person's approval by default, even when a Superuser creates it, and it cannot include the web terminal.
Once approved, the session is Approved until its start time, then Active.
Step 5: run the task
On an Active session, use Launch for the web terminal, file transfer, or code editor. Command execution, port forwarding, and the CLI terminal run from the CLI:
alpacon work-session use SESSION_ID
That command sets it as the active session for your current workspace. After that, run the command shown on each feature in the session, for example alpacon exec, alpacon websh, or alpacon tunnel.
If the task runs long, use Extend session (+1, +2, or +4 hours, or a custom length). An extension requires a reason. Your workspace's admission policy decides it: it can be approved at once or routed to an approver. The current deadline still applies while it is pending, so extend before time runs out. Only one can be pending at a time, and the new end time can be at most the workspace maximum from now. You can extend more than once. From the CLI: alpacon work-session extend SESSION_ID --expires-in 2h --reason "...".
When you are done, Terminate now closes all connections immediately. It cannot be undone, and it is available to the session owner and admins.
Step 6: read the record
Open the session detail page. The Session tab shows status and timeline, the purpose, the servers, and the features. The History tab shows the activity recorded in the session.
Commands that run through the session's governed channels are recorded on that Work Session's timeline. The record comes from the session itself, so the answer to "what ran?" doesn't depend on an agent's own report. It covers what flows through Alpacon; a direct SSH login to the host is outside it.
What you have after one session
After one session you have a purpose written before the work, approval where your workspace requires it, a deadline, and a record of what ran on the governed channels. That is the shape every later session takes. Human and agent sessions use the same model.
