Skip to main content

Local Development

This guide explains how to run AxonFlow locally for development, testing, and single-tenant deployments.

SELF_HOSTED_MODE​

For local development and single-tenant deployments, AxonFlow provides SELF_HOSTED_MODE which bypasses license validation entirely.

When to Use SELF_HOSTED_MODE​

ScenarioUse SELF_HOSTED_MODE?
Local development✅ Yes
Unit testing✅ Yes
Integration testing✅ Yes
Single-tenant internal deployment✅ Yes
Multi-tenant SaaS❌ No
Production with external clients❌ No

Enabling SELF_HOSTED_MODE​

Set the environment variable before starting AxonFlow:

export SELF_HOSTED_MODE=true

Or in your docker-compose.yml:

services:
  agent:
    environment:
      - SELF_HOSTED_MODE=true

What Happens When Enabled​

When SELF_HOSTED_MODE=true:

  1. License validation is skipped - No license key required
  2. All requests are allowed - No authentication needed
  3. Full connector access - All MCP connectors available
  4. No tenant isolation - All requests treated as same tenant

Quick Start with Docker Compose​

# Clone AxonFlow
git clone https://github.com/getaxonflow/axonflow.git
cd axonflow

# Set API key for LLM features (optional)
export OPENAI_API_KEY=sk-your-key-here

# Start all services (SELF_HOSTED_MODE enabled by default)
docker-compose up -d

# Check services are healthy
docker-compose ps

# Test the agent health
curl http://localhost:8080/health

# Run the interactive demo
./platform/examples/demo/demo.sh

# Access Grafana dashboards (optional)
open http://localhost:3000

The Docker Compose setup enables SELF_HOSTED_MODE by default, so you don't need to set it manually.

Services Available:

Security Considerations​

⚠️ Important: SELF_HOSTED_MODE should only be used when:

  • Running locally for development
  • Running in a trusted network environment
  • All applications connecting to AxonFlow are trusted

Never use in production multi-tenant environments - use proper license keys instead.

Running Tests​

With SELF_HOSTED_MODE enabled, you can run the full test suite:

# Run all tests
go test ./...

# Run with coverage
go test -cover ./...

# Run specific module
go test ./platform/agent/...

Local Architecture​

┌──────────────────────────────────────────────────┐
│               Your Development Machine            │
│                                                  │
│  ┌─────────────────────────────────────────────┐ │
│  │           docker-compose                     │ │
│  │                                              │ │
│  │  ┌────────┐  ┌──────────────┐  ┌────────┐  │ │
│  │  │ Agent  │◄►│ Orchestrator │◄►│  MCP   │  │ │
│  │  │ :8080  │  │    :8081     │  │        │  │ │
│  │  └────────┘  └──────────────┘  └────────┘  │ │
│  │       │                                     │ │
│  │       ▼                                     │ │
│  │  ┌───────────────────┐                     │ │
│  │  │   PostgreSQL      │                     │ │
│  │  │      :5432        │                     │ │
│  │  └───────────────────┘                     │ │
│  └─────────────────────────────────────────────┘ │
│                                                  │
│         SELF_HOSTED_MODE=true                    │
│         (No license validation)                  │
└──────────────────────────────────────────────────┘

Transitioning to Production​

When you're ready to move from local development to production:

  1. SaaS Multi-Tenant: Contact [email protected] for service licenses
  2. In-VPC Single-Tenant: Keep SELF_HOSTED_MODE if all apps are trusted, or use licenses for external apps
  3. AWS Marketplace: Follow the AWS Marketplace deployment guide

See the Enterprise License Management documentation for detailed licensing information.

Troubleshooting​

"License validation failed" Error​

If you see this error during local development:

License validation failed: license key required

Solution: Ensure SELF_HOSTED_MODE=true is set:

export SELF_HOSTED_MODE=true
# Then restart AxonFlow

Container Can't Connect to Database​

If the agent can't connect to PostgreSQL:

# Check if PostgreSQL is running
docker-compose ps

# View PostgreSQL logs
docker-compose logs postgres

# Restart all services
docker-compose down && docker-compose up

Port Already in Use​

If ports 8080, 8081, or 5432 are already in use:

# Find what's using the port
lsof -i :8080

# Or use different ports in docker-compose.yml
ports:
  - "9080:8080"  # Map to 9080 instead