runagent deploy

Synopsis

runagent deploy [OPTIONS] [PATH]

Description

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

Note: Remote deployment features require authentication and are coming soon. Local deployment is fully available through the serve command.

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:

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

# 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

Authentication Setup

# Setup API credentials (Coming Soon)
runagent setup --api-key your-api-key

Agent Upload

# Upload agent code (Coming Soon)
runagent upload --folder .

Remote Start

# Start on remote server (Coming Soon)
runagent start --id AGENT_ID

Full Deployment

# Combined upload + start (Coming Soon)
runagent deploy --folder .

Local Deployment Process (Available Now)

Using runagent serve for local deployment:

Validation

Checks runagent.config.json
Validates entrypoints and framework
Verifies agent structure

Database Registration

Registers agent in local database
Allocates unique port automatically
Handles capacity management (5 agents max)

Server Start

Starts FastAPI server
Configures endpoints
Enables real-time execution

Ready for Use

Agent available at local endpoint
Can execute via Python SDK or CLI

Examples

Current Local Deployment

# 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

# Local deployment (redirects to serve)
runagent deploy --folder . --local

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

Future Remote Examples (Coming Soon)

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

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

{
  "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)

{
  "deployment": {
    "memory": "512MB",
    "timeout": 30,
    "min_instances": 1,
    "max_instances": 10,
    "environment_variables": {
      "LOG_LEVEL": "INFO"
    }
  }
}

Validation Checks

Before deployment, RunAgent validates:

Error Handling

Common Local Deployment Errors

# 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

Local Deployment Issues

# 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

Configuration Errors

# Validate agent structure
runagent serve . --verbose

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

Port Conflicts

Local deployment automatically handles port allocation:

Starts from port 8450
Increments if port is busy
Maximum 5 agents (ports 8450-8454)

Best Practices

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

Migration Guide

Current Workflow

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

# 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

Reference

API Reference

SDK Reference

CLI Reference

Configuration

Synopsis

Description

Options

Current Usage

Local Deployment

Coming Soon: Remote Deployment

Remote Deployment Workflow (Coming Soon)

Planned Remote Features

Local Deployment Process (Available Now)

Examples

Current Local Deployment

Local Deployment via Deploy Command

Future Remote Examples (Coming Soon)

Output

Local Deployment Output

Future Remote Deployment Output (Coming Soon)

Local Database Management

Configuration

Agent Configuration

Future Remote Configuration (Coming Soon)

Validation Checks

Error Handling

Common Local Deployment Errors

Troubleshooting

Best Practices

Migration Guide

Current Workflow

Future Remote Workflow (Coming Soon)

See Also

​Synopsis

​Description

​Options

​Current Usage

​Local Deployment

​Coming Soon: Remote Deployment

​Remote Deployment Workflow (Coming Soon)

​Planned Remote Features

​Local Deployment Process (Available Now)

​Examples

​Current Local Deployment

​Local Deployment via Deploy Command

​Future Remote Examples (Coming Soon)

​Output

​Local Deployment Output

​Future Remote Deployment Output (Coming Soon)

​Local Database Management

​Configuration

​Agent Configuration

​Future Remote Configuration (Coming Soon)

​Validation Checks

​Error Handling

​Common Local Deployment Errors

​Troubleshooting

​Best Practices

​Migration Guide

​Current Workflow

​Future Remote Workflow (Coming Soon)

​See Also

Synopsis

Description

Options

Current Usage

Local Deployment

Coming Soon: Remote Deployment

Remote Deployment Workflow (Coming Soon)

Planned Remote Features

Local Deployment Process (Available Now)

Examples

Current Local Deployment

Local Deployment via Deploy Command

Future Remote Examples (Coming Soon)

Output

Local Deployment Output

Future Remote Deployment Output (Coming Soon)

Local Database Management

Configuration

Agent Configuration

Future Remote Configuration (Coming Soon)

Validation Checks

Error Handling

Common Local Deployment Errors

Troubleshooting

Best Practices

Migration Guide

Current Workflow

Future Remote Workflow (Coming Soon)

See Also