Skip to main content
Magpie is a Rust workspace with four crates. This guide covers installation, prerequisites, build process, and environment configuration.

​
System requirements

Operating System

  • Linux: Ubuntu 20.04+, Debian 11+, or equivalent
  • macOS: 12 (Monterey) or later
  • Windows: WSL2 recommended

Hardware

  • CPU: x86_64 or ARM64
  • RAM: 4GB minimum, 8GB recommended
  • Disk: 2GB for build artifacts

​
Prerequisites

Install these tools before building Magpie:

​
Rust 1.75+

1

Install rustup

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Follow the interactive prompts to complete installation.
2

Configure your PATH

Add Cargo’s bin directory to your shell profile:
# For bash
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
3

Verify installation

rustc --version
# Should output: rustc 1.75.0 or higher

cargo --version
# Should output: cargo 1.75.0 or higher
Rust releases every 6 weeks. Keep up to date with rustup update.

​
Claude CLI

The Claude CLI powers both Tier 1 (text generation) and Tier 2 (Goose agent) LLM calls.
1

Install Claude CLI

Follow the official Claude Code documentation to install the CLI for your platform.
2

Authenticate

Run claude interactively to complete authentication:
claude
You’ll be prompted to log in via your browser.
3

Test with a prompt

claude -p "Say hello in one word"
# Should output: Hello
Magpie requires the Claude CLI to be authenticated. The pipeline will fail if claude -p doesn’t work.

​
Git and GitHub CLI

Git handles branch operations. The GitHub CLI (gh) automates PR creation. 
# Git is pre-installed on macOS
git --version

# Install GitHub CLI
brew install gh
1

Authenticate with GitHub

gh auth login
Follow the prompts to authenticate via browser or token.
2

Verify access

gh repo view
# Should show details of the current repository

​
Optional: C++ compiler

Required for building Goose dependencies (candle, llama-cpp). 
xcode-select --install

​
Build Magpie

1

Clone the repository

git clone https://github.com/your-org/magpie.git
cd magpie
2

Build all crates

cargo build --release
First build timing: 4-5 minutes due to Goose transitive dependencies (candle, llama-cpp, tree-sitter). Subsequent builds are much faster thanks to Cargo’s incremental compilation.
This builds all four crates:
  • magpie-core (library)
  • magpie-cli (binary)
  • magpie-discord (binary)
  • magpie-teams (binary)
3

Verify binaries

ls -lh target/release/magpie-*
# Should show: magpie-cli, magpie-discord, magpie-teams

./target/release/magpie-cli --help

​
Build individual crates

To build only specific crates: 
cargo build --release -p magpie-cli

​
Run tests

1

Run fast tests

cargo test
This runs unit tests that don’t require external services.
2

Run integration tests (optional)

Some tests are marked #[ignore] because they require the claude CLI or a real git repository:
cargo test -- --ignored
Integration tests make real API calls and may take several minutes.
3

Test specific crate

cargo test -p magpie-core
4

Run a single test

cargo test -p magpie-core test_slug

​
Configuration

Magpie is configured entirely via environment variables. All adapters (CLI, Discord, Teams) read from the same variables.

​
Core pipeline settings

​
MAGPIE_REPO_DIR
string
default:". (cwd)"
Path to the git repository to operate on. The agent’s file operations and git commands target this directory.
export MAGPIE_REPO_DIR="/Users/you/code/api-service"
​
MAGPIE_BASE_BRANCH
string
default:"main"
Base branch for new feature branches. Magpie creates branches like magpie/{slug} from this branch.
export MAGPIE_BASE_BRANCH="main"
​
MAGPIE_TEST_CMD
string
default:"cargo test"
Command to run tests during the CI loop. Customize for your project’s test runner.
export MAGPIE_TEST_CMD="npm test"
export MAGPIE_TEST_CMD="pytest tests/"
export MAGPIE_TEST_CMD="go test ./..."
​
MAGPIE_LINT_CMD
string
default:"cargo clippy"
Command to run lints during the CI loop.
export MAGPIE_LINT_CMD="npm run lint"
export MAGPIE_LINT_CMD="ruff check ."
export MAGPIE_LINT_CMD="golangci-lint run"
​
MAGPIE_MAX_CI_ROUNDS
integer
default:"2"
Maximum lint → test → fix retries. After this many rounds, the pipeline returns PartialSuccess status.
export MAGPIE_MAX_CI_ROUNDS="3"
​
MAGPIE_GITHUB_ORG
string
default:"None"
GitHub organization to restrict repo access. When set, the pipeline resolves the target repo from the task message and clones it into a temp workspace.
export MAGPIE_GITHUB_ORG="your-company"
This enables multi-repo support. Example task: "fix bug in api-service" → Magpie clones your-company/api-service.

​
Plane integration (optional)

Connect to a self-hosted Plane instance for issue tracking:
​
PLANE_BASE_URL
string
required
URL of your Plane instance.
export PLANE_BASE_URL="https://plane.yourcompany.com"
​
PLANE_API_KEY
string
required
Plane API key for authentication.
export PLANE_API_KEY="your-api-key-here"
​
PLANE_WORKSPACE_SLUG
string
required
Workspace slug where issues will be created.
export PLANE_WORKSPACE_SLUG="engineering"
​
PLANE_PROJECT_ID
string
required
Project ID for auto-created issues.
export PLANE_PROJECT_ID="proj-123abc"

​
Discord bot (optional)

Run Magpie as a Discord bot that responds to @magpie mentions:
​
DISCORD_TOKEN
string
required
Discord bot token from the Discord Developer Portal.
export DISCORD_TOKEN="your-discord-bot-token"
Run the Discord bot: 
cargo run --release -p magpie-discord
The Discord adapter creates a new thread for each task and archives it after the pipeline completes.

​
Teams webhook (optional)

Run Magpie as a Microsoft Teams webhook:
​
TEAMS_APP_ID
string
required
Bot Framework app ID.
export TEAMS_APP_ID="your-app-id"
​
TEAMS_APP_SECRET
string
required
Bot Framework app secret.
export TEAMS_APP_SECRET="your-app-secret"
​
TEAMS_LISTEN_ADDR
string
default:"0.0.0.0:3978"
Address for the webhook server.
export TEAMS_LISTEN_ADDR="0.0.0.0:8080"
Run the Teams webhook: 
cargo run --release -p magpie-teams

​
Daytona sandbox (optional)

Execute pipeline commands in remote Daytona sandboxes:
​
DAYTONA_API_KEY
string
required
Daytona API key.
export DAYTONA_API_KEY="your-api-key"
​
DAYTONA_BASE_URL
string
default:"https://app.daytona.io/api"
Daytona API base URL.
export DAYTONA_BASE_URL="https://daytona.yourcompany.com/api"
​
DAYTONA_ORGANIZATION_ID
string
Organization ID for multi-tenant Daytona instances.
export DAYTONA_ORGANIZATION_ID="org-123abc"
​
DAYTONA_SANDBOX_CLASS
string
default:"small"
Sandbox size class (small, medium, large).
export DAYTONA_SANDBOX_CLASS="medium"
​
DAYTONA_SNAPSHOT_NAME
string
Pre-built snapshot to use for faster sandbox creation.
export DAYTONA_SNAPSHOT_NAME="rust-1.75-ubuntu"
​
DAYTONA_ENV
string
Comma-separated KEY=VALUE pairs to inject into the sandbox environment.
export DAYTONA_ENV="RUST_LOG=debug,CARGO_TERM_COLOR=always"
​
DAYTONA_VOLUME_ID
string
Persistent volume ID to mount in the sandbox.
export DAYTONA_VOLUME_ID="vol-123abc"
​
DAYTONA_VOLUME_MOUNT_PATH
string
Path where the volume should be mounted.
export DAYTONA_VOLUME_MOUNT_PATH="/mnt/data"
Build with Daytona support: 
cargo build --release -p magpie-core --features daytona

​
Using a .env file

Instead of exporting variables manually, create a .env file:
.env
# Core pipeline
MAGPIE_REPO_DIR=/Users/you/code/api-service
MAGPIE_BASE_BRANCH=main
MAGPIE_TEST_CMD="cargo test"
MAGPIE_LINT_CMD="cargo clippy -- -D warnings"
MAGPIE_MAX_CI_ROUNDS=2

# Optional: GitHub org
MAGPIE_GITHUB_ORG=your-company

# Optional: Plane
PLANE_BASE_URL=https://plane.yourcompany.com
PLANE_API_KEY=your-api-key
PLANE_WORKSPACE_SLUG=engineering
PLANE_PROJECT_ID=proj-123abc

# Optional: Discord
DISCORD_TOKEN=your-discord-token

# Optional: Daytona
DAYTONA_API_KEY=your-daytona-key
DAYTONA_SANDBOX_CLASS=medium
Magpie automatically loads .env from the current directory via dotenvy::dotenv() at startup.
Add .env to .gitignore to avoid committing secrets.

​
Verify installation

Run these commands to ensure everything is configured correctly:
1

Test single prompt

./target/release/magpie-cli "Say hello"
Should return a greeting from the agent.
2

Test blueprint demo

./target/release/magpie-cli --demo
Should list files and summarize them.
3

Dry-run the pipeline

Create a test repository:
mkdir /tmp/magpie-test
cd /tmp/magpie-test
git init
git config user.name "Test User"
git config user.email "test@example.com"
echo "# Test" > README.md
git add README.md
git commit -m "Initial commit"
Run a simple task:
MAGPIE_REPO_DIR=/tmp/magpie-test \
MAGPIE_TEST_CMD="echo 'tests pass'" \
MAGPIE_LINT_CMD="echo 'lints pass'" \
  ./target/release/magpie-cli --pipeline "add a hello world file"
For production deployments, see Deployment Guide for Docker, Kubernetes, and systemd configurations.

​
Troubleshooting

Install a C++ compiler:
# macOS
xcode-select --install

# Linux (Debian/Ubuntu)
sudo apt install build-essential

# Linux (Fedora/RHEL)
sudo dnf groupinstall "Development Tools"
The Claude CLI is not installed or not in your PATH. Follow the Claude Code setup guide.
Install the GitHub CLI:
# macOS
brew install gh

# Linux (Debian/Ubuntu)
sudo apt install gh
Then authenticate: gh auth login
Ensure MAGPIE_REPO_DIR points to a valid git repository:
cd $MAGPIE_REPO_DIR
git status
Some integration tests make real API calls. Skip them:
cargo test --lib
Verify the bot has these permissions in your Discord server:
  • Read Messages/View Channels
  • Send Messages
  • Create Public Threads
  • Manage Threads
Check the bot token is correct: echo $DISCORD_TOKEN

​
Next steps

Quickstart

Run your first end-to-end pipeline

Architecture

Understand Magpie’s two-tier agent system and blueprint engine

Chat adapters

Set up Discord or Teams integrations

API reference

Explore the programmatic API

Build docs developers (and LLMs) love

Get started for freeTalk to us