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 these tabs:
- Session: the servers and browser actions, sudo access, and CLI quick start. The right rail shows usage time, session information, purpose, policy checks, and administrator adjustments.
- Resume: your open web terminals and code editors in this session. Shown for an active session with either feature, or while a window remains open. Existing links with
?tab=terminalsor?tab=editorsalso open this tab. - Analysis: an AI risk analysis for a completed, expired, or revoked session. Not available on the Free plan.
- History: activity recorded during the session. A rejected command shows its reason and suggested next step when a reason is available; see Understanding a rejection.
What Alpacon checked
The right rail of the Session tab shows the account the session runs as (on Windows servers an audit label, since commands run as SYSTEM; see permissions on Windows), its purpose, what the policy check considered, and any administrator adjustments. It also shows how much of the session’s time has been used. The policy check links to What Alpacon checks, and what it doesn’t. Approvers see the fuller decision on the approval card; see Reviewing requests.
Launch features in the browser
On the Session tab, find the server you want to use. Its row offers Terminal, Files, and Editor for the browser features included in the session. Select the action on that server to open it. An unavailable action explains why, such as a disconnected server or an editor that is turned off. Browser actions work only while the session is Active. The CLI section gives commands for features you use from the terminal, including command execution and port forwarding.
Set your username before launching a feature for the first time, if you haven’t already. See username.
Open terminals and editors
A web terminal or code editor keeps running after you close its browser tab (an editor with no tab connected closes on its own after about an hour by default). The Resume tab lists the ones you opened in this session that are still open, so you can go back to them. The list shows each window’s type, server or terminal prompt, how long it has been open, and, when known, the OS and browser of the most recent connection (Environment). If it was last opened from the CLI, the list shows the client’s identification string instead.
- Reconnect opens the terminal or editor again in a new tab.
- Terminate (the power icon) closes it right away, without a confirmation step.
The tab lists only your own terminals and editors. Ones that have closed don’t appear, except that an editor that closed because no tab was connected may stay listed until you terminate it. See Editor sessions and Terminal session management.
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 has one of eight statuses. Its detail page shows the current status. Once a session is closed, open History to review its recorded activity. The audit session detail uses the same tabs; its initial tab depends on the session status and plan.
A request admitted without review skips Pending. It starts at Approved if scheduled for later, or Active if it can start immediately.
Approval with no future start time: straight to Active
- Pending
An approver approves a scheduled request
- RejectedAn approver rejects it
- CancelledThe requester or a Superuser cancels it, or it is cancelled automatically before approval
- Approved
Its start time arrives, or an authorized user activates it early
- RevokedA Superuser revokes it, or its assignee is removed from the workspace
- ExpiredIts end time passes before it starts
- Active
An authorized user ends the session
- RevokedA Superuser revokes it, or its assignee is removed from the workspace
- ExpiredIts end time passes
- Completed
Statuses
| Status | Meaning | What you can do |
|---|---|---|
| Pending | Waiting for an approver; access is not available. | Wait for review, or cancel if you created the request or are a Superuser. |
| Approved | Approved with a scheduled start. | Wait for activation, or activate early if you can manage the session. |
| Active | The session grants access within its scope and time window. | Launch features, run commands, request an extension, or end the session. |
| Completed | A user with permission to manage the session ended it. | Review its history; request another session to continue. |
| Expired | Its end time passed. | Request another session. An expired session cannot be extended. |
| Rejected | An approver rejected the request. | Ask the approver about the decision before submitting another request. |
| Cancelled | Cancelled by the requester or a Superuser, or automatically before approval. | Submit another request if access is still needed. |
| Revoked | A Superuser revoked it, or its assignee was removed from the workspace. | Ask an administrator before requesting access again. |
Completed, Expired, Rejected, Cancelled, and Revoked are final statuses. None can return to Active.
Transitions and who can trigger them
The approvers are the people your access rules name, with Superusers as the default. Permission to manage a session belongs to its assignee, the owner of its assigned API token, the owner of the application holding its service token, and Superusers.
| From | To | Trigger | Who |
|---|---|---|---|
| Request submission | Approved or Active | Admission without review; Approved for a future start, Active otherwise | Automatic, according to access rules and execution control |
| Pending | Approved | Approval with a future start time | An approver |
| Pending | Active | Approval without a future start time | An approver |
| Pending | Rejected | Rejection | An approver |
| Pending | Cancelled | Cancel request or work-session cancel | The requester or a Superuser; being the assignee alone does not allow cancellation |
| Pending | Cancelled | The request lapses before review, or its requested end time passes | Automatic |
| Approved | Active | The scheduled start time arrives | Automatic |
| Approved | Active | work-session activate, including before the scheduled start | Anyone with permission to manage the session |
| Active | Completed | End session, Complete session in Live activity, or work-session complete | Anyone with permission to manage the session |
| Approved or Active | Revoked | work-session revoke; the session page offers Revoke only while Approved | A Superuser |
| Approved or Active | Revoked | The assignee is removed from the workspace | Automatic |
| Approved | Expired | The end time passes before activation | Automatic |
| Active | Expired | The end time passes | Automatic |
When a session completes, expires, or is revoked, its web terminals, file transfers, port forwarding, and editors close. Commands not yet delivered are cancelled, the session’s sudo permissions end, and pending feature changes and extension requests are cancelled. Review the recorded activity in Session history.
Time limits
See Server access policies for workspace settings.
| Limit | Value | Where it’s set |
|---|---|---|
| Maximum session duration | 4 hours by default; 5 minutes to 7 days. | A Superuser sets it under “Policies” → “Server access”, in the Server defaults card. Raising it requires the web console. |
| Expiry warning | Once, within the last 10 minutes. | Fixed. |
| Extension end time | Within the maximum duration, measured from the extension request. | The same maximum session duration setting. |
For a new session, duration is measured from the scheduled start, or from the request time if it starts immediately. The form offers only presets within the maximum and caps custom durations. A request above the limit is refused rather than shortened automatically.
Within the last 10 minutes before expiry, the requester and assignee receive a warning in the in-app feed and as a browser notification. Token-only sessions do not receive this warning. If you still need access, request an extension before the end time, leaving time for approval.
After the end time, further operations are refused even if the page has not yet updated the status. Open connections close as the session is marked expired. If your session expired mid-task, request another session.
Manage a session
The actions available depend on the session’s status and your role:
- Extend session: Once the session has started, extend the end time with a preset (+1, +2, +4 hours) or a custom time, and give a reason. A scheduled session can’t be extended before its start time. The new end time can be at most your workspace’s maximum duration from the moment you ask, not from when the session started. See Extending with approval below.
- “End session”—On an active session, end it immediately. All active connections close right away. This can’t be undone. Available to anyone with permission to manage the session.
- Cancel: On a pending session, cancel your own request before it’s approved.
- Revoke: A Superuser can revoke a session that is approved or active, and it ends at once. In the console it’s offered on an approved session;
alpacon work-session revokerevokes either.
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 approval follows the same rule as requesting a new session—see Automatic approval. Extending an AI-agent session that holds sudo policies where the session approval takes the place of MFA 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 an approver 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.
An approver 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:
- An approver 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. If the session has not expired, submit another extension request. If it has expired, request another session.
- 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
The session owner and Superusers 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.