DevOps Agent Adapter

Connect any Linux server to your DevOps Agent central server — enabling AI-powered infrastructure management via Claude Code.

Quick Install (New Server)

SSH into your server and run these commands:

# Step 1: Install pipx (handles the adapter without needing a venv)
sudo apt install pipx -y && pipx ensurepath    # Ubuntu/Debian
# or
sudo dnf install pipx -y && pipx ensurepath    # Amazon Linux / RHEL

# Step 2: Install the adapter from PyPI
pipx install devops-agent-adapter

# Step 3: Verify
devops-agent --version
devops-agent doctor

Then set up your node:

devops-agent init --output ~/identity.json   # generate config template
nano ~/identity.json                          # fill in your server details
devops-agent start --identity ~/identity.json # connect to central server

Install Options

Choose based on your situation:

Option A — pipx from PyPI (Recommended)

Best for most situations. Installs from the public PyPI package registry — no GitHub URL, no PAT token needed.

# Install pipx if not present
sudo apt install pipx -y && pipx ensurepath    # Ubuntu/Debian
# or
sudo dnf install pipx -y && pipx ensurepath    # Amazon Linux / RHEL

# Install the adapter
pipx install devops-agent-adapter

# Verify
devops-agent --version
devops-agent doctor

Why pipx? It automatically creates an isolated virtual environment behind the scenes, then makes devops-agent available as a global command — you never need to type source activate or remember any venv paths. Open a new terminal after pipx ensurepath for the PATH change to take effect.

Option B — One-Liner Script (Fresh Server, Public Repo Only)

Best when your repo is public and your server is brand new (nothing installed yet). The script handles Python, Node.js, pipx, and the adapter all in one go.

curl -fsSL https://raw.githubusercontent.com/YOUR_ORG/devops-agent/main/adapter/install.sh | sudo bash

Note: This only works if the repository is public. If the repo is private, use Option A instead.

Option C — pip (Traditional, with venv)

Best when: you want to manage the install inside your own virtual environment.

python3 -m venv ~/agent-env
source ~/agent-env/bin/activate
pip install devops-agent-adapter
devops-agent --version

Note: With pip, you'll need to activate the venv every time you SSH in. Use sudo devops-agent install-service with the absolute binary path to avoid this for the daemon.

Prerequisites

Claude Code is installed automatically when you first run devops-agent start.

Step-by-Step Setup

Step 1 — Expose Your Central Server

Your EC2 instance needs to reach your central server. If the central server is running locally on your PC, expose it first:

# On your PC — install ngrok (https://ngrok.com) then:
ngrok http 3000
# Output: Forwarding https://xxxx.ngrok-free.app -> http://localhost:3000

Write down the ngrok URL — you'll put it in identity.json as central_server.

If your central server is already on a public IP or domain with port 3000 open, skip ngrok.

Step 2 — Connect to Your Server

# SSH in or use AWS SSM Session Manager:
# AWS Console → EC2 → Select instance → Connect → Session Manager

# Switch to your application user if needed
sudo su - YOUR_APP_USER

Step 3 — Install the Adapter

Pick one of the three options above. The recommended approach for a fresh server:

curl -fsSL https://raw.githubusercontent.com/YOUR_ORG/devops-agent/main/adapter/install.sh | sudo bash

Step 4 — Configure the Node

devops-agent init --output ~/identity.json
nano ~/identity.json

Fill in the template:

{
  "secret": "your-node-secret",

  "node_id": "i-YOUR_INSTANCE_ID",
  "node_name": "My-Server",
  "project_id": "my-project",
  "project_name": "My Project",
  "hostname": "ip-PRIVATE-IP",
  "environment": "production",

  "central_server": "https://YOUR-NGROK-URL.ngrok-free.app",

  "sandbox": "/home/YOUR_APP_USER",

  "cloud_metadata": {
    "provider": "aws",
    "aws": {
      "credentials": {
        "access_key_id":     "YOUR_ACCESS_KEY_ID",
        "secret_access_key": "YOUR_SECRET_ACCESS_KEY"
      },
      "region":      "us-east-1",
      "account_id":  "YOUR_ACCOUNT_ID",
      "instance_id": "i-YOUR_INSTANCE_ID"
    }
  },

  "metadata": {
    "server_type": "ec2",
    "version":     "1.0.0",
    "capabilities": [
      "check_service_status",
      "view_logs",
      "check_health",
      "run_command",
      "upload_s3",
      "analyze_code"
    ]
  }
}

Field reference:

Anthropic API key: Do NOT put it in identity.json. The central server stores it and pushes it automatically to each node on connection.

Step 5 — Start the Adapter

devops-agent start --identity ~/identity.json

Expected output:

🚀 Starting DevOps Agent adapter (daemon)
   Node    : My-Server  (i-0abc123def456)
   Project : My Project  (my-project)
   Server  : https://xxxx.ngrok-free.app

✅ Daemon started (PID 12345)
   Logs : ~/.devops-agent/logs/adapter.log

   Commands:
     devops-agent status   — check if running
     devops-agent logs     — view live logs
     devops-agent stop     — stop the daemon

Your terminal is immediately free. The adapter runs in the background and reconnects automatically if the connection drops.

Step 6 — Verify

devops-agent status    # should show: 🟢 running
devops-agent doctor    # checks all dependencies
devops-agent logs      # view recent log output

On your dashboard, the node should appear with a green dot.

Auto-Start on Boot (Systemd)

To ensure the adapter starts automatically when the server reboots:

sudo devops-agent install-service --identity ~/identity.json

This creates a systemd service. To manage it:

sudo systemctl status devops-agent
sudo systemctl restart devops-agent
journalctl -u devops-agent -f   # live logs via journald

To remove the service:

sudo devops-agent uninstall-service

Adding More Servers

For each additional server:

# 1. Install the adapter (same as above)
curl -fsSL https://raw.githubusercontent.com/YOUR_ORG/devops-agent/main/adapter/install.sh | sudo bash

# 2. Generate config
devops-agent init --output ~/identity.json

# 3. Edit — change node_id, node_name, and sandbox only
nano ~/identity.json

# 4. Start
devops-agent start --identity ~/identity.json

# 5. Optional: auto-start on reboot
sudo devops-agent install-service --identity ~/identity.json

CLI Reference

Updating the Adapter

When a new version is released:

devops-agent update

This automatically uses pipx upgrade if installed via pipx, or pip install --upgrade otherwise.

To check your current version:

devops-agent version

Key Rotation

The Anthropic API key is stored only on the central server (backend-python/.env). Rotate it across all live nodes without touching any server:

Option A — Restart the server (new nodes get the new key on next registration):

# Update ANTHROPIC_API_KEY in backend-python/.env, then restart the server

Option B — Hot-rotate without restarts (all connected nodes updated instantly):

TOKEN="<your-admin-jwt>"
curl -X POST https://YOUR-SERVER/api/admin/config/update \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"anthropic_api_key": "sk-ant-NEW-KEY"}'
# Response: {"ok": true, "nodes_updated": 3}

Log File Locations

Logs rotate at 10 MB with 5 backups kept.

Troubleshooting

How It Works

EC2 Server                          Central Server
─────────────────                   ──────────────────────────
devops-agent start                  
    │                               
    ├─ reads identity.json          
    ├─ connects via WebSocket  ───► registers node
    │                          ◄─── pushes API key + skills
    │
    ├─ waits for jobs...       ◄─── "check disk usage"
    │
    ├─ runs Claude Code             
    │   (with skill procedures)     
    │                               
    └─ streams result back     ───► job complete

The adapter auto-reconnects if the connection drops (exponential backoff: 1s → 60s).

Files

• devops_agent/cli.py — CLI entry point
• devops_agent/runner.py — WebSocket agent
• devops_agent/claude_runner.py — Claude Code execution + skill loading
• devops_agent/skills/ — Built-in procedure skills (bundled with the package)
• install.sh — One-liner installer script
• identity.example.json — Full configuration reference