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          Session purpose
      --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 (does not set as active; combine with --use to attach automatically)

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.

Last updated: