Metadata-Version: 2.4
Name: devops-agent-adapter
Version: 2.3.1
Summary: DevOps AI Agent — connects servers to the central orchestration server via Claude Code
Author: Purvansh
License-Expression: MIT
Project-URL: Homepage, https://github.com/purvansh23/devops-agent
Project-URL: Repository, https://github.com/purvansh23/devops-agent
Project-URL: Documentation, https://github.com/purvansh23/devops-agent/tree/main/adapter
Project-URL: Issues, https://github.com/purvansh23/devops-agent/issues
Keywords: devops,agent,infrastructure,automation,claude,ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Developers
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: System :: Monitoring
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: POSIX :: Linux
Classifier: Environment :: No Input/Output (Daemon)
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-socketio[client]>=5.11
Requires-Dist: websocket-client>=1.7
Requires-Dist: boto3>=1.34
Requires-Dist: requests>=2.31
Dynamic: license-file

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

```bash
# 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:

```bash
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.

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

```bash
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.

```bash
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:

```bash
# 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

```bash
# 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:

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

### Step 4 — Configure the Node

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

Fill in the template:

```json
{
  "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

```bash
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

```bash
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:

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

This creates a systemd service. To manage it:

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

To remove the service:

```bash
sudo devops-agent uninstall-service
```

---

## Adding More Servers

For each additional server:

```bash
# 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:

```bash
devops-agent update
```

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

To check your current version:

```bash
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):
```bash
# Update ANTHROPIC_API_KEY in backend-python/.env, then restart the server
```

**Option B — Hot-rotate without restarts** (all connected nodes updated instantly):
```bash
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
