# Agent Commands

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

Source: https://railgrid.ai/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 `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

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

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

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

```bash
kubectl railgrid 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/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`.