stdio Bus

Transport-level routing for MCP/ACP protocols

Configuration

Complete configuration reference for stdio Bus workers with examples and best practices.

Getting Started

Integration

Reference

Overview

Installation

Configuration

API Reference

Integration

Troubleshooting

Registry Launcher

Echo Worker

ACP Worker

MCP Proxy

MCP Echo Server

Overview

stdio Bus kernel is configured via JSON files that specify worker pools, resource limits, and operational parameters. This guide covers all configuration options and provides examples for common deployment scenarios.

Configuration File Structure

A stdio Bus configuration file consists of two main sections:

{
  "pools": [
    {
      "id": "worker-id",
      "command": "/path/to/executable",
      "args": ["arg1", "arg2"],
      "instances": 1
    }
  ],
  "limits": {
    "max_input_buffer": 1048576,
    "max_output_queue": 4194304,
    "max_restarts": 5,
    "restart_window_sec": 60,
    "drain_timeout_sec": 30,
    "backpressure_timeout_sec": 60
  }
}
Code block in JSON, 18 lines

Pool Configuration

Worker pools define which workers to run and how many instances of each.

Pool Fields

FieldTypeRequiredDescription
idstringYesUnique identifier for this worker pool
commandstringYesPath to the executable (absolute or in PATH)
argsstring[]NoCommand-line arguments passed to the worker
instancesnumberYesNumber of worker instances to spawn (≥ 1)
envobjectNoEnvironment variables for the worker process

Pool Examples

Single worker instance:

{
  "pools": [
    {
      "id": "acp-registry",
      "command": "npx",
      "args": [
        "@stdiobus/workers-registry",
        "acp-worker"
      ],
      "instances": 1
    }
  ]
}
Code block in JSON, 13 lines

Multiple worker instances:

{
  "pools": [
    {
      "id": "acp-registry",
      "command": "npx",
      "args": [
        "@stdiobus/workers-registry",
        "acp-worker"
      ],
      "instances": 4
    }
  ]
}
Code block in JSON, 13 lines

With environment variables:

{
  "pools": [
    {
      "id": "acp-registry",
      "command": "npx",
      "args": [
        "@stdiobus/workers-registry",
        "acp-worker"
      ],
      "instances": 2,
      "env": {
        "LOG_LEVEL": "debug",
        "NODE_ENV": "production"
      }
    }
  ]
}
Code block in JSON, 17 lines

Limits Configuration

Resource limits control memory usage, restart behavior, and connection handling.

Limit Fields

FieldTypeDefaultDescription
max_input_buffernumber1048576 (1 MB)Maximum input buffer size per connection (bytes)
max_output_queuenumber4194304 (4 MB)Maximum output queue size per connection (bytes)
max_restartsnumber5Maximum worker restarts within restart window
restart_window_secnumber60Time window for counting restarts (seconds)
drain_timeout_secnumber30Timeout for graceful shutdown (seconds)
backpressure_timeout_secnumber60Timeout before closing connection when queue is full (seconds)

Limit Examples

Default limits:

{
  "limits": {
    "max_input_buffer": 1048576,
    "max_output_queue": 4194304,
    "max_restarts": 5,
    "restart_window_sec": 60,
    "drain_timeout_sec": 30,
    "backpressure_timeout_sec": 60
  }
}
Code block in JSON, 10 lines

High-throughput limits:

{
  "limits": {
    "max_input_buffer": 4194304,
    "max_output_queue": 16777216,
    "max_restarts": 10,
    "restart_window_sec": 120,
    "drain_timeout_sec": 60,
    "backpressure_timeout_sec": 120
  }
}
Code block in JSON, 10 lines

Conservative limits:

{
  "limits": {
    "max_input_buffer": 524288,
    "max_output_queue": 2097152,
    "max_restarts": 3,
    "restart_window_sec": 30,
    "drain_timeout_sec": 15,
    "backpressure_timeout_sec": 30
  }
}
Code block in JSON, 10 lines

Single-Worker Examples

Echo Worker

Minimal configuration for testing:

{
  "pools": [
    {
      "id": "echo-worker",
      "command": "npx",
      "args": [
        "@stdiobus/workers-registry",
        "echo-worker"
      ],
      "instances": 1
    }
  ]
}
Code block in JSON, 13 lines

ACP Worker

Basic ACP protocol implementation:

{
  "pools": [
    {
      "id": "acp-registry",
      "command": "npx",
      "args": [
        "@stdiobus/workers-registry",
        "acp-worker"
      ],
      "instances": 1
    }
  ]
}
Code block in JSON, 13 lines

Registry Launcher

With API keys configuration:

{
  "pools": [
    {
      "id": "registry-launcher",
      "command": "npx",
      "args": [
        "@stdiobus/workers-registry",
        "registry-launcher",
        "/path/to/api-keys.json"
      ],
      "instances": 1
    }
  ]
}
Code block in JSON, 14 lines

MCP-to-ACP Proxy

For IDE integration:

{
  "pools": [
    {
      "id": "mcp-proxy",
      "command": "npx",
      "args": [
        "@stdiobus/workers-registry",
        "mcp-to-acp-proxy"
      ],
      "instances": 1,
      "env": {
        "ACP_HOST": "localhost",
        "ACP_PORT": "9000",
        "AGENT_ID": "claude-acp"
      }
    }
  ]
}
Code block in JSON, 18 lines

Multi-Worker Examples

Multiple Worker Types

Run different worker types simultaneously:

{
  "pools": [
    {
      "id": "acp-registry",
      "command": "npx",
      "args": [
        "@stdiobus/workers-registry",
        "acp-worker"
      ],
      "instances": 2
    },
    {
      "id": "echo-worker",
      "command": "npx",
      "args": [
        "@stdiobus/workers-registry",
        "echo-worker"
      ],
      "instances": 1
    },
    {
      "id": "registry-launcher",
      "command": "npx",
      "args": [
        "@stdiobus/workers-registry",
        "registry-launcher",
        "/path/to/api-keys.json"
      ],
      "instances": 1
    }
  ]
}
Code block in JSON, 32 lines

Load-Balanced Workers

Multiple instances of the same worker for load balancing:

{
  "pools": [
    {
      "id": "acp-registry",
      "command": "npx",
      "args": [
        "@stdiobus/workers-registry",
        "acp-worker"
      ],
      "instances": 8
    }
  ],
  "limits": {
    "max_input_buffer": 2097152,
    "max_output_queue": 8388608
  }
}
Code block in JSON, 17 lines

Development Environment

Multiple workers with debug logging:

{
  "pools": [
    {
      "id": "acp-registry",
      "command": "npx",
      "args": [
        "@stdiobus/workers-registry",
        "acp-worker"
      ],
      "instances": 1,
      "env": {
        "LOG_LEVEL": "debug",
        "NODE_ENV": "development"
      }
    },
    {
      "id": "echo-worker",
      "command": "npx",
      "args": [
        "@stdiobus/workers-registry",
        "echo-worker"
      ],
      "instances": 1,
      "env": {
        "LOG_LEVEL": "debug"
      }
    }
  ],
  "limits": {
    "max_restarts": 10,
    "restart_window_sec": 120
  }
}
Code block in JSON, 33 lines

Production Examples

High-Availability Configuration

Production-ready configuration with multiple instances and appropriate limits:

{
  "pools": [
    {
      "id": "acp-registry",
      "command": "npx",
      "args": [
        "@stdiobus/workers-registry",
        "acp-worker"
      ],
      "instances": 4,
      "env": {
        "NODE_ENV": "production",
        "LOG_LEVEL": "info"
      }
    },
    {
      "id": "registry-launcher",
      "command": "npx",
      "args": [
        "@stdiobus/workers-registry",
        "registry-launcher",
        "/etc/stdiobus/api-keys.json"
      ],
      "instances": 2,
      "env": {
        "NODE_ENV": "production",
        "LOG_LEVEL": "info"
      }
    }
  ],
  "limits": {
    "max_input_buffer": 4194304,
    "max_output_queue": 16777216,
    "max_restarts": 5,
    "restart_window_sec": 60,
    "drain_timeout_sec": 30,
    "backpressure_timeout_sec": 60
  }
}
Code block in JSON, 39 lines

Docker Production Configuration

Optimized for Docker deployment:

{
  "pools": [
    {
      "id": "acp-registry",
      "command": "node",
      "args": [
        "/workers-registry/out/dist/index.js",
        "acp-worker"
      ],
      "instances": 4,
      "env": {
        "NODE_ENV": "production",
        "LOG_LEVEL": "warn"
      }
    }
  ],
  "limits": {
    "max_input_buffer": 2097152,
    "max_output_queue": 8388608,
    "max_restarts": 3,
    "restart_window_sec": 60,
    "drain_timeout_sec": 30,
    "backpressure_timeout_sec": 60
  }
}
Code block in JSON, 25 lines

Kubernetes Production Configuration

Configuration for Kubernetes deployment with health checks:

{
  "pools": [
    {
      "id": "acp-registry",
      "command": "node",
      "args": [
        "/app/workers-registry/out/dist/index.js",
        "acp-worker"
      ],
      "instances": 2,
      "env": {
        "NODE_ENV": "production",
        "LOG_LEVEL": "info",
        "POD_NAME": "${POD_NAME}",
        "POD_NAMESPACE": "${POD_NAMESPACE}"
      }
    }
  ],
  "limits": {
    "max_input_buffer": 4194304,
    "max_output_queue": 16777216,
    "max_restarts": 5,
    "restart_window_sec": 60,
    "drain_timeout_sec": 45,
    "backpressure_timeout_sec": 90
  }
}
Code block in JSON, 27 lines

Session Affinity

Messages with the same sessionId are routed to the same worker instance. This is important for maintaining session state.

Enabling Session Affinity

Session affinity is automatic when clients include sessionId in requests:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "test",
  "sessionId": "sess-123",
  "params": {}
}
Code block in JSON, 7 lines

Workers must preserve sessionId in responses:

{
  "jsonrpc": "2.0",
  "id": "1",
  "sessionId": "sess-123",
  "result": {}
}
Code block in JSON, 6 lines

Configuration Considerations

When using session affinity:

  1. Multiple instances: Configure enough instances to handle concurrent sessions
  2. Restart limits: Set appropriate restart limits to avoid session loss
  3. Drain timeout: Allow enough time for sessions to complete during shutdown
{
  "pools": [
    {
      "id": "acp-registry",
      "command": "node",
      "args": ["..."],
      "instances": 4
    }
  ],
  "limits": {
    "max_restarts": 5,
    "drain_timeout_sec": 60
  }
}
Code block in JSON, 14 lines

Environment Variables

Workers can receive environment variables through the pool configuration:

Common Environment Variables

{
  "pools": [
    {
      "id": "worker",
      "command": "node",
      "args": ["..."],
      "instances": 1,
      "env": {
        "NODE_ENV": "production",
        "LOG_LEVEL": "info",
        "DEBUG": "false",
        "TIMEOUT": "30000"
      }
    }
  ]
}
Code block in JSON, 16 lines

Worker-Specific Variables

ACP Worker:

{
  "env": {
    "MCP_SERVERS": "server1,server2",
    "MCP_CONFIG_PATH": "/path/to/mcp-servers.json"
  }
}
Code block in JSON, 6 lines

Registry Launcher:

{
  "env": {
    "REGISTRY_URL": "https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json",
    "CACHE_TTL": "3600"
  }
}
Code block in JSON, 6 lines

MCP-to-ACP Proxy:

{
  "env": {
    "ACP_HOST": "localhost",
    "ACP_PORT": "9000",
    "AGENT_ID": "claude-acp"
  }
}
Code block in JSON, 7 lines

Running stdio Bus

With Docker

docker run \
  --name stdiobus \
  -p 9000:9000 \
  -v $(pwd)/config.json:/config.json:ro \
  -v $(pwd):/stdiobus:ro \
  stdiobus/stdiobus:latest \
  --config /config.json --tcp 0.0.0.0:9000
Code block in Bash, 7 lines

With Binary

./stdio_bus --config config.json --tcp 0.0.0.0:9000
Code block in Bash, 1 line

With Unix Socket

./stdio_bus --config config.json --unix /tmp/stdiobus.sock
Code block in Bash, 1 line

Configuration Best Practices

Development

  • Use single instances for easier debugging
  • Enable debug logging
  • Set higher restart limits
  • Use shorter timeouts for faster iteration
{
  "pools": [
    {
      "id": "worker",
      "command": "node",
      "args": ["..."],
      "instances": 1,
      "env": {
        "LOG_LEVEL": "debug",
        "NODE_ENV": "development"
      }
    }
  ],
  "limits": {
    "max_restarts": 10,
    "restart_window_sec": 120,
    "drain_timeout_sec": 15
  }
}
Code block in JSON, 19 lines

Staging

  • Use multiple instances to test load balancing
  • Enable info-level logging
  • Use production-like limits
  • Test session affinity
{
  "pools": [
    {
      "id": "worker",
      "command": "node",
      "args": ["..."],
      "instances": 2,
      "env": {
        "LOG_LEVEL": "info",
        "NODE_ENV": "staging"
      }
    }
  ],
  "limits": {
    "max_input_buffer": 2097152,
    "max_output_queue": 8388608,
    "max_restarts": 5,
    "restart_window_sec": 60
  }
}
Code block in JSON, 20 lines

Production

  • Use multiple instances for high availability
  • Enable warn or error-level logging
  • Set conservative restart limits
  • Use appropriate buffer sizes
  • Configure proper timeouts
{
  "pools": [
    {
      "id": "worker",
      "command": "node",
      "args": ["..."],
      "instances": 4,
      "env": {
        "LOG_LEVEL": "warn",
        "NODE_ENV": "production"
      }
    }
  ],
  "limits": {
    "max_input_buffer": 4194304,
    "max_output_queue": 16777216,
    "max_restarts": 3,
    "restart_window_sec": 60,
    "drain_timeout_sec": 30,
    "backpressure_timeout_sec": 60
  }
}
Code block in JSON, 22 lines

Troubleshooting Configuration

Worker Not Starting

Check:

  • Command path is correct (absolute or in PATH)
  • Arguments are valid
  • Worker executable has execute permissions
  • Environment variables are set correctly

Worker Crashing

Check:

  • Restart limits are not too low
  • Restart window is appropriate
  • Worker logs for error messages
  • Resource limits are sufficient

Connection Issues

Check:

  • Buffer sizes are appropriate for message sizes
  • Backpressure timeout is sufficient
  • Network configuration is correct
  • Firewall rules allow connections

Performance Issues

Check:

  • Number of instances matches load
  • Buffer sizes are appropriate
  • Timeouts are not too short
  • Session affinity is working correctly

Next Steps

Resources

  • stdio Bus kernel
  • Workers Registry
  • Docker Hub
  • Configuration Examples
stdioBus
© 2026 stdio Bus. All rights reserved.