How to Use `reasonix serve` with Different `auth_mode` Options (none, token, password)

The reasonix serve command supports three authentication modes—none (default for local development), token (pre-shared URL parameter), and password (bcrypt-secured login page)—configured via command-line flags or the [serve] section in reasonix.toml.

The reasonix serve command launches a local HTTP server that hosts the Reasonix web UI from the DeepSeek-Reasonix repository. By default, it runs without authentication on loopback only, but you can secure deployments using the auth_mode setting to control access when sharing across networks or running in production environments.

Understanding the Three auth_mode Options

none: Local Development Only

When auth_mode is set to "none", the server skips all authentication checks and listens exclusively on 127.0.0.1:8787. This mode is safe for local-only experimentation since the interface is not exposed to external networks. According to the source code in internal/serve/serve.go, the authGate is set to nil in this configuration, allowing requests to pass through without validation.

token: Shareable URLs with Pre-Shared Keys

The token mode generates a random token at startup (or accepts a custom one via the --token flag) that must be included as a query parameter (?token=...) in every request. This is ideal for temporarily sharing access with colleagues or when binding to public interfaces. The server constructs the authGate to validate the token, returning a 401 response for requests missing or providing invalid credentials.

password: Login Page Protection

For production-grade security, password mode presents a login page and validates submitted credentials against a bcrypt hash stored in the configuration. Upon successful authentication, the server issues a session cookie for subsequent requests. You must generate the required hash using the --hash-password flag before starting the server, or manually add the hash to your configuration file.

Configuration Reference

The ServeConfig Struct

Authentication settings are defined in the ServeConfig struct located in internal/config/config.go (lines 505-511). This struct contains the AuthMode, Token, and PasswordHash fields that the server uses to initialize access controls.

Configuring via reasonix.toml

Instead of command-line flags, you can persist these settings in the [serve] section of your reasonix.toml file:

[serve]
auth_mode = "token"        # none | token | password

token = "my-secret-token"  # required when auth_mode = "token"

password_hash = ""         # bcrypt hash required when auth_mode = "password"

The example configuration in reasonix.example.toml (lines 183-187) demonstrates these settings with inline documentation, as referenced in site/src/pages/docs.astro (lines 150-170).

Practical Usage Examples

Quick Local Testing (No Authentication)

Run the server with default settings for local development:

reasonix serve

This binds to 127.0.0.1:8787 with auth_mode implicitly set to "none".

Token-Based Authentication

Generate a random token automatically or specify your own:

# Auto-generate token

reasonix serve --auth token

# Use a custom token

reasonix serve --auth token --token "my-secret-token"

The server prints a shareable URL like http://127.0.0.1:8787?token=my-secret-token. Requests without this parameter receive a 401 error.

Password Authentication Setup

First, generate the bcrypt hash, then start the server:

# Generate hash (run once)

reasonix serve --hash-password --password "strong-password"

# Start with password auth

reasonix serve --auth password --password "strong-password"

The hash is automatically stored in your configuration. Alternatively, manually add the generated hash to the password_hash field in reasonix.toml and run reasonix serve --auth password.

Binding to Public Interfaces

Combine authentication with a custom bind address for LAN or remote access:

reasonix serve --addr 0.0.0.0:8787 --auth token

This exposes the UI on all network interfaces while requiring the token query parameter for access.

How Authentication Works Internally

The authentication pipeline is constructed in internal/serve/serve.go by the newAuthGate(serveCfg) function (lines 48-55). This function wires the chosen auth_mode into the HTTP request pipeline:

• For none: Returns nil, bypassing all checks
• For token: Validates the token query parameter against the configured value
• For password: Implements bcrypt comparison and session cookie management

All three modes share the same underlying HTTP handler; only the authGate implementation differs, as documented in the user-facing documentation at site/src/pages/docs.astro.

Summary

• reasonix serve supports three authentication modes controlled by the auth_mode setting in reasonix.toml or command-line flags.
• none (default) requires no credentials and restricts access to localhost (127.0.0.1:8787) only.
• token protects access via a pre-shared URL parameter suitable for temporary sharing across networks.
• password provides full login page security using bcrypt hashing for production deployments.
• Configuration is handled through the ServeConfig struct in internal/config/config.go and applied via newAuthGate in internal/serve/serve.go.

Frequently Asked Questions

What is the default authentication mode for reasonix serve?

The default mode is none, which binds only to 127.0.0.1:8787 and requires no authentication credentials. This is safe for local development but should not be used when exposing the server to external networks without additional firewall rules.

How do I generate a bcrypt hash for password authentication?

Run reasonix serve --hash-password --password "your-password". This command generates the hash and stores it in your configuration file. You can then start the server with --auth password without specifying the plaintext password again, or manually paste the hash into the password_hash field in reasonix.toml.

Can I use token authentication with a custom bind address?

Yes. Combine --addr 0.0.0.0:8787 (or your preferred interface) with --auth token. This exposes the server on all network interfaces while requiring the token query parameter for access, as documented in site/src/pages/docs.astro.

Where does the server store the authentication configuration?

Settings are read from the [serve] section of reasonix.toml, specifically the auth_mode, token, and password_hash fields defined in internal/config/config.go (lines 505-511). Command-line flags override these file-based settings when starting the server.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}