Local skill · panduan lengkap

Pasang Proxmox AI di AI client-mu sendiri.

Claude Code, Codex, Claude Desktop, Cursor — atau API ChatGPT langsung. Tool yang muncul mengikuti role API key-mu, dan setiap perubahan tetap berhenti di propose → confirm.

1 · Terbitkan API key

Di dashboard, buka Organisasi → API keys → New key. Isinya:

• Role — ambil yang paling rendah yang masih cukup. Mulai dari readonly; naik ke operator kalau Anda ingin agent bisa menyusun perubahan (tetap tidak bisa mengeksekusi).
• Allowed IP — wajib. Isi alamat IP publik tempat Anda akan memakainya. Key ditolak dari alamat lain, meski key-nya benar.
• Masa berlaku dan rate limit per menit.

2 · Cara A — curl, tanpa Node

Claude Code dan Codex sudah bisa menjalankan shell, jadi tidak perlu memasang apa pun selain curl. Ini cara yang paling ringan.

$ git clone https://github.com/hamimistimewa/proxmox-ai-mcp
$ cd proxmox-ai-mcp
$ ./install.sh --url https://proxmox.ai.id --key pak_xxxxxxxxxxxx_…

Checking https://proxmox.ai.id/api/v1 …
  v  key accepted — Acme · role operator, 31 tools
  v  credentials saved — ~/.proxmox-ai/config.json (owner only)
  v  pmx linked — ~/.local/bin/pmx
  v  skill installed — ~/.claude/skills/proxmox-ai

Installer memverifikasi key sebelum menulis apa pun, menyimpan kredensial dengan mode 600, menaruh perintah pmx di PATH, dan menyalin skill ke client yang terpasang. Setelah itu tinggal bertanya ke agent Anda:

> node mana yang RAM-nya paling mepet?
> VM mana saja yang belum ada backup minggu ini?

pmx adalah satu skrip POSIX shell tanpa dependensi selain curl — silakan dibaca isinya di bin/pmx.

Kalau mau pakai curl mentah

$ curl -sS -H "Authorization: Bearer pak_…" \
    https://proxmox.ai.id/api/v1/nodes

3 · Cara B — MCP server

Kalau Anda ingin tool-nya muncul sebagai tool betulan di daftar tool client (bukan lewat shell), pakai MCP server. Butuh Node 20 atau lebih baru.

$ node bin/install.mjs --url https://proxmox.ai.id --key pak_…

Pemeriksaan yang sama, lalu server didaftarkan ke setiap client yang ditemukan: Claude Code, Claude Desktop, Codex, Cursor, Windsurf, Gemini CLI, dan VS Code. Client yang tidak terpasang dilewati; entri yang sudah ada digabung, bukan ditimpa. Restart client setelahnya — konfigurasi MCP dibaca saat start.

Tetap nol dependensi: seluruh protokol JSON-RPC ditulis apa adanya di bin/proxmox-ai-mcp.mjs, bisa dibaca sekali duduk.

4 · Kenapa tool-nya beda per key

Tidak ada daftar tool yang dibawa client. Saat start, keduanya menanyakan ke platform: key ini boleh memanggil apa?

# key operator
$ pmx tools
scope: organization  role: operator  org: Acme
  whoami           GET  /me
  list_nodes       GET  /nodes
  propose_action   POST /actions
  confirm_action   POST /actions/{id}/confirm
  …53 tools

# key readonly — 48 tools, dan propose_action tidak ada di antaranya

Superadmin dapat 65 tool, dan platform key dapat 24 tool untuk mengelola seluruh estate. Key readonly tidak pernah diberi tahu bahwa propose_action ada. Jadi model tidak bisa mencoba lalu ditolak — tool-nya memang tidak ada. IP whitelist, rate limit, dan masa berlaku tetap ditegakkan platform di setiap panggilan.

Efek lain: daftar tool selalu ikut terbaru. Endpoint baru di platform otomatis muncul di semua pemasangan pada start berikutnya — Anda tidak perlu menarik ulang repo.

5 · Workflow siap pakai

Selain tool, server ini juga menerbitkan prompt — alur kerja ops yang sudah tahu tool mana yang dipanggil, dengan urutan apa, dan apa yang dilaporkan. Di Claude Code mereka muncul sebagai slash command.

> /mcp__proxmox-ai__health-check
> /mcp__proxmox-ai__triage symptom="web-01 lambat sejak pagi"

Prompt juga ikut role key: plan-vm butuh propose_action, jadi key readonly ditawari 6 prompt, operator 7. Tidak satu pun yang mengonfirmasi apa-apa — semuanya berakhir dengan menyuruh model berhenti di rencana.

Ada juga resource, yaitu data yang bisa ditarik client sebagai konteks tanpa menghabiskan satu panggilan tool: proxmox://me, proxmox://nodes, proxmox://guests, proxmox://storage, proxmox://actions, proxmox://backups.

6 · Satu server untuk satu tim

Kalau tidak mau tiap orang memasang sendiri, jalankan satu server dan arahkan semua client ke sana. Tiap request membawa key-nya masing-masing, jadi tiap orang tetap hanya melihat tool yang key-nya izinkan.

$ proxmox-ai-mcp --transport http --port 8080
v listening on http://127.0.0.1:8080/mcp

# dari client mana pun
$ npx mcp-remote http://host:8080/mcp

# atau lewat Docker
$ docker build -t proxmox-ai-mcp .
$ docker run --rm -p 8080:8080 -e PROXMOX_AI_TRANSPORT=http \
    -e PROXMOX_AI_URL=https://proxmox.ai.id proxmox-ai-mcp

Melayani streamable HTTP di POST /mcp dan pemeriksaan kesiapan di GET /health. Tidak membuka stream SSE: tiap jawaban kembali pada POST yang memintanya.

7 · Daftar perintah

$ pmx me                                  # key ini siapa, role apa, organisasi mana
$ pmx tools                               # persis apa yang boleh dipanggil
$ pmx get /nodes                          # armada
$ pmx get /nodes/pve01/usage range=24h    # satu node, dengan riwayat
$ pmx get /vms                            # guest dan template
$ pmx get /guests/101                     # detail satu guest
$ pmx get /storage                        # storage pool
$ pmx get /disks                          # disk fisik, LVM, ZFS
$ pmx get /capabilities                   # hak yang benar-benar dimiliki token Proxmox
$ pmx get /backups/overview               # backup terakhir per guest — mencari yang bolong
$ pmx get /audit limit=20                 # siapa mengubah apa, termasuk agent
$ pmx actions                             # proposal yang menunggu dan hasil terakhir
$ pmx action 42                           # satu aksi, dengan rencana dan peringatannya

8 · Mengubah infrastruktur

Tidak ada satu pun perintah yang langsung mengubah Proxmox.

$ pmx propose guest_power vmid=101 operation=shutdown
! status: proposed · id 42
  plan    : Shut down (graceful) vm 101 (web-01) on pve01
  warning : guest agent tidak merespons; shutdown bisa memakan waktu

# tidak ada yang berubah sampai baris berikut dijalankan
$ pmx confirm 42
v status: executing → confirmed · audit #18422

Skill yang ikut terpasang itulah yang mengajarkan disiplin ini ke model — deskripsi tool saja tidak cukup. Skill-nya melarang model memanggil confirm_action atas inisiatif sendiri, dan mewajibkan rencana beserta seluruh peringatannya ditunjukkan dulu ke Anda.

9 · Dari API ChatGPT

$ node bin/export-openai-tools.mjs --url https://proxmox.ai.id --key pak_…
  v Wrote 31 tools to schemas/openai-tools.json

$ pip install openai
$ python examples/openai_client.py "ringkas kondisi infrastruktur saya"

File-nya dihasilkan dari manifest yang sama, jadi tersaring oleh role key Anda dengan cara yang sama persis.

10 · Berkas yang ditulis

11 · Pemecahan masalah

Menjalankan ulang installer mana pun aman, dan key selalu diverifikasi sebelum ada yang disentuh.

---