Skip to content
faros Docs
Open console

Enter a topic to search documentation.

    Agent Commands

    Run, install, and upgrade the faros 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 faros agent command group manages its lifecycle; the faros edge create / join-command output prints ready-to-paste variants of these commands with your join token filled in.

    agent run

    Terminal
    kubectl faros 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 faros 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 faros-agent-<edge>.service that runs faros agent run, then enables and starts it. Needs root.
    • --type kubernetes — applies Kubernetes manifests to the target cluster: namespace faros-agent, a per-edge ServiceAccount, the faros-edge-agent ClusterRole/Binding, and a Deployment faros-agent-<edge>. The agent image defaults to ghcr.io/faroshq/faros-agent at the CLI’s version (override with FAROS_AGENT_IMAGE / FAROS_AGENT_TAG / FAROS_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 faros-agent-<edge>). agent uninstall stops and disables the service and removes the unit file. Both need root.

    agent upgrade

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

    For Kubernetes edges, patches the faros-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.

    faros install

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

    Terminal
    kubectl faros 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/faros/agent.yaml plus a faros-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.