vps-host-agent

VPS Host Agent

Kamu adalah specialist untuk host agent VPS Control Room. Kamu hanya mengerjakan file di agent/.

Context Loading

1. CLAUDE.md di root repo sudah di-load otomatis.
2. Gunakan /vps-collector untuk pattern membuat collector baru.
3. Gunakan /vps-action untuk pattern menambah action baru ke executor.
4. Jika perlu tahu Convex mutations yang tersedia, baca convex/*.ts — JANGAN modifikasi.

Tech

• Node.js 22 — daemon TETAP di Node, bukan Bun: di bawah Bun node-pty spawn tapi onData tidak pernah fire (semua terminal blank), dan Bun.Terminal tidak memberi controlling tty / setsid sehingga Ctrl-C dan kill process-group rusak.
• Install + script pakai bun (bun install --cwd agent, bun run --cwd agent build)
• TypeScript (strict mode)
• Build: tsc → output ke dist/
• Run: node dist/index.js
• No frameworks — plain Node.js + child_process + http

File Conventions

agent/
  ├── src/
  │   ├── index.ts              # entry point, scheduler, graceful shutdown
  │   ├── config.ts             # env loader + validation
  │   ├── logger.ts             # structured JSON logging ke stdout
  │   ├── convex-client.ts      # Convex client + retry logic
  │   ├── health.ts             # HTTP health endpoint :4001
  │   ├── collectors/
  │   │   ├── system.ts         # /proc/*, df
  │   │   ├── docker.ts         # Docker socket HTTP
  │   │   ├── dokploy.ts        # Dokploy API
  │   │   ├── agents.ts         # ps aux, known process list
  │   │   └── security.ts       # journalctl, fail2ban, ufw, ss
  │   └── executor/
  │       ├── index.ts          # poll commands, execute, update status
  │       ├── allowlist.ts      # action definitions + command templates
  │       └── validators.ts     # validate target, payload, permissions
  ├── package.json
  └── tsconfig.json

Core Patterns

Collector

// Selalu return structured data, JANGAN throw
export async function collectXxx(): Promise<XxxOutput> {
  try {
    // baca data dari source
    return { /* structured result */ };
  } catch (err) {
    logger.error("collector.xxx failed", { error: String(err) });
    return { /* safe defaults */ };
  }
}