---
title: "Request a session"
description: "Request server access with an Alpacon work session. Choose servers, a connect account, features, and time, and check approval requirements before submitting."
---

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

# Request a session

Specify a purpose, servers, connect account, features, and duration in your work session request.

## How requests are decided

To work on a server, request a session describing the access you need. Your workspace's [access rules](/use/approvals/#access-rules) decide whether the request can start, needs approval, or is refused. The [approvers](/use/approvals/#who-may-approve-a-request) are the people those rules name, with Superusers as the default.

## Start a request

Start from a server's "Connect" button to preselect that server, or open "Sessions" under "Access" in the sidebar and choose **New session**.

## Fill in the request

The request is one page. The main form asks for the purpose, servers, connect account, features, and duration, in that order. The right rail appears below the form on a narrow screen. It shows the assignee, the selected account's availability on each server, how requested sudo access is handled at each risk level, and the result of the current choices. The assignee defaults to you. Superusers on the Essentials plan or above can select another user; on Free, the assignee is locked to you. See [Plans & billing](/use/workspace/plans-billing/).

### 1. Session purpose

Describe the work you need to do. A purpose is required and can contain up to 2,048 characters. If "Improve with AI" is available, enter a purpose and select servers before using it. You can edit the suggestion, choose "Improve again", or choose "Undo".

There is no separate title field. If AI title drafting is unavailable, the first nonempty line of your purpose becomes the session title (up to 128 characters). Where AI title drafting is available, the title is generated after you submit.

### 2. Accessible servers

Select at least one server for the task. Only commissioned servers that are online can be added. If you started from a server's "Connect" button, that server is already selected.

### 3. Connect as

Choose the server account under **Connect as**:

- Your own account: use your workspace username. If you have not set one, the form shows **You don't have a connect account yet. Set one to open this session.** and offers a dialog to set it. See [Set your username](/use/iam/users/username/).
- root: run the whole session as root. If **Direct root login** is off, the card is disabled with **Direct root disabled for this workspace**. For commands that occasionally need root, choose your own account and request privilege elevation instead.
- Another account: select a shared or service account from the selected servers. Unavailable accounts show a reason, such as **Bound to another user · ask an admin to rebind**. An account linked to another person cannot be used.

When root is selected, the form warns: **Runs as root for the whole session, bypassing per-command sudo governance. If you only need root for specific commands, connect as yourself and use the sudo scope.**.

If an account is missing or refused on a selected server, the form marks that server and disables submission. Choose another account or remove the affected server. When a Superuser requests a session for someone else, the first card uses the assignee's account instead of the requester's.

On Windows, commands run as SYSTEM; the chosen account is an audit label. See [Permissions and identity on Windows](/reference/platforms/windows/#permissions-and-identity-on-windows).

### 4. Session features

Choose at least one of the [features](/reference/work-session-features/) the task needs: web terminal, file transfer, execute commands, port forwarding, code editor, or privilege elevation. The web terminal is for people; an AI-agent session cannot include it.

The **Code editor** and **Port forwarding** features work only on servers where they are enabled. See [Tunnel and code editor](/use/servers/manage/#tunnel-and-code-editor).

### 5. Session duration

Choose a preset or a custom length. The presets are 30 minutes, 1 hour, 2 hours, 4 hours, and 8 hours, but the form shows only those within your workspace's maximum. With the default 4-hour maximum, you see 30 minutes, 1 hour, 2 hours, and 4 hours.

"Custom" lets you enter hours and minutes. Choose "Start right away" or "Start later"; the latter lets you schedule the start. Custom lengths are also capped by the workspace maximum, which the form shows beneath the duration. See [Time limits](/use/work-sessions/detail/#time-limits).

An approver can shorten the time window you request. See [Shortening the session window before approving](/use/approvals/reviewing/#shortening-the-session-window-before-approving).

## Submit

Check the result card in the right rail before submitting. It shows whether the request opens immediately, waits for approval or a scheduled start, or cannot start with the current choices. The server summary above it shows whether the chosen account is available on each selected server and, when sudo is selected, how commands at each risk level are handled. Adjust the servers, account, or features if the card says the session cannot start.

Submit the request to open its detail page.

## What happens next

- A request needing review stays **Pending** until an approver decides. Its features are unavailable while it waits.
- The requester or a Superuser can cancel a pending request. An assignee cannot cancel a request just because it was made for them.
- Once admitted, a session with a future start time stays **Approved** until activation. A session without a future start becomes **Active**. See [Use a session](/use/work-sessions/detail/).

Admission without review follows your access rules. In an Advisory workspace, sessions are admitted without review, including those requested by AI agents. See [Sessions in an advisory workspace](/use/work-sessions/#sessions-in-an-advisory-workspace).

## If your request is refused

The form or submission message explains the refusal. It can mean the workspace denies the requested access, the AI agent is not allowed, or nobody other than the requester can approve. See [Request troubleshooting](/use/work-sessions/troubleshooting/#your-request-is-refused) for exact messages and next steps.

## Sessions for AI agents

Requests made through a machine channel or a CLI running under a detected AI agent are treated as agent requests. The CLI recognizes Claude Code, Codex, Gemini CLI, GitHub Copilot, Cursor, Cline, and Goose. Other agents can identify themselves with `AI_AGENT=NAME`. A detected agent cannot select `--requester-type user`.

- Use `command` and `alpacon exec` for command execution. Agent sessions can also request `webftp`, `tunnel`, `editor`, and `sudo`; the web terminal is for people.
- In an Enforce workspace, agent requests wait for a person's approval by default, even when the requester is a Superuser. Adding servers also requires approval.
- Run only as the account covered by the approval. To use another account, request a session that covers it.
- Pass `--work-session ID` on each command. Agent sessions cannot be attached with `work-session use` or `--use`.
- Use an agent your workspace allows. If it is refused, ask a security admin to review the allowed agents.

See [Rules for AI agents](/use/approvals/#rules-for-ai-agents).

## Request from the CLI

Use [`alpacon work-session create`](/reference/cli/work-session/create/) to request access from the [Alpacon CLI](/reference/cli/):

```sh
alpacon work-session create --purpose "nginx fix" --scope command --server web-01 --expires-in 2h
```

Key flags:

- `--purpose`: why you need access; required for non-interactive requests.
- `--scope`: comma-separated features: `command`, `editor`, `sudo`, `tunnel`, `webftp`, `websh` (people only).
- `--server`: comma-separated target server names.
- `--account ACCOUNT`: the server account to run as. Pass `-u ACCOUNT` on subsequent commands. Token-held sessions cannot declare a connect-as account.
- `--expires-in` / `--expires-at`: a duration or an absolute end time.
- `--wait`: wait for approval; use `--wait-approval DURATION` to adjust the wait.
- `--use`: attach a person's session as the active session for subsequent commands. Combine with `--wait` if approval is required.
- `--sudo`: declare sudo command patterns that a non-interactive caller can run without an MFA prompt, and add the `sudo` scope.

The same access rules and lifecycle apply. Attach a person's active session with [`alpacon work-session use`](/reference/cli/work-session/use/); for an agent session, pass its ID on each command. See [Attach from the CLI](/use/work-sessions/detail/#attach-from-the-cli).

## Related docs

- [Session features](/reference/work-session-features/)
- [Use a session](/use/work-sessions/detail/)
- [Troubleshooting](/use/work-sessions/troubleshooting/)
- [Approvals](/use/approvals/)
- [`alpacon work-session` CLI reference](/reference/cli/work-session/)

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