​
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

OptionDescriptionDefault
--folderFolder containing agent filesCurrent directory
--local, -lDeploy locally (redirects to serve)false
--idAgent ID (for remote start only)None
--frameworkFramework type (auto-detected if not specified)Auto-detect
--configJSON configuration for deploymentNone

​
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

1

Authentication Setup

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

Agent Upload

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

Remote Start

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

Full Deployment

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

​
Local Deployment Process (Available Now)

Using runagent serve for local deployment:
1

Validation

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

Database Registration

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

Server Start

  • Starts FastAPI server
  • Configures endpoints
  • Enables real-time execution
4

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

# 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

# Validate agent structure
runagent serve . --verbose

# Check configuration
cat runagent.config.json | jq .
Local deployment automatically handles port allocation:
  • Starts from port 8450
  • Increments if port is busy
  • Maximum 5 agents (ports 8450-8454)

​
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

# 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

​
See Also