Deploy an Agent to a Remote Environment

This guide walks you through deploying Unpage agents to a remote production environment, including containerization, PagerDuty webhook integration, and automated deployment via GitHub Actions.

Prerequisites

Before you begin, ensure you have basic familiarity with Unpage concepts and agent configuration

Containerizing Your Unpage Deployment

This guide covers how to deploy Unpage using Docker. Unpage is a python package and can be deployed using your favorite method for deploying python services!

Creating a Dockerfile

Create a Dockerfile in your desired profile directory (e.g., ~/.unpage/profiles/default) so it has access to your config.yaml and agent files:

# Use Python 3.12+ as required by Unpage
FROM ghcr.io/astral-sh/uv:python3.13-bookworm-slim

ENV UV_COMPILE_BYTECODE=1 \
    UV_PYTHON_DOWNLOADS=0 \
    UV_TOOL_DIR=/usr/local/share/uv/tools

# Create a new user to run the container as
RUN useradd -m unpage

# Create the unpage profile
RUN mkdir -p /home/unpage/.unpage/profiles/default/ \
 && chown -R unpage:unpage /home/unpage/.unpage

# Install unpage
RUN apt update -y \
 && apt install -y \
  build-essential \
  curl \
  ;
RUN curl -fsSL https://install.unpage.ai | bash \
 && unpage --version

# Copy your agent configurations and config files
COPY --chown=unpage:unpage config.yaml /home/unpage/.unpage/profiles/default/config.yaml
COPY --chown=unpage:unpage ./agents/ /home/unpage/.unpage/profiles/default/agents/

# Switch to the new user
USER unpage

WORKDIR /home/unpage

EXPOSE 5678
CMD ["unpage", "agent", "serve", "--host", "0.0.0.0", "--port", "5678"]

Docker Compose Configuration

For local development and testing, create a docker-compose.yml:

version: '3.8'

services:
  unpage:
    build: .
    ports:
      - "5678:5678"
    environment:
      - UNPAGE_PROFILE=default
      # Add your environment-specific variables
      - PAGERDUTY_API_KEY=${PAGERDUTY_API_KEY}
      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
      - LLM_API_KEY=${LLM_API_KEY}
    volumes:
      # Mount config file and agents directory for development
      - ./config.yaml:/root/.unpage/profiles/default/config.yaml
      - ./agents:/root/.unpage/profiles/default/agents
    restart: unless-stopped

Configuration Management

Create a production-ready config.yaml:

plugins:
  core:
    enabled: true

  networking:
    enabled: true

  aws:
    enabled: true

  llm:
    enabled: true
    settings:
      model: claude-4-sonnet-20250514
      api_key: ${LLM_API_KEY}

  pagerduty:
    enabled: true
    settings:
      api_key: ${PAGERDUTY_API_KEY}
      from_email: alerts@yourcompany.com

  shell:
    enabled: true
    settings:
      # Add your custom shell commands here
      commands: []

PagerDuty Integration

Setting Up PagerDuty Webhooks

Configure your production webhook URL

Determine your public webhook URL. This should be your deployed Unpage server with the /webhook path:

https://unpage.yourcompany.com/webhook

Create PagerDuty webhook

In PagerDuty, navigate to Integrations → Generic Webhooks (v3)
Click + New Webhook
Configure the webhook:
- Webhook URL: https://unpage.yourcompany.com/webhook
- Event Subscriptions: Select events you want agents to handle:
  - incident.triggered - When new incidents are created
  - incident.acknowledged - When incidents are acknowledged
  - incident.escalated - When incidents escalate
  - incident.resolved - When incidents are resolved
- Custom Headers (optional): Add authentication headers if needed

Test the webhook

Use PagerDuty’s webhook testing feature or create a test incident to verify your deployment receives webhooks correctly.

Agent Configuration for Production

Create production agents in your agents/ directory. Here’s an example production agent (agents/ssl-investigation.yaml):

description: Investigate SSL/TLS connection failures in production environments

prompt: |
  - Extract the affected domain/hostname from the PagerDuty incident
  - Use knowledge graph to identify related infrastructure components
  - Check SSL certificate expiration using shell commands
  - Verify DNS resolution and connectivity
  - If certificate is expired or expiring within 48 hours:
    - Post detailed status update to incident with specific remediation steps
    - Include certificate expiration date and affected services
  - If DNS issues detected:
    - Check Route53 records and provide resolution guidance
  - Escalate to on-call engineer if critical infrastructure is affected

tools:
  - "pagerduty_post_status_update"
  - "pagerduty_get_incident_details"
  - "shell_check_ssl_certificate"
  - "shell_check_dns_resolution"
  - "aws_route53_list_records"
  - "graph_find_related_nodes"

Troubleshooting

Debug logs

Add the --debug flag to unpage agent serve to get detailed logs about what actions the server is taking.

MLflow tracing

See the Debugging with MLflow tracing page.

About Unpage

Core Concepts

Example Agents

Plugins

How-To Guides

Command Reference

Deploy an Agent to a Remote Environment

Prerequisites

Containerizing Your Unpage Deployment

Creating a Dockerfile

Docker Compose Configuration

Configuration Management

PagerDuty Integration

Setting Up PagerDuty Webhooks

Agent Configuration for Production

Troubleshooting

Debug logs

MLflow tracing

​Prerequisites

​Containerizing Your Unpage Deployment

​Creating a Dockerfile

​Docker Compose Configuration

​Configuration Management

​PagerDuty Integration

​Setting Up PagerDuty Webhooks

​Agent Configuration for Production

​Troubleshooting

​Debug logs

​MLflow tracing

Prerequisites

Containerizing Your Unpage Deployment

Creating a Dockerfile

Docker Compose Configuration

Configuration Management

PagerDuty Integration

Setting Up PagerDuty Webhooks

Agent Configuration for Production

Troubleshooting

Debug logs

MLflow tracing