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

# Cloud Deployment

> Deploy agents to RunAgent cloud infrastructure

Deploy agents to RunAgent cloud infrastructure for production use with automatic scaling, monitoring, and global availability.

## Prerequisites

Before deploying to the cloud, you need:

1. **RunAgent Account** - Sign up at [run-agent.ai](https://run-agent.ai)
2. **API Key** - Get your API key from the dashboard
3. **Configured CLI** - Authenticate your CLI with your API key

## Authentication Setup

Configure your CLI with your API key:

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

# Verify configuration
runagent setup --api-key <your-api-key>
```

The setup command will:

* Validate your API key with the RunAgent middleware
* Store credentials securely in `~/.runagent/config.json`
* Display your account information and tier
* Show middleware sync status

### Teardown Configuration

Remove stored credentials:

```bash theme={null}
runagent teardown
```

## Deployment Methods

### Method 1: Quick Deploy (Upload + Start)

Deploy your agent in a single command:

```bash theme={null}
# Deploy to cloud (combines upload + start)
runagent deploy --folder <agent-folder>

# Example
runagent deploy --folder ./my-agent
```

This command will:

1. Validate your agent configuration
2. Upload agent code and metadata to the cloud
3. Start the agent automatically
4. Return the deployment endpoint

**Output:**

```
✅ Full deployment successful!
🆔 Agent ID: abc-123-def-456
🌐 Endpoint: https://api.run-agent.ai/api/v1/agents/abc-123-def-456
```

### Method 2: Two-Step Deploy (Upload Then Start)

For more control, upload and start separately:

#### Step 1: Upload Agent

```bash theme={null}
# Upload agent to cloud
runagent upload --folder <agent-folder>

# Specify framework explicitly (optional)
runagent upload --folder <agent-folder> --framework langgraph
```

**Upload Process:**

1. Agent validation (checks for required files)
2. Fingerprint generation (for duplicate detection)
3. Metadata upload (config + entrypoints)
4. Source code packaging and upload
5. Local database tracking

**Output:**

```
📤 Uploading agent from: ./my-agent
🔍 Validating agent...
✅ Agent validation passed
📋 Agent config loaded successfully
🔍 Agent fingerprint: a1b2c3d4...

📦 Uploading to: https://api.run-agent.ai/api/v1
🌐 Uploading agent metadata...
   Metadata uploaded successfully
📦 Creating upload package...
   Created upload package: agent_abc12345.zip
   Uploading agent_abc12345.zip (1,234,567 bytes)...
   Processing upload...
   Upload completed!

✅ Upload successful!
🆔 Agent ID: abc-123-def-456
🌐 Server: https://api.run-agent.ai/api/v1
🔍 Fingerprint: a1b2c3d4...

💡 Next step: runagent start --id abc-123-def-456
```

#### Step 2: Start Agent

```bash theme={null}
# Start uploaded agent
runagent start --id <agent-id>

# With custom configuration
runagent start --id <agent-id> --config '{"env": "production"}'
```

**Output:**

```
Starting agent: abc-123-def-456

✅ Agent started successfully!
🆔 Agent ID: abc-123-def-456
🌐 Endpoint: https://api.run-agent.ai/api/v1/agents/abc-123-def-456/execute
```

## Agent Configuration

### Agent ID and Entrypoints

When you initialize a new agent with `runagent init`, it automatically:

1. **Generates a unique agent ID** and adds it to `runagent.config.json`
2. **Creates a basic configuration** with framework and template settings

**Important:** You must add your entrypoints to the configuration file before deploying.

#### Using `runagent init` (Recommended)

```bash theme={null}
# Initialize a new agent
runagent init my-agent --framework langgraph

# This creates runagent.config.json with:
# - Generated agent_id
# - Framework configuration
# - Empty entrypoints array (you need to add these)
```

**Example `runagent.config.json` after init:**

```json theme={null}
{
  "agent_name": "my-agent",
  "agent_id": "abc-123-def-456",
  "version": "1.0.0",
  "framework": "langgraph",
  "agent_architecture": {
    "entrypoints": []  // ← You need to add entrypoints here
  }
}
```

**Add your entrypoints:**

```json theme={null}
{
  "agent_name": "my-agent",
  "agent_id": "abc-123-def-456",
  "version": "1.0.0",
  "framework": "langgraph",
  "agent_architecture": {
    "entrypoints": [
      {
        "tag": "chat",
        "file": "main.py",
        "module": "chat_agent"
      },
      {
        "tag": "chat_stream",
        "file": "main.py",
        "module": "chat_agent_stream"
      }
    ]
  }
}
```

#### Manually Editing Agent ID

If you manually edit the `agent_id` in `runagent.config.json`, you **must register** the agent:

```bash theme={null}
# Register the agent after manually editing agent_id
runagent register .

# Or use the config command
runagent config --register-agent .
```

<Warning>
  **Important:** If you manually change the `agent_id` in your config file, RunAgent won't recognize it until you register it. Always run `runagent register .` after manually editing the agent ID.
</Warning>

## Agent Validation

Before upload, RunAgent validates your agent:

### Required Files

* `runagent.config.json` - Agent configuration with valid `agent_id` and `entrypoints`
* `main.py` or `agent.py` - Entry point file
* `requirements.txt` - Python dependencies (optional)

### Validation Checks

* ✅ Configuration file exists and is valid JSON
* ✅ Agent ID exists in configuration
* ✅ Agent ID is registered (if manually edited)
* ✅ Entry point file exists
* ✅ Entrypoints are properly defined
* ✅ Framework is supported
* ✅ No syntax errors in configuration

**Example Valid Configuration:**

```json theme={null}
{
  "agent_name": "my-agent",
  "agent_id": "abc-123-def-456",
  "version": "1.0.0",
  "framework": "langgraph",
  "agent_architecture": {
    "entrypoints": [
      {
        "tag": "chat",
        "file": "main.py",
        "module": "agent.chat"
      }
    ]
  }
}
```

## Duplicate Detection

RunAgent uses fingerprinting to detect duplicate agents:

### How It Works

1. **Fingerprint Generation**: Creates a unique hash of your agent's content
2. **Duplicate Check**: Compares with existing agents in your account
3. **User Prompt**: If duplicate found, asks whether to overwrite or create new

**Example Scenarios:**

**Scenario 1: Identical Content**

```
⚠️ Agent with identical content already exists!
🆔 Existing Agent ID: abc-123-def-456
📊 Status: deployed
📍 Type: Remote

Do you want to overwrite the existing agent? [y/N]: 
```

**Scenario 2: Modified Content**

```
⚠️ Agent content has changed!
🆔 Existing Agent ID: abc-123-def-456
📊 Status: deployed
📍 Type: Remote
🔍 Content fingerprint changed (modified files detected)

What would you like to do?
  [overwrite] - Overwrite existing agent (coming soon)
  [new] - Create new agent
  [cancel] - Cancel upload
```

## Running Cloud Agents

Execute your deployed agents:

### Basic Execution

```bash theme={null}
# Run with entrypoint tag
runagent run --id <agent-id> --tag <entrypoint> --param1=value1 --param2=value2

# Examples
runagent run --id abc-123 --tag chat --message="Hello"
runagent run --id abc-123 --tag process --data='{"key": "value"}'
```

### Using Input Files

```bash theme={null}
# Run with JSON input file
runagent run --id <agent-id> --tag <entrypoint> --input config.json
```

**Example input.json:**

```json theme={null}
{
  "message": "Hello, world!",
  "config": {
    "temperature": 0.7,
    "max_tokens": 100
  }
}
```

### Streaming Execution

For streaming entrypoints (must end with `_stream`):

```bash theme={null}
# Run streaming endpoint using run-stream command
runagent run-stream --id <agent-id> --tag chat_stream --message="Tell me a story"

# Or with local agent
runagent run-stream --id <agent-id> --tag chat_stream --local --message="Tell me a story"
```

<Note>
  **Important:** Use `runagent run-stream` (not `runagent run`) for streaming execution. The `run-stream` command uses WebSocket connections for real-time streaming.
</Note>

## Cloud vs Local Deployment

| Feature            | Local            | Cloud                     |
| ------------------ | ---------------- | ------------------------- |
| **Setup**          | `runagent serve` | `runagent deploy`         |
| **Infrastructure** | Your machine     | RunAgent cloud            |
| **Scaling**        | Manual           | Automatic                 |
| **Uptime**         | While running    | 24/7                      |
| **Monitoring**     | Local logs only  | Full monitoring dashboard |
| **URL**            | localhost:port   | Global endpoint           |
| **Authentication** | None             | API key required          |
| **Cost**           | Free             | Usage-based pricing       |

## Deployment Workflow

### Complete Example

```bash theme={null}
# 1. Create and test agent locally
runagent init my-agent --framework langgraph --template default
cd my-agent

# 2. Add entrypoints to runagent.config.json
# Edit the file and add your entrypoints to agent_architecture.entrypoints

# 3. If you manually edited agent_id, register it
runagent register .

# 4. Test locally
runagent serve

# 5. Authenticate (if not already done)
runagent setup --api-key <your-key>

# 6. Deploy to cloud
runagent deploy --folder .

# 7. Test cloud deployment
runagent run --id <agent-id> --tag chat --message="Hello"
```

### CI/CD Integration

#### GitHub Actions

```yaml theme={null}
name: Deploy to RunAgent Cloud

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'
      
      - name: Install RunAgent
        run: pip install runagent
      
      - name: Deploy Agent
        env:
          RUNAGENT_API_KEY: ${{ secrets.RUNAGENT_API_KEY }}
        run: |
          runagent setup --api-key $RUNAGENT_API_KEY
          runagent deploy --folder .
```

#### GitLab CI

```yaml theme={null}
deploy:
  stage: deploy
  image: python:3.9
  
  script:
    - pip install runagent
    - runagent setup --api-key $RUNAGENT_API_KEY
    - runagent deploy --folder .
  
  only:
    - main
```

## Monitoring and Management

### View Agent Status

```bash theme={null}
# Check if agent is running
runagent start --id <agent-id>
```

### Local Deployment Info

Deployment information is saved locally in `.deployments/`:

```json theme={null}
{
  "agent_id": "abc-123-def-456",
  "remote": true,
  "base_url": "https://api.run-agent.ai/api/v1",
  "fingerprint": "a1b2c3d4...",
  "source_folder": "/path/to/my-agent",
  "saved_at": "2025-01-15 10:30:00",
  "client_version": "1.0"
}
```

## Troubleshooting

### Authentication Errors

**Error:** `Not authenticated. Run 'runagent setup --api-key <key>' first`

**Solution:**

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

# Verify setup worked
runagent setup --api-key <your-api-key>
```

### Upload Failures

**Error:** `Agent validation failed`

**Solution:**

1. Check that `runagent.config.json` exists and is valid
2. Verify entry point file exists (`main.py` or `agent.py`)
3. Ensure all required dependencies are in `requirements.txt`
4. Run `runagent serve` locally to test first

**Error:** `Failed to upload agent: HTTP 413`

**Solution:** Your agent folder is too large. Remove unnecessary files:

* Remove `__pycache__` directories
* Remove `.pyc` files
* Remove large data files (use cloud storage instead)
* Add `.gitignore` patterns to exclude files

### Deployment Fails But Upload Succeeds

**Error:** `Upload succeeded but start failed`

**Solution:**

```bash theme={null}
# Agent is uploaded, just needs to be started
runagent start --id <agent-id>
```

### Connection Issues

**Error:** `Cannot connect to middleware server`

**Solution:**

1. Check your internet connection
2. Verify the base URL is correct
3. Check if middleware server is accessible
4. Try with explicit base URL: `runagent setup --api-key <key> --base-url https://api.run-agent.ai`

## Best Practices

### 1. Test Locally First

Always test your agent locally before deploying:

```bash theme={null}
# Test locally
runagent serve
runagent run --id <local-agent-id> --tag chat --local --message="test"

# Deploy after successful local testing
runagent deploy --folder .
```

### 2. Version Control

Include deployment info in version control:

```bash theme={null}
# Add to .gitignore
.deployments/*.json
.runagent/

# But track your agent code
git add runagent.config.json main.py requirements.txt
git commit -m "feat: add chat agent"
```

### 3. Environment Variables

Use environment variables for sensitive data:

```json theme={null}
{
  "env_vars": {
    "OPENAI_API_KEY": "${OPENAI_API_KEY}",
    "DATABASE_URL": "${DATABASE_URL}"
  }
}
```

Set them before deploying:

```bash theme={null}
export OPENAI_API_KEY="sk-..."
runagent deploy --folder .
```

### 4. Incremental Updates

For agent updates:

```bash theme={null}
# Upload new version
runagent upload --folder .

# Test before switching
runagent run --id <new-agent-id> --tag chat --message="test"

# If good, can use new agent ID
```

### 5. Monitor Performance

After deployment:

* Test all entrypoints
* Check response times
* Verify outputs are correct
* Monitor error rates

## Security

### API Key Management

**Best Practices:**

* ✅ Store API keys in environment variables
* ✅ Use different keys for development and production
* ✅ Rotate keys regularly
* ✅ Never commit API keys to version control
* ❌ Don't share API keys
* ❌ Don't hardcode keys in agent code

### Secure Deployment

```bash theme={null}
# Use environment variables
export RUNAGENT_API_KEY="your-key"
runagent deploy --folder .

# Or use secure config file
runagent setup --api-key $RUNAGENT_API_KEY
```

## Limits and Quotas

### Free Tier

* 5 local agents
* Cloud deployment available
* Standard execution limits

### Enhanced Limits

Contact sales for:

* Unlimited local agents
* Higher execution limits
* Priority support
* Custom SLAs

Check your current limits:

```bash theme={null}
runagent db status --capacity
```

## Next Steps

* [RunAgent Cloud Overview](/runagent-cloud/overview) - Learn about RunAgent Cloud infrastructure
* [Local Development](/deployment/local-development) - Test agents locally
* [SDK Overview](/sdk/overview) - Use Python SDK for deployment
* [API Reference](/api-reference) - Direct API access
* [Monitoring Guide](/explanation/production-considerations) - Track agent performance

## Support

Need help with cloud deployment?

* 📖 [Documentation](https://docs.run-agent.ai)
* 💬 [Discord Community](https://discord.gg/runagent)
* 📧 [Email Support](mailto:support@run-agent.ai)
* 🐛 [Report Issues](https://github.com/runagent/runagent/issues)