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

Bot mode in Reasonix enables autonomous, continuous workflow execution without human interaction through a 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, 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 — 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, 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 in your project root:

[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.

---

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)

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:

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.

---

Step 3: Start the Bot Runtime

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

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

1. Load and merge 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:

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:

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 provides visibility into the runtime behavior. The simplified structure follows this pattern:

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
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 for file location precedence and override behavior.

---

Summary

• Enabling bot mode requires the [bot] section in 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 and the documentation in 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.

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 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.

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