Module `kernels`: managing remote Agent OS cores

🔵 Module kernels maintains a registry of remote Agent OS instances and lets agents manage them: monitoring and requests via the core's HTTP API, and lifecycle via SSH (through the remote module). Unlike remote (arbitrary hosts), kernels knows that the target is an Agent OS core.

The module is included in the standard distribution (modules.enabled → kernels) and requires remote (requires: ["remote"]).

52.1 Registry

A core is described by a document: slug, base_url, token_secret, machine, deploy. The registry is in DuckDB (logs/kernels.db), seeded from config/remote/kernels.yaml (as with remote, the seed does not overwrite edits in the DB).

kernels:
  - slug: prod
    base_url: https://platform.example.com
    token_secret: PROD_ADMIN_TOKEN     # имя секрета, не сам токен
    machine: prod-host                 # slug машины из инвентаря `remote`
    tags: [prod]
    deploy:
      remote_dir: /home/realityfaker/agent_os
      archive: distrib/agent-os-distrib-linux.zip
      install_command: |
        set -e
        cd /home/realityfaker/agent_os
        unzip -o distrib/agent-os-distrib-linux.zip -d /tmp/ao-distrib
        install -m 0755 /tmp/ao-distrib/agent-os-distrib/bin/agent-os target/release/agent-os
      log_path: /home/realityfaker/agent_os/agent_os.log

Paths are overridden by AGENT_OS_KERNELS_DB / AGENT_OS_KERNELS_CONFIG.

52.2 Transports {#transports}

HTTP — via the host port agent_os.Http (host SSRF policy, synchronous). The admin token is read from agent_os.Secrets by the name token_secret.
SSH — via the remote module: the core references the machine's slug, and its policy applies (policy.mode/allow/approval). Lifecycle commands are resolved just like any remote exec, fail-closed.
Deploy — preferably via the distribution: the archive is uploaded via SCP to <remote_dir>/distrib/, then on the host install_command is executed (and, by default, sudo systemctl restart agent-os).

52.3 Tools

See the Tool Reference.

Group	`kind`
Registry	`kernel_list`, `kernel_get`, `kernel_upsert`, `kernel_delete`
HTTP	`kernel_health`, `kernel_models`, `kernel_agents`, `kernel_templates`, `kernel_request`
SSH	`kernel_service`, `kernel_logs`, `kernel_deploy`

Example:

kind: kernel_service
name: prod_service
description: Управление сервисом agent-os на прод-хосте

52.4 HTTP API

Endpoint	Description
`GET /v1/kernels`	list cores 🔒
`POST /v1/kernels`	create/update a core 🔒
`GET /v1/kernels/:slug`	a single core 🔒
`PUT /v1/kernels/:slug`	update 🔒
`DELETE /v1/kernels/:slug`	delete 🔒
`GET /v1/kernels/:slug/health`	health probe of a remote core (HTTP) 🔒

52.5 Security

The admin token and install_command are not exposed in the API (redacted()).
HTTP is restricted by the host port's SSRF policy; SSH — by the policy of the machine remote.
Deploy is allowed only if the machine's policy permits the commands (mode: full or a suitable allow).

52.6 Limitations

The remote module is required.
The host port Http may reject private/loopback addresses — use the cores' public addresses.
Lifecycle (SSH) is available only as tools (the routes are synchronous).