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

> Learn to use reasonix serve with none, token, or password auth modes. Configure authentication seamlessly via command-line flags or reasonix.toml for your DeepSeek-Reasonix deployment.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: how-to-guide
- Published: 2026-06-24

---

**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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml)

Instead of command-line flags, you can persist these settings in the `[serve]` section of your [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) file:

```toml
[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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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:

```bash
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:

```bash

# 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:

```bash

# 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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) and run `reasonix serve --auth password`.

### Binding to Public Interfaces

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

```bash
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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/config.go) and applied via `newAuthGate` in [`internal/serve/serve.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml), specifically the `auth_mode`, `token`, and `password_hash` fields defined in [`internal/config/config.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/config.go) (lines 505-511). Command-line flags override these file-based settings when starting the server.