agent

Documentation

Overview

telad -- Tela Daemon (WireGuard Agent)

Purpose:

Connects to the Hub via WebSocket, registers one or more machines,
and waits. When the Hub signals a session (with the client's WireGuard
public key), it creates a userspace WireGuard tunnel using gVisor
netstack -- no TUN device, no admin/root required.

Config-file mode (recommended):
  telad -config telad.yaml

Single-machine mode (flags):
  telad -hub ws://hub -machine barn -ports 22:SSH,3389:RDP

Network (per-session addressing):

Agent IP:  10.77.{N}.1/32  (N = session index, 1-254)
Client IP: 10.77.{N}.2/32

telad file sharing -- sandboxed file transfer over the WireGuard tunnel.

Purpose:

When enabled in the machine config, telad listens on TCP port 17377
inside the gVisor netstack. Authorized clients can list, download,
upload, and delete files within a single declared directory.

All operations are confined to the sandbox directory. Path traversal,
symlinks, and system directories are rejected. File sharing is off
by default and must be explicitly enabled per machine.

Security:

• Path validation on every operation (no caching).
• Symlinks are never followed.
• System directories are rejected at startup.
• Extension filtering (allowlist and blocklist).
• Per-file and total size limits enforced before writing.
• Checksums validated after upload.
• Connection limit and idle timeout.

Invariants:

• File sharing must not be enabled without explicit config.
• No file operation may escape the sandbox directory.
• The hub never sees file contents (zero-knowledge relay).

Index

• Constants
• func Main()
• func ResetForTesting()
• func Run(ctx context.Context, cfg *Config) error
• func SetActiveConfig(cfg *Config, path string)
• func SetVersion(v string)
• type Config
  • func Load(path string) (*Config, error)

Constants

const FileSharePort = 17377

FileSharePort is the fixed TCP port for file sharing inside the tunnel.

Functions

func Main

func Main()

Main is the entry point for the telad binary. The cmd/telad shim calls this; tests do not -- they call Run() directly with an in-process configFile.

func ResetForTesting

func ResetForTesting()

── Test support ────────────────────────────────────────────────────

ResetForTesting wipes every piece of package-level mutable state in the agent (active config, stop channel, reregister flag, verbose flag) so the next test run starts from a clean slate. Tests call this in t.Cleanup. Production code never calls it.

func Run

func Run(ctx context.Context, cfg *Config) error

Run launches one goroutine per machine in cfg and blocks until ctx is cancelled. When ctx fires, the global shutdown signal closes and each per-machine reconnect loop exits cleanly. Returns nil on a clean shutdown; the function does not currently surface per-machine errors (they are logged), matching the behavior of the original runMultiMachine.

func SetActiveConfig

func SetActiveConfig(cfg *Config, path string)

SetActiveConfig stores cfg as the active configuration the management protocol reads from. Production code calls this from Main() right before invoking Run; tests may call it from teststack to point the management protocol at a test-supplied config.

func SetVersion

func SetVersion(v string)

SetVersion overrides the package-level version string. Called once from the cmd/telad shim before Main() so log lines, registration messages, and the self-update channel comparison see the real linker-supplied version.

Types

type Config

type Config = configFile

Config is the parsed agent YAML configuration. Exported only so the test harness in internal/teststack can pass a config in without going through a YAML round-trip on disk. Production code uses Load() and passes the result straight to Run().

func Load

func Load(path string) (*Config, error)

Load reads and parses an agent YAML config file from disk. Returns a *Config that can be passed to Run().