alpacon work-session create

Create a new work session.

alpacon work-session create [flags]

Pass --use to set the new session as the workspace’s active session, so subsequent exec, websh, cp, and tunnel commands attach to it without --work-session. When approval is required, combine --use with --wait—the session is attached once it reaches the active state.

If the work needs sudo, pre-declare the command patterns with --sudo. This attaches MFA-bypass sudo policies to the session so a non-interactive caller (e.g. an AI agent running exec) can run those exact sudo commands without an interactive MFA prompt. Each --sudo value is a comma-separated pattern list forming one policy—literal commas inside a pattern are not supported, so pass the flag again for each policy that needs them. The sudo scope is added automatically, and the policies are submitted for approval together with the session. If a sudo command is later denied, add it to the session with alpacon work-session update.

When an AI agent drives the CLI, the session is an agent session. The CLI detects Claude Code, Codex, Gemini CLI, GitHub Copilot, Cursor, Cline, and Goose from the environment variables they set in the shells they run, and names the AI agent on every request. For an AI agent the CLI doesn’t detect (for example Aider), set AI_AGENT=<name> in its environment. An agent session follows the workspace’s approval rules. In Advisory mode it starts without waiting for approval. Websh and Kubernetes aren’t available to it.

--requester-type user is refused while an AI agent is detected. If you are running the command yourself, use a terminal outside the AI agent’s environment. Commands an AI agent runs must go through an agent session. --requester-type agent opens an agent session without naming an AI agent.

Pass --account to name the account the work runs as on the servers (for example root), so the approver sees it with the request. On Windows servers the account is an audit label and commands run as SYSTEM; see permissions on Windows.

Options#

      --account string          Account the work runs as on the servers (e.g. root); the approver sees it with the request. On Windows servers it is an audit label (commands run as SYSTEM)
      --expires-at string       Absolute expiry time (RFC3339)
      --expires-in string       Session duration (e.g. 1h, 2h, 4h)
  -h, --help                    help for create
      --purpose string          What you're doing and why; be specific. Markdown supported. (required in non-interactive mode)
      --requester-type string   Requester type: 'user' (default) or 'agent'. A detected AI agent always gets 'agent'; set AI_AGENT=<name> for an agent the CLI does not detect
      --scope strings           Scopes to request. Valid: command, editor, sudo, tunnel, webftp, websh (repeatable; comma-separated values also accepted)
      --server strings          Target server names (repeatable; comma-separated values also accepted)
      --sudo stringArray        Pre-declare sudo command patterns to run without interactive MFA (repeatable; each value is a comma-separated pattern list forming one policy, wildcards allowed)
      --sudo-reason string      Justification applied to the sudo policies created via --sudo
      --use                     Set the created session as the workspace's active session (requires status to reach 'active'; combine with --wait when approval is needed)
      --wait                    Poll until the session is approved, then exit (default timeout 5m; does not set as active; combine with --use to attach automatically)
      --wait-approval string    Like --wait with a custom wait timeout (e.g. 30m; default 5m). Implies --wait

Examples#

Request a session for command execution and terminal access:

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

Request a session for multiple servers with an absolute expiry, and wait for approval:

alpacon work-session create --purpose "deploy" --scope command --server web-01,db-01 --expires-at 2027-01-15T10:00:00Z --wait

Create a session and set it as the active session in one step:

alpacon work-session create --purpose "deploy" --scope command --server web-01 --expires-in 2h --wait --use

Pre-declare sudo command patterns for non-interactive sudo:

alpacon work-session create --purpose "nginx hotfix" --scope sudo --server web-01 --expires-in 2h \
  --sudo "systemctl restart nginx,systemctl reload nginx" --sudo "tail -f /var/log/nginx/*.log"

Name the account the work runs as:

alpacon work-session create --purpose "restart nginx" --scope command,sudo --server web-01 --expires-in 1h --account root

The session starts in the pending state and becomes usable once approved. Superusers’ own requests are approved automatically, except sessions an AI agent requests, which by default wait for a person’s approval unless the workspace is in Advisory mode. See the lifecycle and Request a session for details.

Sudo command patterns#

--sudo patterns decide which elevated commands the session can run without an interactive MFA prompt. Alpacon matches a command against the patterns using these rules:

• Patterns match the command being elevated, which does not include the sudo prefix. By the time Alpacon evaluates it, the sudo you typed is no longer part of the command—so sudo systemctl restart nginx is matched as systemctl restart nginx. Write patterns without sudo: use apt-get update, not sudo apt-get update. A pattern that contains sudo never matches.
• Matching is full-string. The entire command must match the entire pattern. * is the only wildcard and matches any text; there is no other glob or regex syntax.
• Compound commands are split. Input joined by shell operators (&&, ||, ;, pipes, redirects) is split into sub-commands, and every sub-command must match at least one pattern.
• Whitespace is normalized; everything else is exact. Runs of spaces collapse to a single space before matching. Otherwise the match is literal—flags, argument order, and absolute paths all count. apt-get install -y nginx does not match apt-get install nginx, and /usr/bin/apt-get update does not match apt-get update.