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.

Options

      --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 or agent (default "user")
      --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"

The session starts in the pending state and becomes usable once approved. Superusers’ own requests are approved automatically. 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.