Agent protocol

The protocol between goliash-agent and the server is described in api/agent-v1.yaml and licensed Apache-2.0, so you can write your own agent or collector. The server validates every request against it.

• The agent only makes outbound HTTPS requests; the server never connects to the agent.
• Every request carries Authorization: Bearer glsh_agent_…. One token identifies one agent in one workspace and may only send data and read that agent’s configuration.
• The agent sends full state (snapshots), never events. The server compares consecutive snapshots of a target.
• Credentials stay with the agent. The server only sends a credentials_ref name, which the agent resolves locally.

Call order: enroll on start when the agent has an enrollment code instead of a token, then register, then config every minute (with an ETag), a snapshot per target on its interval (Kubernetes also shortly after changes), a heartbeat every minute, and registry-results on the registry check interval. While the server is unreachable, the agent buffers up to 200 snapshots on disk.

A registry check may carry resolve: running digests of images on moving tags, each with the tags it may be. The agent compares them (HEAD first, platform manifests of the two newest candidates only when needed) and answers in resolved. Choosing candidates stays on the server; the agent only compares digests. Older agents ignore the field.