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

> Configure bash, MCP startup, and MCP call timeouts in Reasonix by editing reasonix.toml. Control command execution duration and prevent system hangs.

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

---

**Set `bash_timeout_seconds`, `mcp_startup_timeout_seconds`, and `mcp_call_timeout_seconds` under the `[tools]` table in [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml), the engine reverts to the compiled-in constants.

## Configuring Timeouts in reasonix.toml

To adjust timeouts, edit or create the [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/reasonix.toml) file in your project root. Under the `[tools]` table, assign integer values representing seconds.

### Global Configuration Example

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

```toml
[[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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/boot/boot.go), the engine constructs a `PluginSpecOptions` struct that converts the integer seconds into `time.Duration` values:

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

```bash
reasonix config set tools.bash_timeout_seconds 300

```

This command writes the new value back to [`reasonix.toml`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/config/config.go), boot-time application happens in [`internal/boot/boot.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/boot/boot.go), and the schema is documented in [`docs/SPEC.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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】.