Installation

Get MARSYS up and running on your system in just a few minutes.

Prerequisites

Python 3.12+ (required)
pip package manager
Git for cloning the repository (optional)
API Keys from at least one provider (OpenAI, Anthropic, Google)

Quick Install

Recommended Setup with uv (10-100x faster than pip)

uv is the recommended package manager for MARSYS. It's significantly faster than pip and handles dependency resolution more reliably.

Step 1: Install uv

Unix/macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Step 2: Create virtual environment

# Create virtual environment
uv venv

# Activate (Unix/macOS)
source .venv/bin/activate

# Activate (Windows)
.venv\Scripts\activate

# Alternative: Use uv run without explicit activation
uv run python your_script.py

Step 3: Install MARSYS

Basic (Recommended) - Everything you need for most use cases:

uv pip install marsys

Includes: API models, browser automation, UI, tools, logging

With Local Models - Add PyTorch and Transformers for local LLM/VLM support:

uv pip install marsys[local-models]

Includes: Everything in Basic + PyTorch, Transformers, TRL, Datasets

Production - High-performance inference with vLLM:

uv pip install marsys[production]

Includes: vLLM, Flash Attention, Triton, Ninja

Development - Complete setup for contributors:

uv pip install marsys[dev]

Includes: Everything + testing, linting, documentation tools

Alternative Installation Methods

Using pip - Standard Python package manager:

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Unix/macOS
# .venv\Scripts\activate  # Windows

# Install MARSYS
pip install marsys

From Source - For development or latest changes:

git clone https://github.com/rezaho/MARSYS.git
cd MARSYS
pip install -e .[dev]

Detailed Installation

1. Set Up Virtual Environment (Recommended: uv)

Best Practice

Always use a virtual environment to avoid dependency conflicts. We recommend uv for faster installation.

uv (Recommended):

# Create virtual environment
uv venv

# Activate (Unix/macOS)
source .venv/bin/activate

# Activate (Windows)
.venv\Scripts\activate

# Or skip activation and use uv run
uv run python your_script.py

venv (Standard):

python -m venv .venv
source .venv/bin/activate  # Unix/macOS
# .venv\Scripts\activate  # Windows

conda:

conda create -n marsys python=3.12
conda activate marsys

2. Choose Your Installation

Installation	Size	Time	Use Case
`marsys`	~200 MB	1-2 min	API models + browser + tools
`marsys[local-models]`	~2-3 GB	5-10 min	+ Local LLMs/VLMs
`marsys[production]`	~1 GB	3-5 min	+ High-performance inference
`marsys[dev]`	~3+ GB	10-15 min	+ Testing & docs tools

Install with uv (recommended):

uv pip install marsys  # or marsys[local-models], etc.

Or with pip:

pip install marsys  # or marsys[local-models], etc.

3. Configure API Keys (Required)

Required Step

You must configure API keys before running any examples. MARSYS needs at least one API provider configured.

Method 1: .env file (Recommended for development)

Create a .env file in your project root:

# .env
# Required: At least one API key
OPENAI_API_KEY="sk-..."           # OpenAI GPT models
ANTHROPIC_API_KEY="sk-ant-..."    # Claude models
GOOGLE_API_KEY="AIza..."          # Gemini models
OPENROUTER_API_KEY="sk-or-..."    # OpenRouter (access to many models)

# Optional: Additional configurations
HEADLESS=true                      # Browser automation mode
LOG_LEVEL=INFO                     # Logging verbosity

MARSYS automatically loads .env files using python-dotenv.

Method 2: Environment variables (Recommended for production)

Unix/macOS/Linux:

export OPENAI_API_KEY="your-key-here"
export ANTHROPIC_API_KEY="your-key-here"
export GOOGLE_API_KEY="your-key-here"
export OPENROUTER_API_KEY="your-key-here"

Windows (Command Prompt):

set OPENAI_API_KEY=your-key-here
set ANTHROPIC_API_KEY=your-key-here
set GOOGLE_API_KEY=your-key-here

Windows (PowerShell):

$env:OPENAI_API_KEY="your-key-here"
$env:ANTHROPIC_API_KEY="your-key-here"
$env:GOOGLE_API_KEY="your-key-here"

Security

Never commit .env files to version control. Add .env to your .gitignore file.

4. Install Browser Automation (Optional)

Only for BrowserAgent

This step is optional and only required if you plan to use BrowserAgent for web automation and scraping.

Important: After installing the playwright package (included in basic installation), you must separately install browser binaries:

# Install Chromium (recommended - smallest download)
playwright install chromium

# Or install all browsers (Chrome, Firefox, WebKit)
playwright install

# On Linux: Install system dependencies
playwright install --with-deps chromium

If you skip this step, BrowserAgent will fail with an error about missing browser binaries. All other MARSYS features will work normally.

Verify Installation

Run this quick test to verify everything is working:

# test_installation.py
import asyncio
from marsys import Orchestra, Agent
from marsys.models import ModelConfig

async def test():
    # Create a simple agent
    agent = Agent(
        model_config=ModelConfig(
            type="api",
            name="anthropic/claude-haiku-4.5",
            provider="openrouter"
        ),
        name="TestAgent",
        goal="Test agent for verification",
        instruction="You are a test agent. Respond to requests clearly and concisely."
    )

    # Run a simple task
    result = await Orchestra.run(
        task="Say 'Hello, MARSYS is working!'",
        topology={"agents": ["TestAgent"], "flows": []}
    )

    print("Installation successful!")
    print(f"Response: {result.final_response}")

if __name__ == "__main__":
    asyncio.run(test())

Run the test:

python test_installation.py

Docker Installation

For containerized deployments:

Using Docker Compose

# docker-compose.yml
version: '3.8'

services:
  marsys:
    image: marsys:latest
    build: .
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - GOOGLE_API_KEY=${GOOGLE_API_KEY}
    volumes:
      - ./workspace:/app/workspace
      - ./logs:/app/logs
    ports:
      - "8000:8000"  # If running web interface

Build and run:

# Build the image
docker-compose build

# Run the container
docker-compose up

Using Docker CLI

# Build image
docker build -t marsys .

# Run container
docker run -it \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -v $(pwd)/workspace:/app/workspace \
  marsys

Package Structure

After installation, you'll have access to:

marsys/
├── src/
│   ├── coordination/     # Orchestra and topology system
│   ├── agents/           # Agent implementations
│   ├── models/           # Model configurations
│   ├── environment/      # Browser and OS tools
│   └── utils/            # Utility functions
├── examples/             # Example implementations
├── tests/                # Test suite
└── docs/                 # Documentation

Configuration Options

Environment Variables

Variable	Description	Default
`OPENAI_API_KEY`	OpenAI API key	Required*
`ANTHROPIC_API_KEY`	Anthropic API key	Required*
`GOOGLE_API_KEY`	Google AI API key	Required*
`HEADLESS`	Run browsers headlessly	`true`
`LOG_LEVEL`	Logging level	`INFO`
`MAX_RETRIES`	API retry attempts	`3`
`TIMEOUT`	Default timeout (seconds)	`300`

*At least one API key is required

Model Providers Setup

OpenRouter (Recommended):

ModelConfig(
    type="api",
    name="anthropic/claude-haiku-4.5",
    provider="openrouter",
    api_key=os.getenv("OPENROUTER_API_KEY")
)

OpenAI:

ModelConfig(
    type="api",
    name="anthropic/claude-sonnet-4.5",
    provider="openrouter",
    api_key=os.getenv("OPENROUTER_API_KEY"),
    max_tokens=12000
)

Anthropic:

ModelConfig(
    type="api",
    name="anthropic/claude-sonnet-4.5",
    provider="openrouter",
    api_key=os.getenv("OPENROUTER_API_KEY"),
    max_tokens=12000
)

Google:

ModelConfig(
    type="api",
    name="gemini-pro",
    provider="google",
    api_key=os.getenv("GOOGLE_API_KEY")
)

Local (Ollama):

ModelConfig(
    type="local",
    name="llama2",
    provider="ollama",
    base_url="http://localhost:11434"
)

Troubleshooting

Common Issues and Solutions

ImportError: No module named 'src'

Solution: Ensure you're in the project root and have installed MARSYS:

cd MARSYS
pip install -e .

API Key not found

Solution: Check your .env file is in the project root:

# Verify .env exists
ls -la .env

# Check environment variable
echo $OPENAI_API_KEY

Playwright browser not found

Solution: Install browser binaries:

playwright install chromium
# For all browsers
playwright install

Async syntax error

Solution: MARSYS requires Python 3.12+ for async support:

python --version  # Should be 3.12 or higher

Platform-Specific Issues

macOS:

For M1/M2 Macs, use Python 3.10+ for best compatibility
Install Rosetta 2 if needed: softwareupdate --install-rosetta

Windows:

Use PowerShell or WSL2 for best experience
Ensure long path support is enabled in Windows

Linux:

Install system dependencies for Playwright: playwright install-deps
On Ubuntu/Debian, you may need: sudo apt-get install python3-dev

Next Steps

Installation complete! Now you're ready to:

Need Help?

Check the FAQ
Report issues on GitHub
Join our Discord Community
Email support: support@marsys.ai

Ready to build?

Head to the Quick Start Guide to create your first multi-agent system!

Navigation