Allow commands with a service token
Configure the token’s allowed commands before running an automated job. Token command matching explains the exact comparison rules and refusal codes.
Write the rule exactly as you run it
Because the rule is compared against the line you submit, not the command that runs as root, a rule for a privileged command has to contain sudo.
| Command you run | Rule that allows it | Rule that does not |
|---|---|---|
sudo systemctl restart nginx | sudo systemctl restart nginx | systemctl restart nginx |
sudo -n systemctl restart nginx | sudo -n systemctl restart nginx | sudo systemctl restart nginx |
sudo docker ps | sudo docker * | docker * |
sudo X and sudo -n X are different command lines, so each needs its own rule. Register the line your pipeline actually runs: if a job adds -n for non-interactive use or -u to run as another account, that flag is part of the line being compared.
Why wildcards with sudo are dangerous
A rule of sudo * grants unrestricted root access. Wildcards match across quoting, so that rule also allows sudo bash -c "rm -rf /". sudo bash -c * and sudo sh -c * have the same effect.
List the exact privileged commands instead:
sudo systemctl restart nginx
sudo systemctl reload nginxWhat happens when a token runs sudo
Passing the allowed-command rule only gets the command delivered. Elevation is decided again on the server, at the moment sudo runs.
Service tokens on Alpacon Cloud. The workspace sudo setting must be on; otherwise sudo is refused with workspace_sudo_with_mfa_disabled. In Advisory, service-token sudo is not refused for risk at any level and the decision is recorded. Outside Advisory, once the command clears its allowed-command rule, elevation is decided automatically from the command’s assessed risk: allowed at every level below Critical, refused at Critical with SUDO_RISK_DENIED. When AI verification rejected the command, the stricter of its overall risk level and the level the rejection was made at decides, so a command rejected as Critical is refused even when its overall level reads lower. A command that could not be assessed is allowed too, so an outage in risk assessment does not stall the pipeline. Nothing waits for a reviewer: a pipeline runs unattended, so nobody would be there to answer an approval prompt. Automatic elevations, including Advisory decisions, are recorded in Privilege elevation against the application that owns the token.
A command a person approved. A service token command bound to a work session can be held for a person to approve (see below). Once a person approves the held command, that approval covers the sudo written in the approved line: elevation is allowed at any risk level, Critical included, and the grant is recorded in Privilege elevation as Admin approval, linked to that decision. Only an approval policy your workspace wrote to deny the command, or to require more than one approver, still applies.
Sudo policies do not apply to a service token. A sudo policy targets Alpacon users, and a service token is not one. Writing a policy will not change the outcome above.
Administrators can tighten this outside Advisory. A workspace token_exec rule can require refusal at a lower risk level than Critical—for elevation and for AI-rejected commands below, since both read the same policy. It cannot make a token wait for a human reviewer.
There is no sudo permission to grant. No resource offers a sudo action in the token scope catalog, so elevation is not something you enable on the application’s role or on the token’s scopes. The allowed-command entry and the command’s assessed risk decide it.
API access tokens are different. A personal API access token cannot elevate on its own. Run the command inside a work session that includes the sudo scope and is covered by a sudo policy, or move the workload to a service token.
On self-hosted deployments, sudo from a service token is refused with SUDO_COMMAND_NOT_AUTHORIZED because it cannot be tied to a person. Rerun it as a signed-in person’s authorized command, or in a work session whose sudo policy matches the command.
What happens when a token’s command fails AI verification
Every command is checked by Alpacon’s AI risk verification before it runs. Sent by a person, or inside a work session, a command the verdict rejects is normally held so a person can let it run anyway. See Verification status in Commands.
A service token command sent with no work session skips that hold—this is how CI jobs and other unattended automation run, and there’s nobody to answer it. When the AI verdict rejects such a command, your workspace’s token execution policy settles it on its own, the moment the verdict lands:
- At Critical, or at any level your policy refuses, the command is rejected with the result Command rejected by AI verification. Any commands chained to run after it are cancelled too, each with the result Cancelled: prior command rejected.
- Below that line, the command runs anyway. The rejection is recorded under Rejected by verification, but executed via a session-less service token, with the risk it was judged at. This label identifies the service-token path separately from signing monitor mode. See Verification status.
Administrators can tighten this. It’s the same policy that already decides token sudo: lower the risk level it refuses at, and both this gate and elevation get stricter together. It cannot bring back the hold for a human reviewer.
A service token command bound to a work session, and any command from an existing personal API access token, keep the hold. File operations aren’t affected—only executed commands go through this gate.
When elevation is not available
If sudo is refused because it cannot be tied to a person, rerun it as a signed-in person’s authorized command or in a work session whose sudo policy matches the command. If the command is assessed Critical or you need an alternative for automation, consider these options.
- Remove the need for sudo. Give the account the token runs as direct control of what it manages—a systemd user unit for the service, or membership in the group that owns the files. Nothing is elevated, so nothing has to be approved. This is the narrowest option and the one to try first.
- Run inside a work session. A work session with the sudo scope keeps the approval and audit trail intact. The trade-off is that a person has to request the session, so the deployment is no longer fully unattended.
- Grant the command in the host’s own sudoers file. The job keeps running unattended, but that host’s elevation is decided outside Alpacon: those commands do not appear in Privilege elevation and no policy or approval applies to them. Treat this as a last resort, and only for a host you have deliberately excluded from Alpacon’s privileged-access controls.
Rule matching reference
The token command matching reference covers wildcards, account and group matching, sudo-policy comparisons, and denial codes.