Agent Deployment

Configure where and how this agent runs — cloud providers, Docker, VPS, local process management, knowledge bases, and lifecycle controls.

Overview

How It Works

1. Configure — Click "Edit" on the Deployment Status card. Select a target platform and fill in the required credentials and settings.
2. Save — Save the deployment configuration. This doesn't deploy — it just stores the config.
3. Deploy — Click "Deploy" to initiate the deployment process. The agent starts on the configured target.
4. Monitor — The status card shows state (running, stopped, error), health, uptime, endpoint URL, and deployment details.
5. Control — Use Stop, Restart, or Deploy buttons to manage the agent's lifecycle.

Key Concepts

Deployment Targets

Eight deployment targets are supported, each with platform-specific configuration:

Fly.io

Recommended for quick deployments. Configure:

• API Token — From fly.io/user/personal_access_tokens.
• App Name — Auto-generated if empty.
• Organization — Fly.io org (default: "personal").
• VM Size — From Shared 1x ($1.94/mo) to Performance 8x ($232.36/mo).
• Region — 18 global regions with city names and codes.

AWS EC2

Full cloud deployment on Amazon Web Services:

• Credentials — Access Key ID and Secret Access Key.
• Region — 12 AWS regions from US East to South Africa.
• Instance Type — From t3.micro ($7.59/mo) to c5.xlarge ($122.40/mo).
• Optional — AMI ID, Subnet ID, Security Group, Key Pair Name.

Google Cloud GCE

• Project ID and Service Account Key (JSON).
• Region/Zone — 11 regions from US Central to South America.
• Machine Type — From e2-micro ($6.11/mo) to c2-standard-4 ($124.49/mo).

Microsoft Azure

• Subscription ID and Resource Group.
• Region — 15 regions globally.
• VM Size — From Standard_B1s ($7.59/mo) to Standard_E2s_v5 ($91.98/mo).
• Optional — Tenant ID, Client ID, Client Secret for service principal auth.

Railway

• API Token — From railway.app/account/tokens.
• Project ID — Auto-created if empty.
• Service Name — Name for the Railway service.

Docker

• Image — Docker image name (default: agenticmail/agent).
• Tag — Image tag (default: latest).
• Ports — Comma-separated port mappings.
• Memory / CPU — Resource limits (e.g., 512m, 0.5 CPU).
• Network — Docker network name.
• Restart Policy — Unless Stopped, Always, On Failure, or Never.

VPS / Bare Metal

• Host — IP address or hostname.
• SSH Port — Default 22.
• User — SSH user (default: root).
• SSH Key Path — Path to private key.
• Work Directory — Where the agent runs on the server.

Local (In-Process)

For development and single-server deployments:

• Port — HTTP port the agent listens on. Validated in real-time (see below).
• Host — Hostname or IP (default: localhost).
• Process Manager — PM2 (with install detection), systemd, Manual, or In-Process (embedded).
• Process Name — PM2/systemd service name for lifecycle management.
• Working Directory — Auto-detected or manually specified.

Port Validation

When you enter a port number, the system automatically checks whether it's available before allowing you to save:

• Debounced — Validation triggers 500ms after you stop typing, preventing excessive API calls.
• Bind test — Uses net.createServer() to attempt binding the port. This is the most reliable availability check.
• Process identification — If the port is in use, the system runs lsof (macOS/Linux) or netstat (Windows) to identify the process name and PID.
• Save blocked — You cannot save deployment configuration while a port conflict exists.

POST /system/check-port
Body: { "port": 4100 }
Response (available): { "available": true, "port": 3102 }
Response (in use):    { "available": false, "port": 3102, "process": "node (PID 12345)" }

Deployment Status

The status card shows:

• State — Running, Active, Deploying, Starting, Degraded, Error, Stopped, Draft, Ready. Color-coded.
• Health — Healthy, Degraded, or Unhealthy.
• Uptime — Time since last deployment.
• Endpoint — The agent's URL (clickable link).
• Target, Model, Region, Port — Current deployment configuration.

Lifecycle Controls

• Deploy — Available when stopped. Initiates the deployment process.
• Stop — Available when running. Gracefully stops the agent.
• Restart — Available when running or stopped. Stops and starts the agent.

Knowledge Bases

The Knowledge Bases card shows shared knowledge sources assigned to this agent. These provide the agent with organizational context and reference materials via RAG (Retrieval-Augmented Generation).

Auto-Assignment on Creation

When a new agent is created, knowledge bases are automatically assigned based on the agent's organization:

• Client org agents — Automatically get all knowledge bases belonging to their client organization.
• Internal agents — Automatically get all knowledge bases that are NOT assigned to any client organization (i.e., internal/shared KBs).

Sync Knowledge Button

If new knowledge bases are added after the agent was created, click the "Sync Knowledge" button in the card header to pick them up. This triggers the same auto-assignment logic:

• Scans all knowledge bases matching the agent's org context.
• Assigns any KBs the agent doesn't already have access to.
• Does NOT remove existing assignments — only adds new ones.

POST /knowledge-bases/auto-assign/:agentId
Body: { "clientOrgId": "org-uuid" }  // optional, auto-detected from agent
Response: { "agentId": "...", "assigned": ["kb-1", "kb-2"], "count": 2 }

Agent Deletion

A 5-step confirmation flow prevents accidental deletion:

1. Click "Delete Agent"
2. Three confirmation steps with increasingly clear warnings
3. Type the agent's name to confirm
4. Final deletion via DELETE /bridge/agents/:id

Best Practices

Troubleshooting

Related Pages