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
--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
- 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
- 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
See Also
