incus-contrib/.claude/rules/aether-api-payloads.md

Aether API Payloads Context

paths:

• bin/helpers/incus-mitm
• api-interception

How Aether Communicates with Incus

Aether (192.168.102.160) authenticates to the Incus cluster using a TLS client certificate with subject CN=root@oc-server. Its fingerprint prefix is 6cfd2a1949a7.

Aether's Behavior Pattern

1. Subscribes to Incus event stream (persistent websocket)
2. Reacts to lifecycle events by querying affected resources
3. When user triggers UI actions, makes Incus API calls server-side

Capturing Events

# Live stream with Aether filter
bin/helpers/incus-mitm --live --filter aether

# Capture to file
bin/helpers/incus-mitm --capture 120
bin/helpers/incus-mitm --analyze /tmp/incus-events-*.json --filter aether

API Call Patterns

All Incus operations follow: request → operation (pending→running→success) → lifecycle event

Key patterns:

• Stop: PUT /1.0/instances/<name>/state
• Start: PUT /1.0/instances/<name>/state
• Snapshot: POST /1.0/instances/<name>/snapshots
• Delete: DELETE /1.0/instances/<name>/snapshots/<snap>
• Exec: POST /1.0/instances/<name>/exec (4 websockets)

Aether reacts to lifecycle events with: GET /1.0 → GET /1.0/instances/<name>?recursion=1

Aether's Own REST API

Separate from Incus, JWT-authenticated:

• POST /api/auth/token
• GET /api/clusters
• CRUD /api/clusters/{id}/rules
• CRUD /api/global/rules