Runner Setup

Runners are the execution environments for AI agent Pods. Set up a runner on any machine with Git and your preferred development tools installed.

System Requirements

Linux, macOS, or Windows (WSL2 recommended)
Git installed and configured
Docker (optional, for containerized agents)
Network access to AgentsMesh server
At least 4GB RAM (8GB+ recommended for multiple Pods)

Quick Installation

One-Line Install (Recommended)

# macOS / Linux
curl -fsSL https://api.agentsmesh.ai/install.sh | sh

# Windows (PowerShell)
irm https://api.agentsmesh.ai/install.ps1 | iex

macOS (Homebrew)

# Add AgentsMesh tap
brew tap agentsmesh/tap https://github.com/AgentsMesh/BrewCask

# Install runner
brew install agentsmesh/tap/agentsmesh-runner

Linux (Package Manager)

The one-line script above also works on Linux. Alternatively, download .deb/.rpm/.apk packages from GitHub Releases.

After Installation

Option A: Register with a token

agentsmesh-runner register \
  --server https://api.agentsmesh.ai \
  --token <YOUR_TOKEN>
agentsmesh-runner run

Option B: Register with browser login

agentsmesh-runner login
agentsmesh-runner run

Get your registration token from Settings → Runners → Create Token in the AgentsMesh web interface.

Docker Installation

# Run with Docker
docker run -d \
  --name agentsmesh-runner \
  -e AGENTSMESH_TOKEN=<YOUR_TOKEN> \
  -e AGENTSMESH_URL=https://api.agentsmesh.ai \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.ssh:/root/.ssh:ro \
  agentsmesh/runner:latest

Docker Compose

# docker-compose.yml
version: '3.8'
services:
  runner:
    image: agentsmesh/runner:latest
    container_name: agentsmesh-runner
    restart: unless-stopped
    environment:
      - AGENTSMESH_TOKEN=${AGENTSMESH_TOKEN}
      - AGENTSMESH_URL=${AGENTSMESH_URL:-https://api.agentsmesh.ai}
      - MAX_CONCURRENT_PODS=5
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ~/.ssh:/root/.ssh:ro
      - runner-data:/data
volumes:
  runner-data:

Environment Variables

Variable	Description	Default
AGENTSMESH_TOKEN	Registration token (required)	-
AGENTSMESH_URL	AgentsMesh server URL	https://api.agentsmesh.ai
MAX_CONCURRENT_PODS	Maximum concurrent Pods	5
WORKSPACE_DIR	Base directory for workspaces	/data/workspaces
MCP_PORT	MCP server port	19000

Creating a Registration Token

Go to Settings → Runners in the web interface
Click Create Token
Set an optional description and expiration
Copy the generated token
Use the token when configuring your runner

Security Note: Registration tokens are one-time use. Once a runner registers, it receives mTLS certificates for secure communication. You can revoke certificates from the runner settings if needed.

Verifying Installation

After starting the runner, verify it's connected:

Go to Settings → Runners in the web interface
Find your runner in the list — it should show ● Online
Try creating an AgentPod using this runner

Troubleshooting

Runner shows as Offline

Check network connectivity to the AgentsMesh server. Ensure firewalls allow outbound gRPC connections (port 9443 for mTLS).

Pods fail to start

Verify Git is installed and configured. Check that the runner has access to clone repositories (SSH keys or tokens configured).

"Token invalid" error

Registration tokens are single-use. Create a new token from Settings → Runners if the original was already used.