# Agent Commands

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

Source: https://faros.sh/docs/reference/cli/agent/


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

```bash
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`:

| Flag | Description |
|:-----|:------------|
| `--hub-url` | Hub URL to dial. |
| `--token` | One-time join token from `edge create`. |
| `--hub-kubeconfig` | Alternative to `--token`: a kubeconfig with access to the hub. |
| `--edge-name` | Name of the edge this agent serves. |
| `--type` | `kubernetes` (default) or `server`. |
| `--labels key=value` | Labels to report. |
| `--kubeconfig`, `--context` | Local cluster access (kubernetes type). |
| `--ssh-proxy-port` | Local SSH port to proxy for server edges (default 22). |
| `--ssh-user`, `--ssh-password`, `--ssh-private-key` | SSH credentials for server edges. |
| `--hub-insecure-skip-tls-verify` | Skip hub TLS verification (dev). |
| `--debug-addr` | Bind address for pprof/healthz. |

## agent join

```bash
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

```bash
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:

```bash
kubectl faros install --type server --hub-url https://hub.example.com --edge-name my-vps --token REPLACE_WITH_JOIN_TOKEN
```

| Flag | Description |
|:-----|:------------|
| `--type` | `kubernetes` (default) or `server`. |
| `--hub-url`, `--edge-name`, `--token` | Required. |
| `--kubeconfig` | Target cluster (kubernetes type). |
| `--dry-run` | Print 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`.