Downloads

Download Champ.

Get the tools you need to work with ChampHQ

Free and open source • Available for all platforms

Command line

Champ Runner

Command-line tool to run your AI champs locally

Windows

Windows 10/11 (64-bit)

Download for Windows

Version 1.0.0 • 8.2 MB

macOS

macOS 11+ (Intel & Apple Silicon)

Apple Silicon (M1/M2/M3) Intel (x64)

Version 1.0.0 • 8.4-8.6 MB

Linux

Ubuntu, Debian, Fedora, etc.

x64 (64-bit) ARM64

Version 1.0.0 • 7.6-7.9 MB

Docker

Run Champ Runner in a pre-configured Docker container with Python, Node.js, and Chromium included. The container automatically downloads the latest version on each start.

1.Pull the Image

docker pull public.ecr.aws/c3u5m6o1/champ-runner:latest

Or build from source:

docker build -f docker/Dockerfile.runner -t champ-runner:latest .

2.Run the Container

docker run -e CONNECT_TOKEN="<YOUR_TOKEN>" -v $(pwd):/work champ-runner:latest

Replace <YOUR_TOKEN> with your connection token from the ChampHQ web interface.

→What's Included

  • Node.js 22 with npm
  • Python 3 with pip
  • Chromium for headless browser automation
  • Git and common build tools
  • Browser skill enabled by default (--enable-browser)
  • Always downloads the latest champ-runner binary on startup

Installation Instructions

Windows Installation

  1. Download the champ-runner-windows-amd64.exe file
  2. Rename it to champ-runner.exe (optional)
  3. Move to a directory in your PATH or run from current location
  4. Open Command Prompt or PowerShell
  5. Verify installation: champ-runner --version

macOS Installation

  1. Download the appropriate binary for your Mac (ARM64 for M1/M2/M3, AMD64 for Intel)
  2. Open Terminal and navigate to the download location
  3. Make executable: chmod +x champ-runner-darwin-arm64 (or chmod +x champ-runner-darwin-amd64 for Intel)
  4. Optional: Sign the binary to avoid security warnings: codesign -s - -f champ-runner-darwin-arm64
  5. Move to PATH: sudo mv champ-runner-darwin-* /usr/local/bin/champ-runner
  6. Verify installation: champ-runner --version

Note: If you skip the codesign step, on first run you may need to allow the app in System Preferences → Security & Privacy, or right-click the binary and select "Open" to bypass Gatekeeper.

Linux Installation

  1. Download the appropriate binary (amd64 for x64, arm64 for ARM)
  2. Open Terminal and navigate to the download location
  3. Make executable: chmod +x champ-runner-linux-amd64 (or chmod +x champ-runner-linux-arm64 for ARM)
  4. Move to PATH: sudo mv champ-runner-linux-* /usr/local/bin/champ-runner
  5. Verify installation: champ-runner --version

How to Use Champ Runner

1.Enable Expert Mode

First, you need to enable Expert Mode in your ChampHQ account to access the connection token feature.

  1. Log in to your ChampHQ account at app.champhq.ai
  2. Navigate to Settings (click your profile icon in the top right)
  3. Find the Expert Mode toggle and enable it
  4. Expert Mode unlocks advanced features including local champ execution

2.Get Your Connection Token

Once Expert Mode is enabled, you can generate a connection token for your champ.

  1. Go to the Champs page
  2. Find the champ you want to run locally
  3. Click the link icon (🔗) next to the champ's name
  4. A modal will appear with your unique connection token
  5. Copy the token - you'll need it to connect Champ Runner

Security Note: Keep your connection token private. It provides access to run missions as your champ.

3.Connect and Run

Configure your runner options and copy the command:

./champ-runner --connect <YOUR_TOKEN>

Replace <YOUR_TOKEN> with the token you copied from the web interface.

4.What Happens Next

Once connected, Champ Runner will:

  • Connect to the ChampHQ mission queue
  • Wait for missions assigned to your champ
  • Execute missions locally on your machine
  • Send results back to ChampHQ in real-time
  • Continue running until you stop it (Ctrl+C)

Tip: Keep the terminal window open while Champ Runner is active. You'll see live logs of mission execution.

→Additional Options

champ-runner --connect <TOKEN> --enable-browser

Enable the built-in headless browser with Chrome DevTools Protocol (CDP). Gives your champ the ability to browse the web, take screenshots, and interact with web pages.

champ-runner --connect <TOKEN> --enable-desktop

Enable the desktop skill — screenshot capture, mouse control, and keyboard input on your local machine.

champ-runner --connect <TOKEN> --no-sandbox

Disable the filesystem sandbox (Landlock). Use when the runner needs access to directories outside the working directory.

champ-runner --connect <TOKEN> --tunnel

Enable tunnel to expose local ports through the tunnel server. Useful for previewing web apps running locally.

champ-runner --connect <TOKEN> --worktree

Use a git worktree per mission, isolating file changes so each mission works on its own branch.

champ-runner --connect <TOKEN> --debug

Enable debug logging for troubleshooting connection or execution issues.

champ-runner --connect <TOKEN> --mcp "uvx mcp-server-git" --mcp "fs:npx -y @modelcontextprotocol/server-filesystem /work"

Attach one or more stdio MCP servers. Each server's tools are registered automatically. Use name:command to override the server name.

champ-runner --version

Show the current version.

champ-runner --help

Show all available commands and options.

Tip: You can combine flags, e.g. champ-runner --connect <TOKEN> --enable-browser --worktree --debug

MCP Servers

Extend your champ runner with any Model Context Protocol server. Each MCP server you attach adds its tools directly to the runner — your champ can call them just like built-in skills.

How It Works

The runner spawns each MCP server as a subprocess, discovers its tools via the MCP protocol, and registers them individually. Tools appear as <server>__<tool> in your champ's skill list. 

# Single MCP server
./champ-runner --connect <TOKEN> --mcp "uvx mcp-server-git"

# Multiple servers
./champ-runner --connect <TOKEN> \
  --mcp "uvx mcp-server-git" \
  --mcp "fs:npx -y @modelcontextprotocol/server-filesystem /work"

Name Override

By default the server name comes from the MCP initialize response. Prefix your command with name: to override it: 

# Tool will be registered as fs__read_file, not filesystem__read_file
--mcp "fs:npx -y @modelcontextprotocol/server-filesystem /work"

Popular MCP Servers

uvx mcp-server-git Git operations — log, diff, status, commit on your local repos
uvx mcp-server-fetch Fetch web pages and APIs — gives your champ live internet access
npx -y @modelcontextprotocol/server-filesystem /path Filesystem access — read, write, search files in the given directory

Find more at github.com/modelcontextprotocol/servers

Bring Your Own MCP

Any stdio-compatible MCP server works — including ones you build yourself. Connect your champ to internal APIs, proprietary databases, or custom tooling without writing any ChampHQ code. 

./champ-runner --connect <TOKEN> --mcp "python3 my-internal-api-mcp.py"

The MCP protocol is an open standard. If it speaks JSON-RPC 2.0 over stdio, your champ can use it. This effectively turns the runner into an extensible plugin system — ship tools to your champ without waiting for a ChampHQ release.

Why Run Locally?

  • Privacy: Your champ runs on your machine with your local resources
  • Performance: Direct access to your local files and tools
  • Development: Test and debug champs in your local environment
  • Control: Full control over execution environment and dependencies
  • Cost: Use your own compute resources instead of cloud credits
Microsoft 365

Office Add-in

Chat with your champs from a task pane inside Word, Excel, and PowerPoint

Office Add-in

Runs as a task pane inside Word, Excel, and PowerPoint

Download manifest.xml

Save this file somewhere you can find it — you'll select it in step 3 below.

Installation Instructions

→Sideload in Office on the Web

  1. Open Word, Excel, or PowerPoint on the web (office.com) and open a document
  2. Select Home > Add-ins, then select More Settings
  3. In the Office Add-ins dialog, select Upload My Add-in, browse to the manifest.xml you downloaded, then select Upload

These steps are for Office on the web. Steps for Office desktop apps use different menu names.

You'll need to sign in with a Champ account inside the task pane before you can start a mission.

Deploy to a Team

Sideloading (above) installs the add-in for one user on one machine. To give it to a team, an administrator deploys the same manifest.xml centrally.

  1. Sign in to the Microsoft 365 admin center as an administrator
  2. Select Settings, then choose Integrated apps
  3. Upload this manifest.xml as a custom (line-of-business) app, then assign it to the users or groups who should get it

Requires an administrator role, and the Integrated apps portal is only available to worldwide Microsoft 365 tenants. Full steps: Microsoft's deployment guide.

Browser

Browser Extension

Interact with your champs directly from your browser

Firefox Extension

Development build for Firefox

Download Extension

Version 1.0.0 • Development Build

Chrome Extension

Development build for Chrome

Download Extension

Version 1.0.0 • Development Build

Installation Instructions

→Firefox Installation

  1. Download the firefox.zip file (no need to extract it)
  2. Open Firefox and navigate to about:debugging#/runtime/this-firefox
  3. Click "Load Temporary Add-on..."
  4. Select the downloaded firefox.zip file
  5. The extension will be loaded and active until you restart Firefox

Note: This is a development build. The extension is temporary and will be removed when Firefox restarts. You'll need to load it again each time.

→Chrome Installation

  1. Download the chrome.zip file and unzip it to a folder on your computer
  2. Open Chrome and navigate to chrome://extensions
  3. Enable Developer mode
  4. Click "Load unpacked"
  5. Select the unzipped folder

Note: This is a development build. Keep the unzipped folder in place; Chrome loads the extension from it.

How to Use Browser Extension

1.Open the Extension Sidebar

After installing the extension, you need to open the sidebar to access your champs.

  1. Look for the ChampHQ icon in your Firefox toolbar (top right)
  2. Click the icon to open the extension sidebar
  3. The sidebar will appear on the right side of your browser window

Tip: You can also use the keyboard shortcut Ctrl+Shift+Y (or Cmd+Shift+Y on Mac) to toggle the sidebar.

2.Sign In to Your Account

Connect the extension to your ChampHQ account.

  1. Click the "Sign In" button in the sidebar
  2. You'll be redirected to the ChampHQ login page
  3. Enter your credentials and authorize the extension
  4. You'll be redirected back to the sidebar automatically

3.Select a Champ

Choose which champ you want to interact with.

  1. Click the "Select Champ" dropdown in the sidebar
  2. Browse your available champs
  3. Click on a champ to select it
  4. The chat interface will appear

4.Start Chatting

Now you can interact with your champ directly from the sidebar.

  • Type your message in the input field at the bottom
  • Press Enter to send (or Shift+Enter for new line)
  • Your champ will respond in real-time
  • The conversation syncs with your ChampHQ account

Extension Features

  • Always Available: Access your champs from any webpage
  • Context Aware: Champs can see and interact with the current page
  • Real-time Sync: Conversations sync across all your devices
  • Sidebar Mode: Non-intrusive interface that doesn't block your browsing
  • Quick Access: Toggle sidebar with keyboard shortcut
Editor

ChampHQ for VS Code

Interact with your champs directly from your editor

VS Code Extension

Development build (dev environment)

Download Extension

Version 0.1.0 • Development Build

Installation Instructions

→Option 1: VS Code UI

  1. Download the champ-army-vscode-0.1.0.vsix file
  2. Open VS Code and press Cmd+Shift+P (or Ctrl+Shift+P on Windows/Linux)
  3. Run "Extensions: Install from VSIX..."
  4. Select the downloaded .vsix file

→Option 2: Command Line

  1. Download the champ-army-vscode-0.1.0.vsix file
  2. Run code --install-extension champ-army-vscode-0.1.0.vsix

How to Use ChampHQ for VS Code

1.Sign In

After installing the extension, open the Command Palette and run "ChampHQ: Sign In".

2.Open the ChampHQ Panel

Open the ChampHQ panel from the Activity Bar to start interacting with your champs.

Desktop

ChampHQ for macOS

Native desktop app for chatting with your champs

Champ.app

Universal binary (Apple Silicon & Intel)

Download for macOS

Version 0.1.0 • macOS 10.13 (High Sierra) or later

Installation Instructions

1.Install the App

  1. Download the Champ_0.2.0_universal.dmg file and open it
  2. Drag Champ.app into the Applications folder

Note: Sign-in requires launching the installed Champ.app bundle from Applications (or Spotlight/Launchpad) — the champarmy:// OAuth callback scheme is registered via the app bundle's Info.plist. Running the raw binary inside the bundle directly breaks the login redirect.

How to Use ChampHQ for macOS

1.Sign In

Click Sign in to open your browser and complete the OAuth flow. The browser redirects back into the app automatically once you've signed in.

2.Menu Bar Tray Icon

Champ lives in the macOS menu bar. Click the tray icon to show or hide the window, and use its menu to start a New Mission or Quit the app.

3.Mission Feed & Champ Switcher

Browse missions from the Recent, Bookmarks, Campaigns, and DMs tabs, and switch between champs at any time using the in-app champ switcher.

System Requirements

Windows

  • Windows 10 or later (64-bit)
  • 4 GB RAM minimum
  • 200 MB disk space

macOS

  • macOS 11 (Big Sur) or later
  • 4 GB RAM minimum
  • 200 MB disk space

Linux

  • Ubuntu 20.04+ / Debian 11+
  • 4 GB RAM minimum
  • 200 MB disk space

Additional Resources

View on GitHub Get Support