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

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

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

Everything you need for most use cases:

uv pip install marsys

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

Alternative Installation Methods

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

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.

# 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

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 authentication before running any examples. MARSYS needs at least one API provider configured, either via API keys or OAuth.

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)

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"

Security

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

OAuth Option (No API Keys)

If you want to use subscription-based OAuth providers instead of API keys, log in with the corresponding CLI:

OpenAI ChatGPT (OAuth): codex login - Credentials are stored in ~/.codex/auth.json (override with CODEX_AUTH_PATH)
Anthropic Claude Max (OAuth): claude login - Credentials are stored in ~/.claude/.credentials.json (override with CLAUDE_AUTH_PATH)

You can then set provider="openai-oauth" or provider="anthropic-oauth" in ModelConfig (optionally with oauth_profile="your-profile").

Use At Your Own Risk (Anthropic OAuth)

anthropic-oauth relies on a non-official integration path and may violate provider Terms of Service. Use at your own risk.

OpenAI OAuth Compliance

MARSYS does not make a legal determination about OpenAI ToS coverage for this OAuth path. Review OpenAI terms for your use case.

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-opus-4.6",
            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

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

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

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

Next Steps

Installation complete! Now you're ready to:

Quick Start

Build your first multi-agent system in 10 minutes

Create Your First Agent

Learn how to create custom agents with tools

Configuration Guide

Explore advanced configuration options

Need Help?

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