agent

package
v0.2.28 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 30, 2026 License: Apache-2.0 Imports: 40 Imported by: 0

Documentation

Overview

Package agent implements the railgrid agent that connects edges to the hub.

Index

Constants

View Source 
const DefaultRunnerUser = "railgrid-runner"

DefaultRunnerUser is the dedicated system account harness runners run as when the operator named none. Creating it is what keeps the DEFAULT path working: with mode auto, a machine that has Claude Code installed is a harness host, so refusing to start for lack of a flag would turn the default into a failure.

Variables

This section is empty.

Functions

func AgentConfigPath 

func AgentConfigPath(edgeName string) (string, error)

AgentConfigPath returns the path for the per-edge agent config file. Default location: ~/.railgrid/agent-<edgeName>.json

func AgentConfigPathForHome 

func AgentConfigPathForHome(home, edgeName string) string

AgentConfigPathForHome returns the per-edge config path under home. It is used by installers that provision a service for a different local account (for example a root-installed launchd daemon running as a worker user).

func AgentCredentialPath added in v0.2.7 

func AgentCredentialPath(edgeName string) (string, error)

AgentCredentialPath returns where the enrolment bundle is stored.

func AgentCredentialPathForHome added in v0.2.7 

func AgentCredentialPathForHome(home, edgeName string) string

AgentCredentialPathForHome is AgentCredentialPath under an explicit home, for installers that run as one user and write for another.

func AgentKubeconfigPath 

func AgentKubeconfigPath(edgeName string) (string, error)

AgentKubeconfigPath returns the path for the per-edge agent kubeconfig file. Default location: ~/.railgrid/agent-<edgeName>.kubeconfig

func AgentKubeconfigPathForHome 

func AgentKubeconfigPathForHome(home, edgeName string) string

AgentKubeconfigPathForHome returns the per-edge kubeconfig path under home. See AgentConfigPathForHome for why installers need this variant.

func AgentKubeconfigSecretName 

func AgentKubeconfigSecretName(edgeName string) string

AgentKubeconfigSecretName returns the name of the Secret used to persist the hub kubeconfig for the given edge when running in-cluster.

func DeleteAgentCredential added in v0.2.7 

func DeleteAgentCredential(edgeName string) error

DeleteAgentCredential removes a saved bundle.

func DeleteAgentKubeconfig 

func DeleteAgentKubeconfig(edgeName string) error

DeleteAgentKubeconfig removes a previously saved agent kubeconfig from disk.

func EnsureRunnerAccount added in v0.2.8 

func EnsureRunnerAccount(name string) (localuser.Account, error)

EnsureRunnerAccount resolves the local account harness runners run as, CREATING a dedicated system account when name is the default and does not exist yet. A named account is never created: an operator who mistyped --runner-user must be told, not given a new account they did not ask for.

Linux only. On macOS the LaunchDaemon's worker account is the runner account, so there is nothing to create and --runner-user is not accepted.

func IsInCluster 

func IsInCluster() bool

IsInCluster returns true when the process is running inside a Kubernetes Pod.

func LoadAgentCredential added in v0.2.7 

func LoadAgentCredential(edgeName string) (tunnel.Credential, bool, error)

LoadAgentCredential reads a previously saved bundle. A missing file is not an error the caller should treat as fatal: it simply means this agent has not enrolled yet and must present its join token.

func LoadAgentKubeconfig 

func LoadAgentKubeconfig(edgeName string) (string, error)

LoadAgentKubeconfig reads a previously saved agent kubeconfig from disk. Returns an empty string without error if the file does not exist yet.

func LoadCredentialFromSecret added in v0.2.7 

func LoadCredentialFromSecret(edgeName string) (tunnel.Credential, bool, error)

LoadCredentialFromSecret reads a previously saved bundle from the agent's in-cluster Secret. Absent is not an error: it means this pod has not enrolled yet.

func LoadKubeconfigFromSecret 

func LoadKubeconfigFromSecret(edgeName string) (string, error)

LoadKubeconfigFromSecret reads the hub kubeconfig from the in-cluster Secret. Returns ("", nil) when the Secret does not exist yet (first boot before token exchange).

func ParseHarnessSetting added in v0.2.8 

func ParseHarnessSetting(raw string) (harnessplane.Setting, error)

ParseHarnessSetting validates a --harness value ("auto", "none", or a comma-separated list of harness names) into the setting the plane seeds its cache with. Exported so `railgrid agent join`, `railgrid agent install` and `railgrid edge create` all refuse the same typos at the same moment.

func SaveAgentConfigAt 

func SaveAgentConfigAt(path string, cfg AgentConfig) error

SaveAgentConfigAt writes a persisted agent config at path with owner-only permissions. Callers that install for another account should chown the file to that account after this function returns.

func SaveAgentConfigWithCluster 

func SaveAgentConfigWithCluster(edgeName, hubURL, token, cluster string) error

SaveAgentConfigWithCluster persists the durable agent token and its kcp cluster context so the agent can reconnect without the bootstrap join token after the first successful auth.

func SaveAgentCredential added in v0.2.7 

func SaveAgentCredential(edgeName string, credential tunnel.Credential) error

SaveAgentCredential persists the bundle with the same restrictive rewrite the kubeconfig used (writeCredentialFile), because it holds a live bearer.

func SaveAgentKubeconfig 

func SaveAgentKubeconfig(edgeName, kubeconfigB64 string) error

SaveAgentKubeconfig decodes the base64-encoded kubeconfig returned by the hub (via X-Railgrid-Agent-Kubeconfig header) and persists it to disk so the agent can reconnect without the bootstrap join token after the first successful auth.

func SaveCredentialToSecret added in v0.2.7 

func SaveCredentialToSecret(edgeName string, credential tunnel.Credential) error

SaveCredentialToSecret persists the agent's enrolment bundle into its in-cluster Secret so it survives a pod restart. A pod's filesystem does not.

func SaveKubeconfigToSecret 

func SaveKubeconfigToSecret(edgeName, kubeconfigData string) error

SaveKubeconfigToSecret writes the hub kubeconfig to the in-cluster Secret so that it survives a pod restart.

func ValidateAgentKubeconfig 

func ValidateAgentKubeconfig(kubeconfigPath string, insecureSkipTLS bool) error

ValidateAgentKubeconfig checks whether the saved kubeconfig still has valid credentials by attempting a lightweight API call. Returns an error only if authentication definitively fails (401 Unauthorized — token revoked, e.g. after Edge recreation). All other errors (403 Forbidden, timeouts, network errors) return nil because they don't prove the token is invalid — the hub may be temporarily unreachable or the RBAC may not permit the probe call. When insecureSkipTLS is true, TLS certificate verification is disabled.

Types

type Agent 

type Agent struct {
	// contains filtered or unexported fields
}

Agent is the railgrid agent that connects an edge to the hub.

func New 

func New(opts *Options) (*Agent, error)

New creates a new agent.

func (*Agent) Run 

func (a *Agent) Run(ctx context.Context) error

Run starts the agent and blocks until the context is cancelled.

type AgentConfig 

type AgentConfig struct {
	HubURL  string `json:"hubURL"`
	Token   string `json:"token"`
	Cluster string `json:"cluster,omitempty"`
}

AgentConfig holds the locally persisted agent configuration. It is written to disk after the first successful join-token authentication so that the agent can reconnect on restart without needing the bootstrap join token again.

func LoadAgentConfig 

func LoadAgentConfig(edgeName string) (*AgentConfig, error)

LoadAgentConfig reads a previously saved agent config from disk. Returns nil without error if the config file does not exist yet.

type AgentType 

type AgentType string

AgentType discriminates which connectable resource the agent registers and serves through the hub. Host agents share the same tunnel and Service path; only LinuxServer exposes the optional SSH bridge. 

const (
	// AgentTypeKubernetes connects a Kubernetes cluster (registers a KubernetesCluster).
	AgentTypeKubernetes AgentType = "kubernetes"
	// AgentTypeServer connects a bare-metal Linux host via SSH
	// (registers a LinuxServer).
	AgentTypeServer AgentType = "server"
	// AgentTypeMacOS connects a macOS host as a service-only edge. It registers
	// a MacOSServer and deliberately does not probe, generate, or upload SSH
	// credentials.
	AgentTypeMacOS AgentType = "macos"
)

type Options 

type Options struct {
	HubURL        string
	HubKubeconfig string
	HubContext    string
	TunnelURL     string // Separate URL for reverse tunnel (defaults to hubConfig.Host)
	Token         string
	EdgeName      string
	Kubeconfig    string
	Context       string
	Labels        map[string]string
	// Type controls whether the agent registers as a Kubernetes, Linux server,
	// or macOS service edge. Defaults to AgentTypeKubernetes.
	Type AgentType
	// InsecureSkipTLSVerify disables TLS certificate verification for the hub
	// connection. Should only be used in development/testing; never in production.
	InsecureSkipTLSVerify bool
	// SSHProxyPort is the local port of the SSH daemon the agent proxies to.
	// Defaults to 22; override in tests to avoid conflicts with the host sshd.
	SSHProxyPort int
	// SSHUser is the SSH username to authenticate as on server-type edges.
	// Defaults to the current user if not set.
	SSHUser string
	// SSHPassword is the SSH password for password-based authentication.
	// Prefer SSHPrivateKeyPath for better security.
	SSHPassword string
	// SSHPrivateKeyPath is the path to an SSH private key file for key-based auth.
	SSHPrivateKeyPath string
	// Cluster is the kcp logical cluster path (e.g., "root:railgrid:user-default").
	// If not set, it's extracted from the SA token (for kubeconfig-based auth)
	// or defaults to "default" (for static token auth).
	Cluster string
	// UsingSavedKubeconfig is set to true when the agent loaded a saved
	// kubeconfig from a previous join-token registration. When true, edge
	// registration is skipped (the edge was already registered).
	UsingSavedKubeconfig bool
	// DebugAddr, if non-empty, is the bind address for the agent's debug
	// HTTP server. It exposes /healthz and the standard /debug/pprof/*
	// endpoints. Use "127.0.0.1:6060" for local-only access; bind to a
	// non-loopback address only when port-forwarding is not an option.
	DebugAddr string
	// SvcAllowedCIDRs are the CIDRs (e.g. "192.168.1.0/24") the /svc proxy may
	// dial besides loopback and, in kubernetes mode, cluster-DNS names. A
	// Service's spec.host outside this set is refused (or warned about, per
	// SvcPolicy). Link-local, unspecified and multicast addresses are never
	// dialable even if listed. Flag: --svc-allow-cidr (repeatable); env:
	// RAILGRID_AGENT_SVC_ALLOW_CIDR (comma-separated).
	SvcAllowedCIDRs []string
	// SvcPolicy is what the /svc proxy does with a target outside the allowed
	// set: "enforce" (403, never dialed), "warn" (dialed, logged, response
	// carries X-Railgrid-Svc-Policy: warn) or "allow-any" (allow list disabled,
	// logged at startup). Defaults to "warn" in this release; the next release
	// flips the default to "enforce". Flag: --svc-policy; env: RAILGRID_AGENT_SVC_POLICY.
	SvcPolicy string
	// Harness SEEDS which coding harnesses this machine offers: "auto" (the
	// default — every harness installed on the machine), "none", or a
	// comma-separated list of claude,codex. It only seeds: the setting lives on
	// the edge object's spec.harness, the agent caches the last value it
	// observed, and the cache is written before this flag is ever consulted. An
	// install-time opt-out that STICKS is `railgrid edge create --harness none`.
	// Flag: --harness; env: RAILGRID_AGENT_HARNESS.
	Harness string
	// RunnerUser is the non-root local account a harness runner runs as. A root
	// agent (the systemd unit) needs one, and when it is empty a dedicated
	// railgrid-runner system account is created rather than refusing — the
	// default path must never run a harness as root and must never fail for
	// lack of a flag. Ignored for a non-root agent (the macOS LaunchDaemon
	// worker), which runs runners as itself. Flag: --runner-user; env:
	// RAILGRID_AGENT_RUNNER_USER.
	RunnerUser string
}

Options holds configuration for the agent.

func NewOptions 

func NewOptions() *Options

NewOptions returns default agent options.

Source Files

View all Source files

Directories

Path Synopsis
Package discovery detects HTTP services running on the edge host next to the agent (e.g.
 Package discovery detects HTTP services running on the edge host next to the agent (e.g.
Package harnessplane makes a machine a harness host for its workspace.
 Package harnessplane makes a machine a harness host for its workspace.
Package reconciler reconciles workloads on the agent side: it watches the edge's Placements in the tenant workspace and materializes each as a local Deployment.
 Package reconciler reconciles workloads on the agent side: it watches the edge's Placements in the tenant workspace and materializes each as a local Deployment.
runner
supervisor
Package supervisor runs one long-lived child process for a supervised harness runner and keeps it running.
 Package supervisor runs one long-lived child process for a supervised harness runner and keeps it running.
Package status reports agent status back to the hub.
 Package status reports agent status back to the hub.
Package tunnel implements reverse-dial tunneling between agent and hub.
 Package tunnel implements reverse-dial tunneling between agent and hub.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.