# How to Configure Bot Mode in Reasonix for Fully Automated Workflow Execution

> Master Reasonix bot mode for automated workflow execution. Learn to configure the TOML file, control API, and task queue for seamless, uninterrupted operation.

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

---

**Bot mode in Reasonix enables autonomous, continuous workflow execution without human interaction through a [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) configuration, a protected HTTP control API, and a persistent task queue with automatic checkpointing.**

Reasonix can operate as a fully automated "bot" that continuously executes workflows using the same reasoning engine that powers its CLI, TUI, desktop application, and VS Code extension. When configured for bot mode, the engine reads runtime parameters from [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml), authenticates via a **control token**, and exposes an HTTP API for external services to submit tasks. This guide walks through the complete configuration process based on the official source code in `esengine/DeepSeek-Reasonix`.

---

## Understanding the Bot Mode Architecture

The bot runtime consists of four integrated components that work together to provide deterministic, resumable automation:

- **[`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml)** — Contains the `[bot]` section with provider selection, concurrency limits, and checkpoint intervals
- **Control Token (`REASONIX_BOT_CONTROL_TOKEN`)** — A Bearer token that protects the HTTP control API endpoints
- **Global Credentials Store** — Holds sensitive values including the control token and integration secrets like `QQ_BOT_APP_SECRET`
- **Bootstrap Runtime** — Initializes the provider, starts the internal HTTP server, and enters the main task-processing loop

According to the source in [`src/engine/bot.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/src/engine/bot.go), the bot performs environment-aware configuration merging before starting the control server and task executor.

---

## Step 1: Create the Bot Configuration in reasonix.toml

The central configuration file declares all bot-specific settings in a dedicated `[bot]` section. This section controls provider selection, model assignment, concurrency limits, and checkpoint persistence.

Create or edit [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) in your project root:

```toml
[bot]
enabled = true
control_token = "change-me"        # Overridden by REASONIX_BOT_CONTROL_TOKEN env var or credentials store

provider = "deepseek"              # Must match an entry in providers.toml

model = "deepseek-chat"            # Model used for both planning and execution phases

max_concurrency = 4                # Maximum parallel workflow executions

checkpoint_interval = "5m"         # Automated checkpoint frequency (uses Go duration syntax)

```

The `control_token` value serves as a fallback; the runtime prioritizes the `REASONIX_BOT_CONTROL_TOKEN` environment variable and the global credentials store. For production deployments, omit the plaintext token and rely on the credentials system documented in [`docs/ACP.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/ACP.md).

---

## Step 2: Configure the Control Token and Credentials

Bot mode requires a secret **control token** to authenticate HTTP API requests. Reasonix supports two credential locations, checked in priority order:

1. **Environment variable**: `REASONIX_BOT_CONTROL_TOKEN`
2. **Global credentials file**: Managed via the Reasonix credential store (see [`docs/ACP.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/ACP.md))

For integrations such as the QQ bot platform, additional credentials are required:

| Credential | Purpose | Source |
|------------|---------|--------|
| `REASONIX_BOT_CONTROL_TOKEN` | Authenticates control API requests | Environment or credentials store |
| `QQ_BOT_APP_SECRET` | Authenticates with QQ bot platform | Global credentials store |
| `QQ_BOT_APP_ID` (optional) | Identifies the QQ bot application | Global credentials store |

Export the control token before starting the bot:

```bash
export REASONIX_BOT_CONTROL_TOKEN="sk-reasonix-$(openssl rand -hex 32)"

```

Or configure permanently using the Reasonix credential manager as described in [`docs/ACP.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/ACP.md).

---

## Step 3: Start the Bot Runtime

Launch the bot using either the dedicated subcommand or the flag-based invocation:

```bash

# Method 1: Dedicated bot command

reasonix bot start

# Method 2: Flag-based invocation

reasonix run --bot

```

Both commands execute the same bootstrap sequence implemented in [`src/engine/bot.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/src/engine/bot.go):

1. Load and merge [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) with environment overrides
2. Initialize the specified provider (e.g., DeepSeek-Chat) and planner/executor models
3. Start the HTTP control server on `localhost:<port>` with Bearer token authentication
4. Enter the main loop: fetch tasks from queue, respect `max_concurrency`, persist checkpoints

The control server accepts task submissions, status queries, and lifecycle commands via REST endpoints.

---

## Step 4: Submit Tasks via the Control API

External services interact with the bot through authenticated HTTP requests. The control token must be included as a Bearer token in the `Authorization` header.

Submit a new workflow task:

```bash
curl -X POST "http://localhost:8080/v1/tasks" \
     -H "Authorization: Bearer $REASONIX_BOT_CONTROL_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "contract": "run \"implement the TODOs in main.go\"",
           "priority": "high",
           "timeout": "10m"
         }'

```

Query task status:

```bash
curl -H "Authorization: Bearer $REASONIX_BOT_CONTROL_TOKEN" \
     "http://localhost:8080/v1/tasks/{task_id}"

```

The API design supports programmatic integration with CI/CD systems, chatbots, and scheduled job runners.

---

## Internal Implementation: The Bot Runtime Loop

The core bot implementation in [`src/engine/bot.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/src/engine/bot.go) provides visibility into the runtime behavior. The simplified structure follows this pattern:

```go
func startBot(ctx context.Context, cfg BotConfig) error {
    // Initialize provider from configuration
    prov := providers.New(cfg.Provider, cfg.Model)
    
    // Configure authenticated HTTP control server
    srv := http.NewServeMux()
    srv.Handle("/v1/tasks", authMiddleware(cfg.ControlToken, taskHandler(prov)))
    go http.ListenAndServe(cfg.ListenAddr, srv)
    
    // Main execution loop with checkpointing and concurrency control
    for {
        select {
        case <-ctx.Done():
            return ctx.Err()
        default:
            task := taskQueue.Pop()
            semaphore.Acquire(ctx, 1)  // Respect cfg.MaxConcurrency
            go func() {
                defer semaphore.Release(1)
                runTask(task, prov)
                checkpoint.Persist(task.ID)  // Automated checkpointing
            }()
        }
    }
}

```

Key implementation details from the source:

- **Checkpointing** occurs at configurable intervals and after task completion, enabling crash recovery
- **Concurrency control** uses a semaphore pattern to enforce `max_concurrency` limits
- **Graceful shutdown** responds to context cancellation for clean termination

---

## Configuration Reference: Essential Bot Settings

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `enabled` | boolean | `false` | Activates bot mode on startup |
| `provider` | string | required | Provider identifier from [`providers.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/providers.toml) |
| `model` | string | required | Model name for planning and execution |
| `max_concurrency` | integer | `1` | Parallel workflow limit |
| `checkpoint_interval` | duration | `"5m"` | Automated checkpoint frequency |
| `listen_addr` | string | `"localhost:8080"` | HTTP control server binding |
| `control_token` | string | `""` | Fallback token (use environment/credentials instead) |

Refer to [`docs/CONFIG_PATHS.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/CONFIG_PATHS.md) for file location precedence and override behavior.

---

## Summary

- **Enabling bot mode** requires the `[bot]` section in [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) with `enabled = true` and valid provider/model configuration
- **Securing the control API** depends on the `REASONIX_BOT_CONTROL_TOKEN` environment variable or credentials store entry
- **Starting the runtime** uses `reasonix bot start` or `reasonix run --bot` to launch the HTTP server and task processor
- **Submitting work** happens via authenticated POST requests to `/v1/tasks` with Bearer token authentication
- **Maintaining state** relies on automatic checkpointing at configurable intervals for crash recovery and resumability

All implementation details derive from the source code in `esengine/DeepSeek-Reasonix`, specifically [`src/engine/bot.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/src/engine/bot.go) and the documentation in [`docs/BOT_GUIDE.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/BOT_GUIDE.md).

---

## Frequently Asked Questions

### What happens if the bot crashes during workflow execution?

Reasonix persists **checkpoints** automatically at the configured `checkpoint_interval` and after each task completes. When restarted, the bot loads the most recent checkpoint from disk and resumes from the last successful state. This behavior is implemented in the checkpoint persistence layer of [`src/engine/bot.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/src/engine/bot.go).

### Can I run multiple bot instances with the same configuration?

Running multiple instances requires **unique control tokens** and **non-conflicting listen addresses** for each instance. The task queue implementation does not provide automatic distributed coordination; for horizontal scaling, deploy separate Reasonix instances with independent checkpoint directories or implement external task distribution.

### How do I rotate the control token without stopping the bot?

The bot reads the control token **once at startup** from the environment or credentials store. To rotate credentials, update the `REASONIX_BOT_CONTROL_TOKEN` environment variable or credentials file, then restart the bot process. There is no hot-reload mechanism for security-sensitive configuration values in the current implementation.

### Does bot mode support custom authentication beyond the control token?

The HTTP control server in [`src/engine/bot.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/src/engine/bot.go) implements **Bearer token authentication only**. For additional security layers, deploy a reverse proxy (nginx, Caddy, or cloud API gateway) to handle TLS termination, IP allowlisting, or OAuth2 integration upstream of the Reasonix control port.