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

> Deploy agent locally or to remote server (remote coming soon)

## Synopsis

```bash theme={null}
runagent deploy [OPTIONS] [PATH]
```

## Description

The `deploy` command handles agent deployment workflows. Currently supports local deployment, with remote cloud deployment coming soon.

<Info>
  **Note:** Remote deployment features require authentication and are coming soon. Local deployment is fully available through the `serve` command.
</Info>

## Options

| Option          | Description                                     | Default           |
| --------------- | ----------------------------------------------- | ----------------- |
| `--folder`      | Folder containing agent files                   | Current directory |
| `--local`, `-l` | Deploy locally (redirects to serve)             | `false`           |
| `--id`          | Agent ID (for remote start only)                | None              |
| `--framework`   | Framework type (auto-detected if not specified) | Auto-detect       |
| `--config`      | JSON configuration for deployment               | None              |

## Current Usage

### Local Deployment

For local deployment, use the `serve` command directly:

```bash theme={null}
# Start local development server (recommended)
runagent serve .

# Or use deploy with --local flag (redirects to serve)
runagent deploy --folder . --local
```

The `--local` option internally calls the `serve` command with automatic:

* Port allocation
* Database management
* Agent registration

## Coming Soon: Remote Deployment

### Remote Deployment Workflow (Coming Soon)

```bash theme={null}
# Upload agent to remote server (Coming Soon)
runagent upload --folder .

# Start uploaded agent (Coming Soon)
runagent start --id AGENT_ID

# Full deployment workflow (Coming Soon)
runagent deploy --folder .
```

### Planned Remote Features

<Steps>
  <Step title="Authentication Setup">
    ```bash theme={null}
    # Setup API credentials (Coming Soon)
    runagent setup --api-key your-api-key
    ```
  </Step>

  <Step title="Agent Upload">
    ```bash theme={null}
    # Upload agent code (Coming Soon)
    runagent upload --folder .
    ```
  </Step>

  <Step title="Remote Start">
    ```bash theme={null}
    # Start on remote server (Coming Soon)
    runagent start --id AGENT_ID
    ```
  </Step>

  <Step title="Full Deployment">
    ```bash theme={null}
    # Combined upload + start (Coming Soon)
    runagent deploy --folder .
    ```
  </Step>
</Steps>

## Local Deployment Process (Available Now)

Using `runagent serve` for local deployment:

<Steps>
  <Step title="Validation">
    * Checks `runagent.config.json`
    * Validates entrypoints and framework
    * Verifies agent structure
  </Step>

  <Step title="Database Registration">
    * Registers agent in local database
    * Allocates unique port automatically
    * Handles capacity management (5 agents max)
  </Step>

  <Step title="Server Start">
    * Starts FastAPI server
    * Configures endpoints
    * Enables real-time execution
  </Step>

  <Step title="Ready for Use">
    * Agent available at local endpoint
    * Can execute via Python SDK or CLI
  </Step>
</Steps>

## Examples

### Current Local Deployment

```bash theme={null}
# Basic local deployment
runagent serve .

# With custom port
runagent serve . --port 8080

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

# With animation disabled
runagent serve . --no-animation
```

### Local Deployment via Deploy Command

```bash theme={null}
# Local deployment (redirects to serve)
runagent deploy --folder . --local

# With framework specification
runagent deploy --folder . --local --framework langgraph
```

### Future Remote Examples (Coming Soon)

```bash theme={null}
# Full remote deployment (Coming Soon)
runagent deploy --folder .

# With custom configuration (Coming Soon)
runagent deploy --folder . --config '{"memory": "1GB", "timeout": 60}'

# Deploy specific agent (Coming Soon)
runagent deploy --id existing-agent-id
```

## Output

### Local Deployment Output

```
🚀 RunAgent Configuration:
   Agent ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
   Local: Yes
   Tag: main

🔌 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!
```

### Future Remote Deployment Output (Coming Soon)

```
Validating agent configuration... ✓
Uploading agent files... ✓
Starting remote deployment... ✓
Initializing endpoints... ✓

Deployment successful!
Agent ID: 055b73d7-6239-4a94-a156-1193fcf33ff0
Status: Running
Endpoint: https://api.run-agent.ai/agents/055b73d7

To test your agent:
  runagent run --id 055b73d7 --tag main --input '{"query": "test"}'
```

## Local Database Management

Local deployments are managed through a SQLite database:

```bash theme={null}
# Check local agent status
runagent db-status

# View capacity information
runagent db-status --capacity

# Delete local agent
runagent delete --id agent-id
```

**Capacity Limits:**

* Maximum 5 agents simultaneously
* Automatic port allocation (8450-8454)
* Replace oldest agent when at capacity

## Configuration

### Agent Configuration

In `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"
      }
    ]
  }
}
```

### Future Remote Configuration (Coming Soon)

```json theme={null}
{
  "deployment": {
    "memory": "512MB",
    "timeout": 30,
    "min_instances": 1,
    "max_instances": 10,
    "environment_variables": {
      "LOG_LEVEL": "INFO"
    }
  }
}
```

## Validation Checks

Before deployment, RunAgent validates:

<Checklist>
  * Configuration file exists and is valid JSON
  * Required fields are present in config
  * Entrypoint files exist
  * Framework is supported
  * Agent structure is valid
  * No syntax errors in configuration
</Checklist>

## Error Handling

### Common Local Deployment Errors

```bash theme={null}
# Database at capacity
❌ Database is full!
💡 Suggested commands:
   Replace: runagent serve . --replace oldest-agent-id
   Delete:  runagent delete --id agent-id

# Port already in use
🔌 Auto-allocated address: 127.0.0.1:8451

# Invalid configuration
❌ Validation error: Missing required field 'agent_name'
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Local Deployment Issues">
    ```bash theme={null}
    # Check database status
    runagent db-status

    # Check specific agent
    runagent db-status --agent-id AGENT_ID

    # Clean up old agents
    runagent delete --id AGENT_ID
    ```
  </Accordion>

  <Accordion title="Configuration Errors">
    ```bash theme={null}
    # Validate agent structure
    runagent serve . --verbose

    # Check configuration
    cat runagent.config.json | jq .
    ```
  </Accordion>

  <Accordion title="Port Conflicts">
    Local deployment automatically handles port allocation:

    * Starts from port 8450
    * Increments if port is busy
    * Maximum 5 agents (ports 8450-8454)
  </Accordion>
</AccordionGroup>

## Best Practices

1. **Test with Serve**: Always use `runagent serve` for local development
2. **Monitor Capacity**: Check `runagent db-status --capacity` regularly
3. **Clean Up**: Remove unused agents with `runagent delete`
4. **Version Control**: Keep `runagent.config.json` in version control
5. **Environment Setup**: Configure `.env` files properly

## Migration Guide

### Current Workflow

```bash theme={null}
# 1. Create agent
runagent init my-agent --framework langgraph

# 2. Develop locally
runagent serve .

# 3. Test execution
runagent run --id agent-id --tag main --local
```

### Future Remote Workflow (Coming Soon)

```bash theme={null}
# 1. Setup authentication
runagent setup --api-key your-key

# 2. Deploy remotely
runagent deploy --folder .

# 3. Test execution
runagent run --id agent-id --tag main
```

## See Also

* [`runagent serve`](/cli/commands/serve) - Local development server (recommended)
* [`runagent upload`](/cli/commands/upload) - Upload agent to remote (coming soon)
* [`runagent start`](/cli/commands/start) - Start remote agent (coming soon)
* [`runagent db-status`](/cli/commands/db-status) - Check local database
* [`runagent run`](/cli/commands/run) - Execute agents