---
title: "Use a session"
description: "Use an approved work session in Alpacon. Launch features, attach from the CLI, check all eight statuses and time limits, and extend, end, or cancel a session."
---

> Full documentation index: https://docs.alpacax.com/llms.txt

# 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=terminals` or `?tab=editors` also 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](/use/audit/events/commands/#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](/reference/platforms/windows/#permissions-and-identity-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](/learn/security/what-alpacon-checks/). Approvers see the fuller decision on the approval card; see [Reviewing requests](/use/approvals/reviewing/#what-alpacon-checked).

## 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](/use/iam/users/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](/use/work-sessions/editor/sessions/) and [Terminal session management](/use/work-sessions/terminal/sessions/).

## 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_ID
```

After attaching, run the feature commands shown on each feature—for example `alpacon websh`, `alpacon exec`, or `alpacon tunnel`. See the [`alpacon work-session`](/reference/cli/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.

1. Pending: An approver approves a scheduled request
   - Rejected: An approver rejects it
   - Cancelled: The requester or a Superuser cancels it, or it is cancelled automatically before approval
2. Approved: Its start time arrives, or an authorized user activates it early
   - Revoked: A Superuser revokes it, or its assignee is removed from the workspace
   - Expired: Its end time passes before it starts
3. Active: An authorized user ends the session
   - Revoked: A Superuser revokes it, or its assignee is removed from the workspace
   - Expired: Its end time passes
4. Completed

Pending → Active: Approval with no future start time: straight to Active

### 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](/use/approvals/#who-may-approve-a-request) 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`](/reference/cli/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`](/reference/cli/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`](/reference/cli/work-session/complete/) | Anyone with permission to manage the session |
| Approved or Active | Revoked | [`work-session revoke`](/reference/cli/work-session/revoke/); the session page offers Revoke only while Approved | A Superuser |
| Approved or Active | Revoked | The assignee is [removed from the workspace](/use/iam/users/remove/#work-sessions) | 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](/use/audit/sessions/).

## Time limits

See [Server access policies](/use/policies/server-access/) 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](#extending-with-approval) 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](/use/work-sessions/troubleshooting/#the-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](#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 revoke`](/reference/cli/work-session/revoke/) revokes 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](/use/approvals/#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](/use/approvals/). 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`](/reference/cli/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](/use/approvals/)—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](/reference/approvals/#session-extension) 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.

## Related docs

- [Request a session](/use/work-sessions/create/)
- [Session features](/reference/work-session-features/)
- [After a session](/use/audit/sessions/review/)
- [Session history](/use/audit/sessions/)
- [Troubleshooting](/use/work-sessions/troubleshooting/)

Source: https://docs.alpacax.com/use/work-sessions/detail/
