RBAC Setup
Role-Based Access Control (RBAC) adds operator authentication, roles, sessions, CSRF protection, and progressive lockout to ClawNex.
Public-facing installs always use RBAC. Local macOS installs ask whether to enable RBAC or run localhost-only without login.
Installer Behavior
| Install Mode | RBAC Behavior |
|---|---|
| Linux VPS | RBAC on |
| macOS server | RBAC on |
| macOS local | Operator chooses RBAC on or RBAC off |
| Raw development env | Controlled by RBAC_ENABLED and NEXT_PUBLIC_RBAC_ENABLED |
RBAC off is only appropriate for localhost-only local testing. Public or shared hosts should run with RBAC enabled.
First Admin Setup
Run an RBAC-enabled install
Use the installer normally for VPS/server mode, or select RBAC on during local macOS install.
Open the setup URL
The installer prints a URL like:
https://qa.example.com/setup?secret=...For local installs, the URL uses http://127.0.0.1:5001.
Create the admin account
Enter the first admin username and a strong password. This account has full platform control.
Environment Flags
For raw development or manual environments, enable RBAC with:
RBAC_ENABLED=true
NEXT_PUBLIC_RBAC_ENABLED=trueSet public-origin auth values for server deployments:
AUTH_RP_ID=qa.example.com
AUTH_EXPECTED_ORIGIN=https://qa.example.comThe 5 Roles
| Role | What You Can Do |
|---|---|
| Admin | Full platform access and user/system administration |
| Security Manager | Manage shield policy, access controls, alerts, and security operations |
| Operator | Monitor traffic, investigate alerts, run shield tests, and operate daily workflows |
| Viewer | Limited read-only operational visibility based on assigned permissions |
| Auditor | Read audit, evidence, and compliance-oriented views |
32 Permissions
Permissions are assigned per role and enforced on API routes. Key permissions include:
config:read,config:write— configuration accessshield:scan,shield:config— shield operationsalerts:read,alerts:manage— alert triageaudit:read— audit trail accesssystem:manage— system-level operationsworkspace:read— agent workspace file accesschat:use,voice:use— proxy and voice features
SETUP_SECRET
SETUP_SECRET protects the first-admin setup route. The installer generates a fresh secret and prints the correct setup URL.
Recover it later from the install directory:
grep SETUP_SECRET ~/clawnex/.env.localSession Management
- Session timeout — configurable from 1 to 720 hours
- Concurrent sessions — maximum 5 per operator; oldest session is revoked when exceeded
- Password change — revokes all of that operator’s sessions immediately
Progressive Account Lockout
Failed login attempts trigger escalating lockouts:
| Failed Attempts | Lockout Duration |
|---|---|
| 5 | 1 minute |
| 10 | 5 minutes |
| 15 | 30 minutes |
| 20+ | Account auto-disabled until an admin re-enables it |
Lockout is per account. A successful login resets the failure counter.