> ## Documentation Index
> Fetch the complete documentation index at: https://docs.run-agent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# runagent serve

> Start local FastAPI server with automatic agent deployment and database management

## Synopsis

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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:

<Steps>
  <Step title="Startup Animation">
    Displays robotic runner animation (customizable with `--animation-style`)
  </Step>

  <Step title="Capacity Check">
    Verifies database capacity (5 agents max) or handles replacement
  </Step>

  <Step title="Agent Registration">
    Registers agent in database with unique ID and allocated port
  </Step>

  <Step title="Server Start">
    Starts FastAPI server with automatic configuration
  </Step>
</Steps>

## 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

```bash theme={null}
curl http://localhost:8450/health
```

### Execute Agent

```bash theme={null}
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

```python theme={null}
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

```bash theme={null}
# 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`:

```json theme={null}
{
  "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

```bash theme={null}
# 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:

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
# 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

<AccordionGroup>
  <Accordion title="Database Capacity Issues">
    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Port Allocation Problems">
    The serve command handles port conflicts automatically:

    * Starts from port 8450
    * Increments if port is busy
    * Shows allocated address in output
    * Maximum 5 agents (ports 8450-8454)
  </Accordion>

  <Accordion title="Agent Configuration Errors">
    ```bash theme={null}
    # Validate configuration
    runagent serve . --debug

    # Check config file
    cat runagent.config.json | jq .

    # Verify framework detection
    runagent serve . --verbose
    ```
  </Accordion>

  <Accordion title="Import/Module Errors">
    ```bash theme={null}
    # Check entrypoint files exist
    ls -la main.py

    # Verify dependencies
    pip install -r requirements.txt

    # Test import manually
    python -c "from main import agent"
    ```
  </Accordion>
</AccordionGroup>

## Best Practices

1. **Monitor Capacity**: Regularly check `runagent db-status --capacity`
2. **Clean Up**: Remove unused agents to free database slots
3. **Use Replace**: When at capacity, replace oldest agents rather than failing
4. **Test Locally**: Always test with `serve` before remote deployment
5. **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

## See Also

* [`runagent run`](/cli/commands/run) - Execute deployed agents
* [`runagent db-status`](/cli/commands/db-status) - Check database status
* [`runagent delete`](/cli/commands/delete) - Remove agents
* [`runagent deploy`](/cli/commands/deploy) - Remote deployment (coming soon)
* [`runagent logs`](/cli/commands/logs) - View logs (coming soon)