Getting StartedRBAC Setup

RBAC Setup

Role-Based Access Control (RBAC) adds operator authentication to ClawNex. When disabled (default), the dashboard is accessible to anyone on localhost without login.

Enabling RBAC

Set environment variables

Add to your .env or .env.local:

RBAC_ENABLED=true
NEXT_PUBLIC_RBAC_ENABLED=true

Rebuild and restart

npm run build && npm start

Create the admin account

On first visit with RBAC enabled, a setup wizard prompts you to create the initial Admin account. Enter a username and a strong password. This account has full platform control.

The 5 Roles

RoleWhat You Can Do
AdminFull platform access — manage users, configure RBAC, change all settings
Security ManagerManage shield rules, whitelist entries, alert triage, break-glass activation
OperatorMonitor traffic, acknowledge and investigate alerts, run shield tests
ViewerRead-only access to all dashboards and reports
AuditorRead-only access to audit trails, compliance reports, and security logs

28 Permissions

Permissions are assigned per role and enforced on every API route. Key permissions include:

  • config:read, config:write — configuration access
  • shield:scan, shield:manage — shield operations
  • alerts:read, alerts:manage — alert triage
  • audit:read — audit trail access
  • system:manage — system-level operations (install, restart, backup)
  • workspace:read — agent workspace file access
  • chat:use, voice:use — proxy and voice features

SETUP_SECRET

When ClawNex is exposed on a network (not just localhost), the admin setup page could be accessed by anyone who reaches port 5001. Use SETUP_SECRET to prevent unauthorized admin creation:

# In .env
SETUP_SECRET=your-random-secret-here

Then access the setup page with:

http://your-host:5001/setup?secret=your-random-secret-here

Without the correct secret, the setup page will not load.

⚠️

Use SETUP_SECRET for any deployment where port 5001 is reachable from other machines — production, staging, and shared development servers.

Session Management

  • Session timeout — configurable from 1 to 720 hours in Configuration > Session Settings
  • 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 AttemptsLockout Duration
51 minute
105 minutes
1530 minutes
20+Account auto-disabled (requires admin re-enable)

Lockout is per-account, not per-IP. A successful login resets the failure counter.

First Shield TestOverview