Prerequisites

Before installing the workers package, ensure you have:

• Node.js ≥20.0.0 - Required for running workers
• stdio Bus kernel - The core message routing daemon

Installing stdio Bus Kernel

The stdio Bus kernel is available through two installation methods:

Option 1: Docker (Recommended)

Pull the official Docker image:

docker pull stdiobus/stdiobus:latest

Docker provides the easiest way to get started with stdio Bus, with pre-configured environments and automatic updates.

Option 2: Build from Source

For advanced users who need custom builds or want to contribute:

git clone https://github.com/stdiobus/stdiobus
cd stdiobus
# Follow build instructions in the repository

See the stdio Bus kernel repository for detailed build instructions.

Installing Workers Package

Install the workers registry package via npm:

npm install @stdiobus/workers-registry

This package includes all worker implementations:

• ACP Worker
• Registry Launcher
• MCP-to-ACP Proxy
• Echo Worker
• MCP Echo Server

Quick Start

Get a basic stdio Bus deployment running with the ACP Worker in three steps:

1. Create Configuration File

Create a config.json file with your worker configuration:

{
  "pools": [
    {
      "id": "acp-registry",
      "command": "npx",
      "args": [
        "@stdiobus/workers-registry",
        "acp-worker"
      ],
      "instances": 1
    }
  ]
}

2. Start stdio Bus

Using Docker:

docker run -p 9000:9000 \
  -v $(pwd):/stdiobus:ro \
  -v $(pwd)/config.json:/config.json:ro \
  stdiobus/stdiobus:latest \
  --config /config.json --tcp 0.0.0.0:9000

Using Binary:

./stdio_bus --config config.json --tcp 0.0.0.0:9000

3. Test Your Setup

Verify the installation by sending a test message:

echo '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"clientInfo":{"name":"test","version":"1.0"}}}' | nc localhost 9000

You should receive a JSON-RPC response confirming the connection.

Basic Worker Usage

Running Workers with the Universal Launcher

The simplest way to run any worker:

npx @stdiobus/workers-registry <worker-name>

Available workers:

• acp-worker - Full ACP protocol implementation
• registry-launcher - Routes to ACP Registry agents
• echo-worker - Simple echo for testing
• mcp-echo-server - MCP server example
• mcp-to-acp-proxy - Protocol bridge for IDEs

Example: Running Echo Worker

Test your setup with the echo worker:

# Run echo worker directly
npx @stdiobus/workers-registry echo-worker

Or configure it in stdio Bus:

{
  "pools": [{
    "id": "echo-worker",
    "command": "npx",
    "args": [
      "@stdiobus/workers-registry",
      "echo-worker"
    ],
    "instances": 1
  }]
}

Verification

After installation, verify everything is working:

1. Check Node.js version:

   Bash

   node --version  # Should be ≥20.0.0

2. Verify package installation:

   Bash

   npm list @stdiobus/workers-registry

3. Test stdio Bus connection:

   Bash

   # Start stdio Bus with your config
   # Then test with netcat
   echo '{"jsonrpc":"2.0","id":"1","method":"test"}' | nc localhost 9000

Next Steps

Now that you have workers installed:

• Configure Workers - Learn about configuration options for production deployments
• Explore Worker Types - Discover specific workers like ACP Worker or Registry Launcher
• Integration Patterns - See integration examples for Node.js and other platforms
• Troubleshooting - Check the troubleshooting guide if you encounter issues

Common Installation Issues

Node.js Version Mismatch

If you see errors about Node.js version:

node --version  # Check current version
nvm install 20  # Install Node.js 20 if using nvm

Permission Errors

For global installations that require elevated permissions:

npm install -g @stdiobus/workers-registry  # May need sudo
# Or use npx to run without installing
npx stdiobus-acp-worker

Docker Connection Issues

If Docker can't connect to stdio Bus:

# Verify Docker is running
docker ps
 
# Check port availability
netstat -an | grep 9000

See the troubleshooting guide for more detailed solutions.