alpacon work-session

Create, inspect, and manage work sessions. A work session is an approval-gated unit of work that authorizes access to servers—see Work sessions for the full concept guide.

alpacon work-session [command] [flags]

Aliases: work-session, session

Recommended workflow

# 1. Check whether your authentication requires a work session
alpacon whoami
 
# 2. Create a session, wait for approval, and set it as your active session
alpacon work-session create --purpose "nginx fix" --scope command,websh \
  --server web-01 --expires-in 2h --wait --use
 
# 3. Work as usual—gated commands attach to the active session automatically
alpacon exec web-01 systemctl status nginx
alpacon websh web-01

Lifecycle

pending → approved → active → completed | expired | revoked
        ↘ rejected

A session starts as pending and must be approved before use. Superusers’ own requests are approved automatically.
An approved session becomes active when its start time arrives, or immediately with activate.
A session ends when you complete it, when it expires, or when a superuser runs revoke. A pending request can also be rejected.

Gated operations

When you sign in with browser login, the following operations require an active work session that includes the matching scope. Token authentication (API token or service token) bypasses this requirement.

Scope	Gated operations
`websh`	`alpacon websh` (interactive terminal)
`command`	`alpacon exec` (including `exec logs`), `alpacon websh SERVER "command"`
`webftp`	`alpacon cp`, `alpacon edit`
`tunnel`	`alpacon tunnel`
`sudo`	Privilege elevation; sudo command patterns declared with `--sudo`
`editor`	Code editor on the Alpacon web interface (not gated in the CLI)

Run alpacon whoami to check whether your authentication requires a work session and which session is active.

Selecting a session

Gated commands resolve which work session to attach to in this order:

The --work-session flag on the command
The ALPACON_WORK_SESSION environment variable
The workspace’s active session set with alpacon work-session use

Gate errors

When a gated command is denied, alpacon exec, alpacon websh, alpacon cp, and alpacon edit exit with code 3 and print a diagnostic with suggested next steps. With --output json, the diagnostic is printed to stderr as machine-readable JSON—fields include error_code, reason, context, and next_actions—so scripts and AI agents can recover automatically.

Error code	Meaning
`work_session_required`	No work session selected for this shell
`work_session_not_active`	Session not yet active (check its start time)
`work_session_expired`	Session has expired
`work_session_scope_not_allowed`	Operation not in the session’s scopes
`work_session_server_not_allowed`	Target server not in the session
`work_session_assignee_mismatch`	Session assigned to another principal
`work_session_not_usable`	Session is no longer usable