Skip to content
Railgrid Docs
Sections
Open console

Enter a topic to search documentation.

    Agent Commands

    Run, install, and upgrade the Railgrid agent on edges.

    The agent is the process that runs on your edge (in a pod on a Kubernetes cluster, or as a systemd service on a Linux host) and dials out to the hub. The railgrid agent command group manages its lifecycle; the railgrid edge create / join-command output prints ready-to-paste variants of these commands with your join token filled in.

    agent run

    Terminal
    kubectl railgrid agent run --hub-url https://hub.example.com --edge-name home-lab --token REPLACE_WITH_JOIN_TOKEN

    Runs the agent as a foreground process. This is what container images, dev loops, and e2e tests use — for production installs prefer agent join, which sets up a persistent service. After the first successful join the agent persists its issued kubeconfig (as an in-cluster Secret on Kubernetes, or on disk for servers) and reconnects on restart without needing the bootstrap token again.

    Shared flags on run and join:

    FlagDescription
    --hub-urlHub URL to dial.
    --tokenOne-time join token from edge create.
    --hub-kubeconfigAlternative to --token: a kubeconfig with access to the hub.
    --edge-nameName of the edge this agent serves.
    --typekubernetes (default) or server.
    --labels key=valueLabels to report.
    --kubeconfig, --contextLocal cluster access (kubernetes type).
    --ssh-proxy-portLocal SSH port to proxy for server edges (default 22).
    --ssh-user, --ssh-password, --ssh-private-keySSH credentials for server edges.
    --hub-insecure-skip-tls-verifySkip hub TLS verification (dev).
    --debug-addrBind address for pprof/healthz.

    agent join

    Terminal
    sudo kubectl railgrid agent join --hub-url https://hub.example.com --edge-name my-vps --token REPLACE_WITH_JOIN_TOKEN --type server

    Installs the agent persistently. Requires --edge-name and one of --token / --hub-kubeconfig.

    • --type server — writes a systemd unit railgrid-agent-<edge>.service that runs railgrid agent run, then enables and starts it. Needs root.
    • --type kubernetes — applies Kubernetes manifests to the target cluster: namespace railgrid-agent, a per-edge ServiceAccount, the railgrid-edge-agent ClusterRole/Binding, and a Deployment railgrid-agent-<edge>. The agent image defaults to ghcr.io/railgrid/railgrid-agent at the CLI’s version (override with RAILGRID_AGENT_IMAGE / RAILGRID_AGENT_TAG / RAILGRID_AGENT_PULL_POLICY).

    agent install / agent uninstall

    agent install writes a systemd unit for a host-mode agent from a hub kubeconfig (--hub-kubeconfig and --edge-name required; --unit-name defaults to railgrid-agent-<edge>). agent uninstall stops and disables the service and removes the unit file. Both need root.

    agent upgrade

    Terminal
    kubectl railgrid agent upgrade home-lab            # kubernetes edge: patch the Deployment image
kubectl railgrid agent upgrade my-vps              # server edge: prints binary-replace steps

    For Kubernetes edges, patches the railgrid-agent-<edge> Deployment to the new image tag and (with --wait, the default) waits for the rollout and for the edge to report the new agent version. Flags: --tag (defaults to the CLI’s own version), --wait.

    railgrid install

    A separate top-level one-shot installer, useful for provisioning scripts:

    Terminal
    kubectl railgrid install --type server --hub-url https://hub.example.com --edge-name my-vps --token REPLACE_WITH_JOIN_TOKEN

    FlagDescription
    --typekubernetes (default) or server.
    --hub-url, --edge-name, --tokenRequired.
    --kubeconfigTarget cluster (kubernetes type).
    --dry-runPrint what would be applied instead of applying it.

    For server it writes /etc/railgrid/agent.yaml plus a railgrid-agent.service systemd unit; for kubernetes it renders hardened manifests (namespace, ServiceAccount, RBAC, Deployment with resource limits) and applies them with kubectl — or prints them with --dry-run.