Auth Mode (Multi-User)

Auth mode adds a full authentication and authorization layer to Superagent, turning it into a multi-user deployment suitable for teams. Users sign in with email/password or an OIDC provider, and access to agents is controlled through a role-based permission system.

When to choose this option

• Multiple people need to access the same Superagent instance.
• You need per-user accounts with audit trails.
• You want to control who can view, use, or manage each agent.
• You are deploying Superagent as shared team infrastructure.

For single-user deployments without authentication, see Single-User Docker.

Published image

Auth mode requires a dedicated image that has the authentication frontend compiled in. The frontend is compiled with AUTH_MODE=true at build time, which enables the login UI and session management in the client.

ghcr.io/skillfulagents/superagent:main-auth

The -auth suffix is the key difference from the single-user image:

Quick start

Create a .env file:

ANTHROPIC_API_KEY=sk-ant-...
BETTER_AUTH_SECRET=your-random-secret-at-least-32-characters

Create a docker-compose.yml:

services:
  superagent:
    image: ghcr.io/skillfulagents/superagent:main-auth
    restart: unless-stopped
    network_mode: host
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ${HOME}/.superagent:${HOME}/.superagent
    environment:
      - SUPERAGENT_DATA_DIR=${HOME}/.superagent
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - PORT=47891
      - AUTH_MODE=true
      - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}
      - TRUSTED_ORIGINS=${TRUSTED_ORIGINS:-}

Start the container:

docker compose up -d

Open your browser to http://localhost:47891. You will see a sign-up page. The first account you create automatically becomes the admin.

Environment variables

In addition to the standard environment variables, auth mode uses:

Authentication methods

Email and password

Email/password authentication is enabled by default. Users create an account with an email address and a password that meets the configured policy (minimum 12 characters with uppercase, lowercase, number, and symbol by default).

OIDC / social login

Superagent supports any OpenID Connect (OIDC) identity provider -- Google Workspace, Microsoft Entra ID, Okta, Auth0, Keycloak, and others. OIDC providers are configured through the AUTH_PROVIDERS_JSON environment variable.

AUTH_PROVIDERS_JSON='[
  {
    "id": "google",
    "type": "oidc",
    "displayName": "Google",
    "discoveryUrl": "https://accounts.google.com/.well-known/openid-configuration",
    "clientId": "your-client-id.apps.googleusercontent.com",
    "clientSecret": "your-client-secret",
    "scopes": ["openid", "email", "profile"]
  }
]'

Each provider entry supports:

All OIDC flows use PKCE (Proof Key for Code Exchange) for security.

You can configure multiple providers. Each appears as a separate button on the login screen.

First user becomes admin

The very first user to sign up on a fresh Superagent instance is automatically promoted to the admin role. This happens atomically -- the promotion only applies if the user table has exactly one row after account creation.

This bootstrapping mechanism means you do not need any special setup to create the initial admin. Just start the container, visit the sign-up page, and create your account.

Role-based access control

Auth mode has two layers of roles: app-level roles that control global permissions, and agent-level roles that control access to individual agents.

App-level roles

Agent-level roles

Each agent has its own access control list (ACL). Users are granted one of three roles per agent:

The role hierarchy is strict: owner > user > viewer. A middleware check requiring "user" access will also pass for "owner", and a check requiring "viewer" access will pass for both "user" and "owner".

Admins bypass all agent-level checks. An admin can access any agent without needing an explicit ACL entry.

When a user creates an agent, they are automatically assigned the owner role on that agent.

Signup and access control

Admins can configure how new users join the instance through the admin settings panel:

Admin approval

When enabled, new users are automatically banned with the reason "Pending admin approval" after signing up. They cannot log in until an admin unbans their account. This works in combination with open or domain-restricted signup modes to give admins a review step before granting access.

Disabling auth methods

Admins can independently enable or disable:

• Email/password authentication -- Disable to force OIDC-only login.
• Social/OIDC authentication -- Disable to force email/password-only login.

Password policy

The default password policy requires:

• Minimum 12 characters (configurable).
• Maximum 128 characters (configurable).
• At least one uppercase letter, one lowercase letter, one number, and one symbol (complexity requirement, can be disabled).

These settings are enforced on both sign-up and password change.

Session management

Account lockout

After 10 consecutive failed login attempts (configurable), the account is locked for 30 minutes (configurable). The lockout is per-email and resets on successful login.

User management

Admins can manage users through the admin panel in the UI:

• View all users -- See email, role, status, and creation date.
• Ban / unban users -- Prevent a user from logging in.
• Promote / demote -- Change a user's app-level role between admin and user.
• Set password -- Force a password reset. The user will be required to change their password on next login.
• Approve pending users -- When admin approval is required, approve or reject new signups.

Data directory considerations

Auth mode can only be enabled on a fresh data directory or one that already has auth tables. You cannot enable auth mode on an existing single-user data directory that contains agents -- the startup validation will reject it to prevent orphaned agent data that no user owns.

If you are migrating from single-user to auth mode, start with a clean data directory.

Docker Compose example

A complete production-ready docker-compose.yml with auth mode, OIDC, and trusted origins:

services:
  superagent:
    image: ghcr.io/skillfulagents/superagent:main-auth
    restart: unless-stopped
    network_mode: host
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /data/superagent:/data/superagent
    environment:
      - SUPERAGENT_DATA_DIR=/data/superagent
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - PORT=47891
      - AUTH_MODE=true
      - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}
      - TRUSTED_ORIGINS=https://superagent.example.com
      - AUTH_PROVIDERS_JSON=${AUTH_PROVIDERS_JSON:-}

Limitations

• Auth mode is web/Docker only. The Electron desktop app does not support auth mode. If AUTH_MODE=true is set in an Electron environment, it is ignored with a warning.
• OIDC providers are configured at deployment time. Provider credentials are passed through environment variables, not through the admin UI. This keeps secrets out of the application database.

Next steps

• Single-User Docker -- Simpler deployment without authentication.
• Electron Desktop App -- Run Superagent as a native desktop application.