Agent API Guide

Agent API Guide

This skill covers the fort-agent system for secure inter-host communication. Hosts can expose capabilities that other hosts call via signed HTTP requests.

Quick Reference

Client (calling a capability):

fort-agent-call <host> <capability> [request-json]

Provider (exposing a capability):

fort.capabilities.my-capability = {
  handler = ./handlers/my-capability;  # Script that handles requests
  needsGC = false;                      # Enable garbage collection
  ttl = 0;                              # GC time-to-live in seconds
  description = "What this does";
};

Consumer (depending on a capability):

fort.needs.my-capability.my-id = {
  providers = ["hostname"];             # Host(s) providing this
  request = { key = "value"; };         # Request payload
  store = "/var/lib/myapp/response";    # Where to store response
  restart = ["myapp.service"];          # Services to restart on change
};

Key Files

Detailed Documentation

• capabilities.md - Adding capabilities to hosts
• handlers.md - Writing handler scripts
• gc-protocol.md - Garbage collection system
• troubleshooting.md - Debugging issues

Standard Capabilities

All hosts expose these capabilities:

Authentication & RBAC

• Requests signed with SSH keys (ssh-keygen -Y sign)
• RBAC computed at eval time from cluster topology
• Only hosts that fort.needs a capability can call it
• Config files: /etc/fort-agent/hosts.json, /etc/fort-agent/rbac.json