Request a session

To work on a server, you request a session that describes what you need. After you submit, a workspace administrator reviews the request before access is granted.

Start a request

You can start a request two ways:

From a server — Click Connect on a server card or the server detail page. The server is pre-selected in the request form.
From the Sessions page — Open Sessions under Access in the sidebar, then click New session.

Either way, you land on the request form.

Fill in the request

The form walks through the following steps.

1. Assignee (superusers only)

By default, the session is requested for yourself. Superusers can assign the session to another user instead.

2. Accessible servers

Select the servers you need to work on. Only servers that are commissioned and online can be added. Use the search box to find servers, and add or remove them as needed. At least one server is required.

Note: If you started from a server’s Connect button, that server is already selected.

3. Session purpose

Describe why you need access. The purpose is required and supports Markdown, up to 2,048 characters.

If you’ve selected servers, you can click Generate to have Alpacon draft a purpose for you and suggest relevant features based on your servers. You can edit the result or click Revert to undo it.

4. Session features

Choose the features you need—web terminal, file transfer, execute commands, port forwarding, code editor, and privilege elevation. Select at least one. Web terminal, file transfer, execute commands, and privilege elevation are selected by default; adjust them to match your task.

Each feature shows a badge for who it suits best:

For user (web interface · user friendly) — launches in your browser.
For agent (CLI · agent friendly) — used from the Alpacon CLI after you attach to the session.

Note: The Code editor and Port forwarding features require the server owner to enable them on the server first. See enable editor and tunnel.

5. Session duration

Set how long the session stays usable:

Presets — 1 hour, 2 hours, or 4 hours. A preview shows when the session will end.
Custom — switch to Custom to set a start time (Now or Scheduled) and a length in hours and minutes.

Your workspace sets a maximum allowed duration (4 hours by default), shown beneath the duration field. You can’t request a session longer than that.

Submit

Click Request session. The session is created in the Pending state and you’re taken to its detail page.

What happens next

Your request waits for administrator approval. While it’s pending, the features and servers are shown as requested, and you can’t use them yet.
You can Cancel the request while it’s pending.
Once approved, the session becomes Active when its start time arrives—until then it shows as Approved—and you can launch its features once it’s active. See Use a session.

Note: Superusers don’t need separate approval—their own session requests are approved automatically and become usable right away.

Request from the CLI

You can also request a session from the Alpacon CLI with alpacon work-session create—useful for scripts and AI agents:

$ alpacon work-session create --purpose "nginx fix" --scope command,websh --server web-01 --expires-in 2h

Key flags:

--purpose — why you need access (required).
--scope — features to request: command, editor, sudo, tunnel, webftp, websh (comma-separated).
--server — target server names (comma-separated).
--expires-in / --expires-at — duration (1h, 2h, 4h) or an absolute time.
--wait — wait until the request is approved.
--use — set the new session as your active session, so later exec, websh, cp, and tunnel commands attach to it automatically. Combine with --wait when approval is required.
--sudo — pre-declare sudo command patterns so a non-interactive caller can run them without an MFA prompt (adds the sudo scope).

The same lifecycle applies: the session starts in Pending and becomes usable once approved. To attach to an approved session later, use alpacon work-session use—see Use a session. For all commands and flags, see the alpacon work-session CLI reference.