runagent serve

Synopsis

runagent serve [PATH] [OPTIONS]

Description

The serve command starts a local FastAPI server that automatically deploys your agent with database persistence, port allocation, and capacity management. It’s the primary command for local development and testing.

Options

Option	Description	Default
`--port`, `-p`	Preferred port (auto-allocated if unavailable)	Auto-allocated
`--host`, `-h`	Host to bind server to	`127.0.0.1`
`--debug`	Run server in debug mode	`false`
`--replace`	Replace existing agent with this agent ID	None
`--no-animation`	Skip startup animation	`false`
`--animation-style`	Animation style (field, ascii, minimal, quick)	`field`

Auto Port Allocation

The serve command automatically allocates ports starting from 8450:

Port Range: 8450-8454 (supports up to 5 agents)
Automatic Detection: Finds next available port if preferred port is busy
Conflict Resolution: Never conflicts with existing agents

# Uses auto-allocated port
runagent serve .
# Output: 🔌 Auto-allocated address: 127.0.0.1:8450

# Prefers specific port, falls back to auto-allocation
runagent serve . --port 8080
# Output: Using specified address: 127.0.0.1:8080

Database Integration

Each serve command automatically:

Registers agent in local SQLite database
Manages capacity (maximum 5 agents)
Persists deployments between restarts
Tracks usage statistics

Capacity Management

# Check current capacity
runagent db-status --capacity

# Replace oldest agent when at capacity
runagent serve . --replace oldest-agent-id

# Delete existing agent to free space
runagent delete --id agent-id

Examples

Basic Usage

# Serve current directory with auto port allocation
runagent serve .

# Serve specific project
runagent serve ~/projects/my-agent

# Use preferred port
runagent serve . --port 8080

Advanced Usage

# Replace existing agent
runagent serve . --replace a1b2c3d4-e5f6-7890

# Debug mode with verbose output
runagent serve . --debug

# Skip startup animation
runagent serve . --no-animation

# Quick startup animation
runagent serve . --animation-style quick

Startup Process

The serve command follows this process:

Startup Animation

Displays robotic runner animation (customizable with --animation-style)

Capacity Check

Verifies database capacity (5 agents max) or handles replacement

Agent Registration

Registers agent in database with unique ID and allocated port

Server Start

Starts FastAPI server with automatic configuration

Available Endpoints

Once running, your agent exposes these REST and WebSocket endpoints:

REST Endpoints

Endpoint	Method	Description
`/`	GET	Agent information and status
`/health`	GET	Health check
`/api/v1/agents/{agent_id}/run/{tag}`	POST	Execute agent entrypoint
`/docs`	GET	Interactive API documentation
`/redoc`	GET	Alternative API documentation

WebSocket Endpoints

Endpoint	Protocol	Description
`/api/v1/agents/{agent_id}/stream/{tag}`	WebSocket	Stream agent responses

Testing Your Agent

Health Check

curl http://localhost:8450/health

Execute Agent

curl -X POST http://localhost:8450/api/v1/agents/{agent_id}/run/main \
  -H "Content-Type: application/json" \
  -d '{
    "input_data": {
      "input_args": [],
      "input_kwargs": {"query": "Hello, agent!"}
    }
  }'

Using Python SDK

from runagent import RunAgentClient

# Connect to local agent
client = RunAgentClient(
    agent_id="your-agent-id", 
    entrypoint_tag="main",
    local=True
)

# Execute agent
result = client.run(query="Hello, agent!")
print(result)

Using CLI

# Execute local agent
runagent run --id agent-id --tag main --local --query="Hello"

Output Information

Successful Startup

🚀 Starting local server with auto port allocation...
🔌 Auto-allocated address: 127.0.0.1:8450
🌐 URL: http://127.0.0.1:8450
📖 Docs: http://127.0.0.1:8450/docs

✅ Agent started successfully!
🆔 Agent ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
📊 Capacity: 1/5 slots used

Capacity Warning

❌ Database is full!
💡 Suggested commands:
   Replace: runagent serve . --replace oldest-agent-id
   Delete:  runagent delete --id agent-id

Replacement Success

🔄 Replacing agent: old-agent-id
✅ Agent replaced successfully!
🆔 New Agent ID: new-agent-id
🔌 Address: 127.0.0.1:8451

Agent Configuration

The serve command reads from runagent.config.json:

{
  "agent_name": "my-agent",
  "description": "My awesome agent",
  "framework": "langgraph",
  "template": "basic",
  "version": "1.0.0",
  "agent_architecture": {
    "entrypoints": [
      {
        "file": "main.py",
        "module": "agent",
        "tag": "main"
      },
      {
        "file": "main.py", 
        "module": "agent_stream",
        "tag": "main_stream"
      }
    ]
  }
}

Development Features

Automatic Framework Detection

# Automatically detects framework from config
runagent serve .
# Output: Framework: langgraph

Database Persistence

Agent registrations persist between restarts
Usage statistics are tracked
Port allocations are remembered

Error Handling

Clear error messages for common issues:

# Missing configuration
❌ Validation error: No config file found

# Invalid entrypoint
❌ Validation error: Module 'agent' not found in main.py

# Capacity exceeded
❌ Database at capacity. Use --replace or 'runagent delete'

Integration with Other Commands

Database Management

# Check all local agents
runagent db-status

# View specific agent details
runagent db-status --agent-id your-agent-id

# Clean up agents
runagent delete --id agent-id

Execution

# Run agent locally
runagent run --id agent-id --tag main --local

# Use host/port directly
runagent run --host 127.0.0.1 --port 8450 --tag main

Animation Styles

Customize the startup animation:

# Default robotic runner in field
runagent serve .

# ASCII art version
runagent serve . --animation-style ascii

# Minimal clean version
runagent serve . --animation-style minimal

# Quick startup
runagent serve . --animation-style quick

# No animation
runagent serve . --no-animation

Troubleshooting

Database Capacity Issues

# Check current capacity
runagent db-status --capacity

# View all agents by age
runagent db-status

# Replace oldest agent
runagent serve . --replace oldest-agent-id

# Delete unused agents
runagent delete --id agent-id

Port Allocation Problems

Agent Configuration Errors

Import/Module Errors

Best Practices

Monitor Capacity: Regularly check runagent db-status --capacity
Clean Up: Remove unused agents to free database slots
Use Replace: When at capacity, replace oldest agents rather than failing
Test Locally: Always test with serve before remote deployment
Version Control: Keep runagent.config.json in version control

Performance Notes

Single Process: Each agent runs in a single FastAPI process
Port Per Agent: Each agent gets its own port for isolation
Database Tracking: Minimal overhead for registration and tracking
Auto Cleanup: Detect and handle stale agent registrations

CLI Reference

Synopsis

Description

Options

Auto Port Allocation

Database Integration

Capacity Management

Examples

Basic Usage

Advanced Usage

Startup Process

Available Endpoints

REST Endpoints

WebSocket Endpoints

Testing Your Agent

Health Check

Execute Agent

Using Python SDK

Using CLI

Output Information

Successful Startup

Capacity Warning

Replacement Success

Agent Configuration

Development Features

Automatic Framework Detection

Database Persistence

Error Handling

Integration with Other Commands

Database Management

Execution

Animation Styles

Troubleshooting

Best Practices

Performance Notes

See Also

CLI Reference

​Synopsis

​Description

​Options

​Auto Port Allocation

​Database Integration

​Capacity Management

​Examples

​Basic Usage

​Advanced Usage

​Startup Process

​Available Endpoints

​REST Endpoints

​WebSocket Endpoints

​Testing Your Agent

​Health Check

​Execute Agent

​Using Python SDK

​Using CLI

​Output Information

​Successful Startup

​Capacity Warning

​Replacement Success

​Agent Configuration

​Development Features

​Automatic Framework Detection

​Database Persistence

​Error Handling

​Integration with Other Commands

​Database Management

​Execution

​Animation Styles

​Troubleshooting

​Best Practices

​Performance Notes

​See Also

Synopsis

Description

Options

Auto Port Allocation

Database Integration

Capacity Management

Examples

Basic Usage

Advanced Usage

Startup Process

Available Endpoints

REST Endpoints

WebSocket Endpoints

Testing Your Agent

Health Check

Execute Agent

Using Python SDK

Using CLI

Output Information

Successful Startup

Capacity Warning

Replacement Success

Agent Configuration

Development Features

Automatic Framework Detection

Database Persistence

Error Handling

Integration with Other Commands

Database Management

Execution

Animation Styles

Troubleshooting

Best Practices

Performance Notes

See Also