Running Locally

Run the Pixell Agent Runtime (PAR) on your local machine for development, testing, and single-agent deployments. PAR supports both Three-Surface mode (single agent) and Multi-Agent mode (agent platform).

Prerequisites

• Python 3.11+ - Required for modern Python features
• pip - Python package installer
• APKG file - Agent package to run (optional for Multi-Agent mode)
• 2GB+ RAM - Recommended for optimal performance

Installation

Using pip (Recommended)

# Install PAR
pip install pixell-runtime

# Verify installation
pixell-runtime --version

Using Docker

# Pull the official PAR image
docker pull pixell/runtime:latest

# Run PAR container
docker run -p 8080:8080 -p 9090:9090 pixell/runtime:latest

From Source

# Clone the repository
git clone https://github.com/pixell-global/pixell.git
cd pixell/packages/runtime

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

Quick Start

Three-Surface Mode (Single Agent)

Run a single agent with all three communication surfaces:

# Run with an APKG file
pixell-runtime --package my-agent-0.1.0.apkg

# Run with environment variables
AGENT_PACKAGE_PATH=./my-agent-0.1.0.apkg pixell-runtime

Access points:

• 🌐 REST API: http://localhost:8080
• 🔗 A2A gRPC: localhost:8081
• 🎨 Web UI: http://localhost:8080/ui

Multi-Agent Mode (Agent Platform)

Run PAR as a platform for managing multiple agents:

# Run in Multi-Agent mode
pixell-runtime --mode multi-agent

# With custom configuration
pixell-runtime --mode multi-agent --max-agents 10

Access points:

• 🌐 Management API: http://localhost:8080
• 🔗 A2A gRPC: localhost:8081
• 📊 Admin Dashboard: http://localhost:9090

Configuration

Environment Variables

Set up your environment:

# .env file
# Runtime mode
RUNTIME_MODE=three-surface  # or multi-agent

# Server configuration
PORT=8080
ADMIN_PORT=9090
HOST=localhost

# Agent configuration (Three-Surface mode)
AGENT_PACKAGE_PATH=./my-agent-0.1.0.apkg

# Multi-Agent configuration
MAX_AGENTS=20
AGENT_STORAGE_PATH=./agents

# Logging
LOG_LEVEL=INFO
DEBUG=false

# Security
API_KEY=your-secret-key
CORS_ORIGINS=http://localhost:3000,http://localhost:8080

Configuration File

Create a par-config.yaml file:

# par-config.yaml
runtime:
  mode: three-surface  # or multi-agent
  host: localhost
  port: 8080
  admin_port: 9090

agent:
  package_path: ./my-agent-0.1.0.apkg
  max_agents: 20
  storage_path: ./agents

logging:
  level: INFO
  format: json
  file: ./logs/par.log

security:
  api_key: your-secret-key
  cors_origins:
    - http://localhost:3000
    - http://localhost:8080

performance:
  max_workers: 4
  timeout: 30
  memory_limit: 2GB

Running Examples

1. Basic Three-Surface Mode

# Create a simple agent package first
pixell init hello-agent
cd hello-agent
pixell build

# Run PAR with the agent
pixell-runtime --package ../hello-agent/dist/hello-agent-0.1.0.apkg

2. Multi-Agent Platform

# Start PAR in Multi-Agent mode
pixell-runtime --mode multi-agent --max-agents 10

# In another terminal, deploy agents
curl -X POST http://localhost:8080/agents \
  -H "Content-Type: application/json" \
  -d '{"name": "agent1", "package": "base64-encoded-apkg-data"}'

3. Development Mode

# Run with hot-reload for development
pixell-runtime --package my-agent.apkg --reload

# With debug logging
pixell-runtime --package my-agent.apkg --debug --log-level DEBUG

Command Line Options

Basic Options

Option	Description	Default
--package PATH	APKG file to run (Three-Surface mode)	Required
--mode MODE	Runtime mode: three-surface or multi-agent	three-surface
--port PORT	Main server port	8080
--admin-port PORT	Admin server port	9090
--host HOST	Server host	localhost

Advanced Options

Option	Description	Default
--max-agents N	Maximum agents (Multi-Agent mode)	20
--config FILE	Configuration file path	par-config.yaml
--log-level LEVEL	Logging level	INFO
--debug	Enable debug mode	false
--reload	Enable hot-reload	false

Examples

# Custom ports
pixell-runtime --package my-agent.apkg --port 3000 --admin-port 3001

# Debug mode
pixell-runtime --package my-agent.apkg --debug --log-level DEBUG

# Multi-Agent with custom limits
pixell-runtime --mode multi-agent --max-agents 50 --port 8080

# With configuration file
pixell-runtime --config ./my-par-config.yaml

Testing Your Setup

Health Check

# Check if PAR is running
curl http://localhost:8080/health

# Expected response
{
  "status": "healthy",
  "runtime": "three-surface",
  "version": "0.1.0",
  "uptime": "00:05:23"
}

Agent Status (Three-Surface Mode)

# Check agent status
curl http://localhost:8080/agent/status

# Expected response
{
  "agent": {
    "name": "my-agent",
    "version": "0.1.0",
    "status": "running",
    "capabilities": ["greeting", "conversation"]
  }
}

Platform Status (Multi-Agent Mode)

# Check platform status
curl http://localhost:8080/platform/status

# Expected response
{
  "platform": {
    "mode": "multi-agent",
    "max_agents": 20,
    "active_agents": 3,
    "status": "healthy"
  }
}

Development Workflow

1. Local Development

# Terminal 1: Start PAR
pixell-runtime --package my-agent.apkg --reload

# Terminal 2: Test the agent
curl -X POST http://localhost:8080/invoke \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, agent!"}'

2. Agent Development

# Build your agent
pixell build

# Run with PAR
pixell-runtime --package dist/my-agent-0.1.0.apkg

# Test A2A communication
python test_a2a_client.py

3. Multi-Agent Testing

# Start PAR platform
pixell-runtime --mode multi-agent

# Deploy multiple agents
for i in {1..5}; do
  curl -X POST http://localhost:8080/agents \
    -H "Content-Type: application/json" \
    -d "{\"name\": \"agent-$i\", \"package\": \"$(base64 -w 0 agent-$i.apkg)\"}"
done

Troubleshooting

Common Issues

1. Port Already in Use

Error: Address already in use: Port 8080

Solution:

# Use different port
pixell-runtime --package my-agent.apkg --port 3000

# Or kill existing process
lsof -ti:8080 | xargs kill -9
pixell-runtime --package my-agent.apkg

2. APKG File Not Found

Error: Package file not found: my-agent.apkg

Solution:

# Check file exists
ls -la my-agent.apkg

# Use absolute path
pixell-runtime --package /full/path/to/my-agent.apkg

# Or navigate to correct directory
cd /path/to/agent
pixell-runtime --package my-agent.apkg

3. Permission Denied

Error: Permission denied: Cannot access package file

Solution:

# Check file permissions
ls -la my-agent.apkg

# Fix permissions
chmod 644 my-agent.apkg

# Or run with sudo (not recommended)
sudo pixell-runtime --package my-agent.apkg

4. Memory Issues

Error: Out of memory or slow performance

Solution:

# Reduce max agents
pixell-runtime --mode multi-agent --max-agents 5

# Increase system memory
# Or use a more powerful machine

Debug Mode

Enable detailed debugging:

# Debug mode with verbose logging
pixell-runtime --package my-agent.apkg --debug --log-level DEBUG

# Check logs
tail -f logs/par.log

Performance Monitoring

# Monitor resource usage
htop

# Check PAR process
ps aux | grep pixell-runtime

# Monitor network connections
netstat -tulpn | grep 8080

Production Considerations

Security

# Use API keys
pixell-runtime --package my-agent.apkg --api-key your-secret-key

# Enable CORS restrictions
pixell-runtime --package my-agent.apkg --cors-origins https://yourdomain.com

# Use HTTPS (with reverse proxy)
# PAR doesn't handle SSL directly

Performance

# Optimize for production
pixell-runtime --package my-agent.apkg \
  --max-workers 4 \
  --timeout 30 \
  --memory-limit 2GB

Monitoring

# Enable metrics
pixell-runtime --package my-agent.apkg --metrics

# Access metrics
curl http://localhost:8080/metrics

Next Steps

After running PAR locally:

1. Configuration - Learn advanced configuration options
2. REST Endpoints - Explore the REST API
3. gRPC Interface - Use A2A communication
4. Deployment - Deploy to production

---

Ready to configure PAR? Check out Configuration to learn about advanced setup options!