Use a session
Once you submit a request, each session has its own detail page where you launch features, track status, and manage the session. Open a session from the Sessions page or from the link shown after you request one.
Session detail tabs
The detail page has three tabs:
- Session — the main view: status and timeline, purpose, target servers, available features, and the CLI quick start.
- History — activity recorded during the session.
- Analysis — an AI risk analysis of the session, available after the session ends.
What Alpacon checked
The Session tab shows a “What Alpacon checked” block with the facts your request was decided on: the AI agent’s reported name if there is one, the account the session runs as (on Windows servers an audit label, since commands run as SYSTEM; see permissions on Windows), and your purpose. “Policy check, not malware detection.” links to What Alpacon checks, and what it doesn’t. Approvers see the fuller block on the approval card, which adds the approval rule and who had to approve; see Reviewing requests.
Launch features in the browser
On the Session tab, the Available features card lists what the session grants.
- Features that open in the browser—web terminal, file transfer, and code editor—show a Launch button. Click it to start working. If a feature needs a target server, you’re prompted to pick one.
- CLI-only features—execute commands and port forwarding—show the command to run, with a copy button.
Launch is available only while the session is Active, and the code editor and port forwarding require a server that has those features enabled.
Set your username before launching a feature for the first time, if you haven’t already. See username.
Attach from the CLI
To use a session’s features from the command line, attach to it first. The Get started in CLI card shows the command:
$ alpacon work-session use SESSION_IDAfter attaching, run the feature commands shown on each feature—for example alpacon websh, alpacon exec, or alpacon tunnel. See the alpacon work-session CLI reference for all commands and flags.
Session lifecycle
A session moves through these statuses:
| Status | Meaning |
|---|---|
| Pending | Request submitted, waiting for administrator approval. Not usable yet. |
| Approved | Approved and scheduled to start. Usable once it becomes active. |
| Active | Currently usable. Launch features, attach from the CLI, extend, or terminate. |
| Completed | Ended early by the user while active. |
| Expired | Reached its end time. |
| Rejected | The administrator rejected the request. |
| Cancelled | The requester cancelled before approval. |
| Revoked | The administrator revoked an approved session before it became active. |
The timeline on the Session tab shows where the session is in this lifecycle.
Manage a session
The actions available depend on the session’s status and your role:
- Extend session — On an active or approved session, extend the end time with a preset (+1, +2, +4 hours) or a custom time, and give a reason. The new end time can’t exceed your workspace’s maximum duration. See Extending with approval below.
- Terminate now — On an active session, end it immediately. All active connections close right away. This can’t be undone. Available to the session owner and administrators.
- Cancel — On a pending session, cancel your own request before it’s approved.
- Revoke — Administrators can revoke an approved session before it becomes active.
Extending with approval
A reason is required when you extend a session; leave it blank and the extension is refused until you resubmit with one. Whether the extension needs a Superuser’s approval follows the same rule as requesting a new session—see Automatic approval. Extending an AI-agent session that holds MFA-bypass sudo policies waits for a person’s approval in an Enforce workspace.
- Auto-approved — the new end time applies immediately, and any sudo permissions attached to the session follow it.
- Otherwise — the extension becomes a request in the approvals queue. The session keeps its current end time until a Superuser decides. The session page shows a banner with your reason, the new end time you asked for, and how long the request itself has before it lapses.
Only one extension request can be pending on a session at a time—Extend session stays disabled until this one is decided or lapses.
A Superuser can approve the request as asked, or shorten the new end time—never lengthen it past what you asked for. Either way, the result is checked again against your workspace’s maximum duration at the moment of approval, and any sudo permissions attached to the session follow the approved end time once it takes effect.
You can extend a session more than once. Each extension is checked against the same limits and needs its own reason and, unless your workspace auto-approves it, its own approval.
How do I extend a session that’s about to expire?
Open the session and click Extend session, or run alpacon work-session extend SESSION_ID --expires-in 2h --reason "..." from the CLI (see alpacon work-session extend). Do this before the session expires—if your workspace requires approval, the current end time keeps counting down while the request waits for a decision, so leave enough time for someone to review it.
Why was my extension rejected?
A few things can keep an extension from taking effect:
- A Superuser rejected the request. The reason isn’t shown on the session page—ask the approver directly.
- Nobody decided before it lapsed. If the request or the session itself reaches its deadline first, the request lapses without applying, and the session’s end time is unchanged. Submit a new extension request if you still need more time.
- Your workspace refused it outright. Some workspaces block extension requests before they’re even queued—for example, based on who’s asking. This shows up as an immediate error when you submit, not as a pending request.
How do I approve or shorten an extension request?
Open the request from the approvals queue—it’s labeled Session extension. Alongside the reason, current end time, and requested end time, you can leave the new end time as requested or pick an earlier one; you can’t set it later than what was requested. Approve applies the end time you left in place; Reject leaves the session’s current end time unchanged. See Request types for what an approver sees and can adjust.
Changing features or servers
Administrators can edit the features or target servers of an approved or active session. Changes may need another approval before they take effect. While a change is awaiting approval, you’ll see a banner noting that some changes are pending, and you can cancel the pending change. On an AI-agent session, adding servers waits for a person’s approval; adding or widening sudo policies also waits in an Enforce workspace. Removing or narrowing sudo policies applies at once.