Browse docs

First Run Setup

On your first visit to OpenCode Manager, you'll complete a guided setup process.

Interactive Setup

When no admin account exists, you'll be automatically redirected to the setup page.

Step 1: Create Admin Account

Fill in your account details:

  • Name - Your display name
  • Email - Used for login
  • Password - At least 8 characters (required)

Click Create Admin Account to continue.

Step 2: Configure Provider (Optional)

After account creation, configure an AI provider:

  1. Navigate to Settings > Providers
  2. Select a provider
  3. Enter API key or connect via OAuth
  4. Save configuration

You can skip this and configure providers later.

Pre-Configured Admin

For automated or headless deployments, skip interactive setup by setting environment variables:

# In docker-compose.yml or .env
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=your-secure-password

When these are set:

  • Admin user is created automatically on first startup
  • Setup wizard is skipped
  • Registration is disabled, so no new accounts can be created
  • ADMIN_PASSWORD sets the password only when the admin is first created, or when ADMIN_PASSWORD_RESET=true; changing it later has no effect otherwise

Adding Passkeys

After initial setup, you can add passkey authentication for passwordless login:

  1. Go to Settings > Account
  2. Optionally enter a passkey name (e.g., "MacBook Touch ID")
  3. Click Add Passkey
  4. Follow your browser/device prompts

Passkeys provide:

  • Passwordless login
  • Phishing-resistant authentication
  • Biometric support (Touch ID, Face ID, Windows Hello)

Password Reset

If you forget your password:

  1. Set environment variables:
ADMIN_EMAIL=your@email.com
ADMIN_PASSWORD=new-password
ADMIN_PASSWORD_RESET=true
  1. Recreate the container so it picks up the new environment variables:
docker compose up -d --force-recreate app

  1. Log in with new password

  2. Important: Remove ADMIN_PASSWORD_RESET=true and recreate the container again:

docker compose up -d --force-recreate app

Security Recommendations

Production Deployments

  • Keep AUTH_SECRET stable. Docker generates a strong one and keeps it in the data volume; outside Docker, set it yourself
  • Use HTTPS with valid SSL certificate
  • Use strong, unique passwords
  • Enable passkey authentication
  • Regularly rotate API keys

Generate AUTH_SECRET

Only needed outside Docker, or to manage the secret yourself:

openssl rand -base64 32

Add to your environment:

AUTH_SECRET=your-generated-secret-here

Next Steps