How to Configure Timeouts for Bash, MCP Startup, and MCP Calls in Reasonix

Set bash_timeout_seconds, mcp_startup_timeout_seconds, and mcp_call_timeout_seconds under the [tools] table in reasonix.toml to control how long foreground Bash commands, MCP server initialization, and individual MCP RPC calls may run before Reasonix aborts them.

Reasonix provides granular control over execution limits through its TOML-based configuration system. Whether you are running long-duration data processing scripts in Bash or connecting to slow-starting Model Context Protocol (MCP) servers, you can tune three distinct timeout values to prevent hangs while accommodating legitimate long-running operations. All timeout configuration happens in the user-level reasonix.toml file, with hard-coded defaults defined in the DeepSeek-Reasonix source.

Understanding the Three Timeout Categories

Reasonix distinguishes between interactive shell commands, server initialization phases, and active RPC operations. Each category has a dedicated configuration key with sensible defaults that you can override globally or per-plugin.

Bash Command Timeout

The bash_timeout_seconds setting caps the wall-clock time for any non-background Bash tool execution. According to internal/config/config.go, the default is 120 seconds (2 minutes), defined by the constant defaultBashTimeoutSeconds【/cache/repos/github.com/esengine/DeepSeek-Reasonix/main-v2/internal/config/config.go#L1584-L1587】. Setting this value to 0 disables the cap entirely, allowing commands to run indefinitely.

MCP Startup Timeout

The mcp_startup_timeout_seconds setting controls how long Reasonix waits for an MCP server to complete its background initialization sequence—specifically the initialize handshake plus the tools/list discovery phase. The default is 30 seconds, defined by defaultMCPStartupTimeoutSeconds【/cache/repos/github.com/esengine/DeepSeek-Reasonix/main-v2/internal/config/config.go#L1585-L1586】. If a server exceeds this limit, Reasonix falls back to a "retry later" prompt rather than blocking the session.

MCP Call Timeout

The mcp_call_timeout_seconds setting imposes a safety limit on individual JSON-RPC method calls to an MCP server (e.g., generate, list, or custom tool invocations). The default is 300 seconds (5 minutes), stored in defaultMCPCallTimeoutSeconds【/cache/repos/github.com/esengine/DeepSeek-Reasonix/main-v2/internal/config/config.go#L1586-L1587】. Individual plugins or specific tools can raise this value beyond the global default when necessary.

Where Timeout Defaults Are Defined

The source of truth for default values resides in internal/config/config.go. The configuration struct exposes accessor methods—BashTimeoutSeconds(), MCPStartupTimeoutSeconds(), and MCPCallTimeoutSeconds()—that apply fallback logic for omitted, zero, or negative entries【/cache/repos/github.com/esengine/DeepSeek-Reasonix/main-v2/internal/config/config.go#L1595-L1609】. These methods ensure that even if a user deletes a key from reasonix.toml, the engine reverts to the compiled-in constants.

Configuring Timeouts in reasonix.toml

To adjust timeouts, edit or create the reasonix.toml file in your project root. Under the [tools] table, assign integer values representing seconds.

Global Configuration Example

[tools]

# Allow Bash commands to run for up to 3 minutes

bash_timeout_seconds = 180

# Wait 45 seconds for MCP servers to initialize

mcp_startup_timeout_seconds = 45

# Permit individual MCP calls to block for up to 10 minutes

mcp_call_timeout_seconds = 600

Changes take effect on the next Reasonix start or after a configuration reload. You can verify the active values using reasonix config view, which renders the current settings including any overrides.

Per-Plugin Timeout Overrides

For servers with specific performance characteristics, override the global defaults directly in the plugin definition. As documented in docs/SPEC.md, individual plugins accept startup_timeout_seconds and call_timeout_seconds fields【/cache/repos/github.com/esengine/DeepSeek-Reasonix/main-v2/docs/SPEC.md#L16-L20】.

[[plugins]]
name = "video-generator"
command = "reasonix-plugin-video"

# This server starts slowly but processes quickly

startup_timeout_seconds = 90   # 1.5 minutes to initialize

call_timeout_seconds = 1200    # 20 minutes per generation task

# Optional: override specific tool timeouts

[plugins.tool_timeouts]
generate_video = 1800  # 30 minutes for this specific tool

How Timeouts Are Applied at Boot

When Reasonix initializes, it passes the configured timeout values to the MCP launch manager. In internal/boot/boot.go, the engine constructs a PluginSpecOptions struct that converts the integer seconds into time.Duration values:

pluginSpecOptions := PluginSpecOptions{
    DefaultStartupTimeout: time.Duration(cfg.MCPStartupTimeoutSeconds()) * time.Second,
    DefaultCallTimeout:    time.Duration(cfg.MCPCallTimeoutSeconds()) * time.Second,
    // …
}

This initialization occurs at lines 529-531, ensuring that every MCP plugin manager receives the user-defined limits before spawning server processes【/cache/repos/github.com/esengine/DeepSeek-Reasonix/main-v2/internal/boot/boot.go#L529-L531】.

Runtime Configuration via CLI

You can modify the Bash timeout without editing the TOML file directly by using the Reasonix CLI:

reasonix config set tools.bash_timeout_seconds 300

This command writes the new value back to reasonix.toml, and subsequent sessions automatically apply the updated cap.

Summary

• Bash timeout: Control foreground shell command duration with bash_timeout_seconds (default: 120s).
• MCP startup timeout: Set mcp_startup_timeout_seconds to define how long Reasonix waits for server initialization (default: 30s).
• MCP call timeout: Limit individual RPC calls using mcp_call_timeout_seconds (default: 300s).
• Per-plugin flexibility: Override global MCP timeouts for specific servers using startup_timeout_seconds and call_timeout_seconds in the [[plugins]] table.
• Source locations: Defaults live in internal/config/config.go, boot-time application happens in internal/boot/boot.go, and the schema is documented in docs/SPEC.md.

Frequently Asked Questions

What happens if I set a timeout to zero?

Setting bash_timeout_seconds to 0 disables the timeout entirely, allowing commands to run indefinitely. For MCP settings, zero or negative values trigger the fallback logic in the accessor methods, causing Reasonix to revert to the hard-coded defaults (30s for startup, 300s for calls).

Can I set different timeouts for different MCP tools within the same server?

Yes. While you can set a base call_timeout_seconds for the entire plugin, Reasonix supports tool-specific overrides via the tool_timeout_seconds map (or tool_timeouts table in TOML). Specify the exact MCP tool name as the key and the desired seconds as the value.

Why does Reasonix separate MCP startup timeout from call timeout?

The startup phase involves process spawning, initialize handshake, and tools/list discovery—operations that should complete quickly. Separating this from call timeouts prevents misconfigured or hanging servers from blocking your session indefinitely, while still allowing long-running operations (like video generation) once the server is active.

Where can I see the current timeout values my session is using?

Run reasonix config view to display the rendered configuration, including all active timeout values. The web documentation interface in site/src/pages/docs.astro also displays these defaults in the UI for reference【/cache/repos/github.com/esengine/DeepSeek-Reasonix/main-v2/site/src/pages/docs.astro#L310-L313】.

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