Permissions
Permissions define what an agent is allowed to do, and what requires human approval. They are fields on the agent document and are enforced both by Nexus Core (at dispatch) and inside the runner (at action time).
Permission model
agent.can_create_branch
agent.can_commit
agent.can_open_pr
agent.can_merge
agent.can_delete_files
agent.can_use_kubectl
agent.can_apply_k8s
agent.can_write_memory
agent.can_create_plane_task
Approval gates
Some actions never run unattended. The agent declares them:
permissions:
can_create_branch: true
can_commit: true
can_open_pr: true
can_merge: false
can_delete_files: false
requires_human_approval_for:
- production_deploy
- dependency_upgrade
- database_migration
When an agent attempts a gated action, Nexus Core raises an approval request. The run pauses (or proceeds with the action skipped, depending on policy) until an operator approves in the UI. See the approvals queue.
Enforcement layers
| Layer | Enforces |
|---|---|
| Nexus Core | Whether the agent may be dispatched with a given tool/permission set; raises approvals. |
| Runner | Refuses to perform actions the run config didn't grant. |
| Kubernetes RBAC | The run's service account can only touch what its role allows (e.g. read-only kubectl). |
nexus-auth crate | Agent tokens, API keys, tool permissions, project permissions. |
Defense in depth: a permission must be granted at every layer for an action to succeed.