Tutorial: Setting Up a Runner

Beginner — 5 minutes

Learn how to install, register, and verify an AgentsMesh Runner step by step. A Runner is required before you can create Pods.

Prerequisites

Before starting, make sure you have:

An AgentsMesh account (sign up at the registration page)
A machine with Linux, macOS, or Windows (WSL2 recommended)
Git installed and configured on the machine
Network access to the AgentsMesh server

Install the Runner

Download and install the AgentsMesh Runner on your machine. Choose the method that works best for you:

One-Line Install (Recommended) — Works on Linux and macOS:

curl -fsSL https://agentsmesh.ai/install.sh | sh

The one-line installer automatically detects your OS and architecture.

Register the Runner

After installation, register the Runner with your AgentsMesh instance. You have two options:

Option A: Register with a token (headless servers)

Get a registration token from Settings → Runners → Create Token in the web interface, then run the register command with your token.

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

Option B: Register with browser login (developer machines)

Run the login command — a browser window opens for authentication. Best for machines where you have a browser.

agentsmesh-runner login

Registration tokens are single-use. Once registered, the Runner receives mTLS certificates for secure communication.

Start the Runner

After registration, start the Runner daemon:

agentsmesh-runner run

Run the start command to begin the Runner process
The Runner connects to the AgentsMesh backend via gRPC with mTLS
It reports available AI agent CLIs (Claude Code, Codex, Gemini, etc.) found in PATH

For production deployments, install the Runner as a system service so it starts automatically on boot.

Run in the background

`agentsmesh-runner run` stays attached to your terminal. Pick a background mode if you want the Runner to survive closing the shell:

System service (recommended)

Register the Runner with systemd / launchd / Windows Service Manager so it starts on boot, restarts on failure, and writes logs to the OS journal.

Install and start

sudo agentsmesh-runner service install
sudo agentsmesh-runner service start
sudo agentsmesh-runner service status

Stop or uninstall

sudo agentsmesh-runner service stop
# Remove from startup entirely:
sudo agentsmesh-runner service uninstall

On Linux, logs go to journalctl -u agentsmesh-runner. On macOS, ~/Library/Logs/agentsmesh-runner.log. Use --config /path/to/config.yaml if your config is non-default.

Shell background (nohup)

Quick and service-free — fork the process with nohup and record its PID so you can stop it later. Good for dev boxes and short-lived hosts.

Start and tail logs

nohup agentsmesh-runner run > ~/agentsmesh-runner.log 2>&1 &
echo $! > ~/.agentsmesh/runner.pid
tail -f ~/agentsmesh-runner.log

Stop the process

# Graceful stop by PID file
kill "$(cat ~/.agentsmesh/runner.pid)"

# Fallback if PID was lost
pkill -f agentsmesh-runner

nohup does not auto-restart on crash or reboot. For anything long-running, prefer the system service option above.

Install AI Agent CLIs

Install the AI coding agents you want to use on the Runner machine:

Claude Code — npm install -g @anthropic-ai/claude-code (set ANTHROPIC_API_KEY)
Codex CLI — npm install -g @openai/codex (set OPENAI_API_KEY)
Gemini CLI — npm install -g @google/gemini-cli (set GOOGLE_API_KEY)

After installing, restart the Runner or wait for the next heartbeat. Newly available agents appear in the New Pod dialog.

Verify the Runner is Online

Check that your Runner is connected and ready:

Go to Settings → Runners in the web interface
Find your Runner in the list — it should show a green Online status
Check that the available agents are listed correctly
Try creating a test Pod to confirm everything works

Keep the Runner Up to Date

New Runner releases ship bug fixes, security patches, and protocol improvements. Pick whichever update method fits your deployment:

From the Web Dashboard

For connected Runners, trigger an upgrade remotely without touching the host machine.

Open Settings → Runners and locate your Runner card.
Click the Upgrade badge when a newer version is available.
The platform sends a signed upgrade command over gRPC; the Runner downloads, swaps its binary, and restarts automatically.

The Runner must be online and permitted to auto-update. Active Pods finish gracefully before the restart.

With the Update Command

SSH or shell into the Runner host and let the Runner update itself from GitHub Releases.

agentsmesh-runner update              # Interactive prompt
agentsmesh-runner update --check      # Only check, do not install
agentsmesh-runner update -y           # Skip confirmation
agentsmesh-runner update -v v1.2.3    # Pin to a specific version

A backup of the previous binary is created before replacement. If the update fails, the Runner automatically rolls back.

Re-install from install.sh

If the self-update path is blocked (air-gapped host, unusual distro, or you want a fresh binary), re-run the official installer.

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

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

Restart after install

# System service
sudo agentsmesh-runner service restart

# CLI mode
pkill agentsmesh-runner && agentsmesh-runner run

Re-installing preserves ~/.agentsmesh/config.yaml and the mTLS certificates — you do not need to re-register.

Troubleshooting

Runner shows Offline — Check network connectivity and ensure firewalls allow outbound gRPC connections (port 9443)

Pods fail to start — Verify Git is installed and the Runner has access to clone repositories

Token invalid error — Registration tokens are single-use. Create a new token from Settings → Runners

What's Next?

Your Runner is ready. Continue with the next tutorial:

Connect Git Repositories — Link your code repositories for Pod access

Your First Pod — Create and interact with your first AI agent