Concepts and terminology

The Goauld concepts used throughout the documentation

Components

Goauld has three components:

  • Server: the broker. It accepts the agent’s outbound connections and exposes the operator-facing API and SSH entry points.
  • Agent: runs on the target machine. It initiates the connection to the server and exposes SSH-based services through that connection.
  • Client (tealc): runs on the operator’s machine and uses the server to list agents, open sessions, transfer files, and manage the deployment.

Control and data traffic

The control channel carries registration, heartbeats, configuration, and management messages. A data channel carries SSH sessions, SFTP, file transfers, proxies, and port forwards.

The agent initiates both connections. The SSH data connection can use direct SSH, TLS, WebSocket, HTTP, DNS, or QUIC. The Socket.IO control connection uses HTTP long polling, WebSocket over HTTP(S), or WebSocket encapsulated over DNS. The chosen transport does not change the SSH interface exposed to the operator.

Names and identities

An agent has a persistent ID and a display name. The default display name is based on the username and hostname, but it can be overridden at build or run time. Use the ID when an operation must target one exact agent; use the name for normal interactive work.

Tokens and keys

  • The age private key stays on the server.
  • The age public key is embedded in agent build configuration.
  • The access token protects the normal management API.
  • The admin token protects administrative endpoints.

Do not place private keys or tokens in a public agent binary, shell history, or documentation example.