---
title: "Work sessions overview"
description: "Request time-bound access to Alpacon servers through a work session. Learn how requests, approvals, session states, and launched tools fit together in practice."
---

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

# Work sessions overview

Request a time-bound work session to access one or more servers.

## How a work session works

A work session is a **time-bound, approved grant of access** to one or more servers. Instead of connecting to a server directly, you request a session that says which servers you need, what you want to do, and for how long. Once approved, you can launch the tools you requested—a browser terminal, file transfer, the code editor, command execution, and more—until the session expires.

## Why work sessions?

Work sessions replace direct, always-on server access with access that is requested, reviewed, and recorded:

| Benefit | What it means |
| --- | --- |
| Least privilege | You only get the servers, features, and time window you ask for. |
| Approval built in | An approver reviews each request before access is granted: the one your access rules name, or by default a user with the Superuser role. |
| Time-bound | Sessions expire automatically, so access never lingers. |
| Fully audited | Every session, the features used, and the activity inside it are recorded. |
| One request, many tools | A single session can cover the terminal, file transfer, editor, command execution, and privilege elevation across several servers. |

## How it works

Working with a server follows four stages:

1. **Request**—From a server or the **Sessions** page, click **Connect** and choose the target servers, the [features](/reference/work-session-features/) you need, a purpose, and a duration. See [Request a session](/use/work-sessions/create/).
2. **Approval**—Your request enters the **Pending** state. An approver approves or rejects it; by default, that is a user with the Superuser role. You can cancel a pending request at any time.
3. **Active**—Once approved, the session becomes **Active**. Open its **Session** tab and choose a browser action on the server you want to use, or attach from the CLI.
4. **End**—The session ends at expiry, when you terminate it early, or when a Superuser revokes it. Ending the session closes its tunnels, terminals, and file transfers, and cancels commands that have not been delivered to a server.

See [Use a session](/use/work-sessions/detail/) for launching features, extending, and ending a session.

## Session states

A session is always in one of eight states. It moves along the line from **Pending** to **Completed**, or leaves it for one of the states below each step. The five end states are final: a session never leaves them.

A request admitted without review starts at Approved if scheduled for later, or Active if it can start immediately.

1. Pending: An approver approves it, with a later start
   - Rejected: An approver rejects it
   - Cancelled: The requester or a Superuser cancels it, or the requested end or pending limit (24 hours by default) passes before a decision
2. Approved: Its start time arrives, or an authorized user activates it early
   - Revoked: A Superuser revokes it, or its user is removed from the workspace
   - Expired: Its end time passes
3. Active: An authorized user completes it
   - Revoked: A Superuser revokes it, or its user is removed from the workspace
   - Expired: Its end time passes
4. Completed

Pending → Active: Approved with no later start: straight to Active

## Sessions in an advisory workspace

When a workspace's [execution control](/use/policies/server-access/) is set to **Advisory**, stage 2 doesn't apply. A session is admitted without review and becomes **Active** immediately—or **Approved** until a scheduled start time arrives—for every requester, including a session requested by an AI agent, which by default waits for a human decision under Enforce.

Nothing else about the session changes. It still covers only the servers and features you asked for, it still expires on its own, and it's still recorded end to end. The rules about which [system account](/use/work-sessions/account-selection/) a session may run as are unchanged.

What changes inside the session is when judgment happens, not whether it happens. Commands are judged after they run instead of before, and carry the **Advisory** verification status in [Commands](/use/audit/events/commands/#verification-status) and on the session timeline. `sudo` still needs its own authority and a recent verification—advisory removes the risk gate, not the requirement to be allowed.

An amber **Advisory** chip beside the workspace name in the top bar tells you a workspace is in this posture.

## Key concepts

**Features (scopes)**: the set of capabilities you request for a session—web terminal, file transfer, command execution, port forwarding, code editor, and privilege elevation. See [Session features](/reference/work-session-features/).

**Duration**: how long the session stays usable. Choose a preset or a custom length. The presets are 30 minutes, 1, 2, 4, and 8 hours, filtered by the workspace maximum. With the default 4-hour maximum, the form offers 30 minutes, 1, 2, and 4 hours. See [Request a session](/use/work-sessions/create/#5-session-duration).

**Status**: where the session is in its lifecycle—Pending, Approved, Active, Completed, Expired, Rejected, Cancelled, or Revoked. See [Session lifecycle](/use/work-sessions/detail/#session-lifecycle).

**Browser actions vs CLI**: how a feature is used. On an active session's **Session** tab, choose **Terminal**, **Files**, or **Editor** on the server you want to use. Command execution and port forwarding use the [Alpacon CLI](/reference/cli/) after you attach to the session.

## Where to find work sessions

Open **Sessions** under the **Access** group in the sidebar to see your sessions and create new ones. You can also start a session straight from a server—click **Connect** on any server card or detail page, and the server is pre-selected in the request form.

The **Open sessions** tab contains sessions you can still use or are waiting to start. Switch between tiles and a list; each page shows up to 12 sessions. The **Closed sessions** tab shows sessions that ended or were refused. Open a session to see its details and recorded activity. For an active session, the detail page's **Resume** tab lets you return to your open terminals and editors.

## Getting started

1. [Request a session](/use/work-sessions/create/)—choose servers, features, and duration
2. [Session features](/reference/work-session-features/)—what each feature lets you do
3. [Use a session](/use/work-sessions/detail/)—launch tools, extend, and end a session

## Related docs

- [Connect to servers](/use/servers/connect/)
- [Terminal access (Websh)](/use/work-sessions/terminal/)
- [File management (WebFTP)](/use/work-sessions/files/)
- [Code editor](/use/work-sessions/editor/)

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