devops-agent-adapter 2.3.1

DevOps AI Agent — connects servers to the central orchestration server via Claude Code

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

Requirement	Version	Purpose
Python	3.11+	Runs the adapter
Node.js	18+	Required for Claude Code CLI
npm	any	Required for Claude Code CLI
Claude Code	latest	The AI execution engine

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:

Field	Where to find it
node_id	EC2 Instance ID from AWS Console (e.g. i-0abc123def456)
node_name	The Name tag of your EC2 instance
project_id	Must match the project ID in your central server dashboard
central_server	Your ngrok URL or public server URL
sandbox	Home directory of the app user (e.g. /home/ubuntu)
secret	Must match NODE_SECRET in the central server's config.py

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

Command	Description
devops-agent version	Show installed adapter version
devops-agent --version	Same (flag form)
devops-agent init -o ~/identity.json	Generate identity file template
devops-agent start -i ~/identity.json	Start as background daemon
devops-agent start -i ~/identity.json --foreground	Start in foreground (debug)
devops-agent stop	Stop the running daemon
devops-agent status	Check if adapter is running
devops-agent logs	Show last 50 log lines
devops-agent logs -f	Tail logs in real-time
devops-agent logs -n 200	Show last 200 log lines
devops-agent update	Upgrade to latest version
devops-agent doctor	Check all dependencies
sudo devops-agent install-service -i ~/identity.json	Install systemd service
sudo devops-agent uninstall-service	Remove systemd service

---

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

User	Log file	PID file
root	/var/log/devops-agent/adapter.log	/var/run/devops-agent.pid
non-root	~/.devops-agent/logs/adapter.log	~/.devops-agent/devops-agent.pid

Logs rotate at 10 MB with 5 backups kept.

---

Troubleshooting

Symptom	Likely Cause	Fix
devops-agent: command not found	pipx bin not in PATH	Run pipx ensurepath then open a new terminal
Connection refused	Central server not reachable	Check ngrok is running, URL is correct
AUTH_FAILED in logs	Wrong secret	secret in identity.json must match NODE_SECRET in central server
Node not in dashboard	Wrong project_id	Must match exactly (case-sensitive)
⚠️ Adapter update available	Newer version released	Run devops-agent update
Claude Code install fails	npm missing	Install Node.js first (it includes npm)
Permission denied on service install	Need root	Prefix with sudo
Node offline after EC2 reboot	Systemd service not installed	sudo devops-agent install-service -i ~/identity.json
No API key received after registration	Key not set on central server	Add ANTHROPIC_API_KEY=sk-ant-... to backend-python/.env

---

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