# fairvisor connect

- Canonical URL: https://docs.fairvisor.com/docs/cli/connect/
- Section: docs
- Last updated: n/a
> Register this edge with the Fairvisor SaaS control plane.


`fairvisor connect` registers the edge with the SaaS control plane, receives an `edge_id`, downloads the initial policy bundle, and writes the resulting credentials to an env file.

## Synopsis

```
fairvisor connect [--token=TOKEN] [--url=URL] [--output=PATH]
```

## Options

| Flag | Env var | Default | Description |
|---|---|---|---|
| `--token` | `FAIRVISOR_EDGE_TOKEN` | (prompted) | Registration bearer token from SaaS dashboard |
| `--url`, `--saas-url` | `FAIRVISOR_SAAS_URL` | `https://api.fairvisor.com` | SaaS API base URL |
| `--output` | — | `/etc/fairvisor/edge.env` | Path to write credentials env file |

If `--output` path is not writable, the command falls back to `./edge.env` in the current directory.

## What it does

The command performs three steps:

### Step 1: Register

```
POST {saas_url}/api/v1/edge/register
Authorization: Bearer {token}
Content-Type: application/json

{"version": "0.1.0"}
```

Expected response:

```json
{ "edge_id": "edge-abc123" }
```

### Step 2: Write env file

Creates the output file with:

```bash
FAIRVISOR_EDGE_ID=edge-abc123
FAIRVISOR_EDGE_TOKEN=<your-token>
FAIRVISOR_SAAS_URL=https://api.fairvisor.com
```

### Step 3: Download initial bundle

```
GET {saas_url}/api/v1/edge/config
Authorization: Bearer {token}
```

The bundle JSON is written to `/etc/fairvisor/policy.json`.

## Interactive mode

By default, the command prompts for missing values:

```
$ fairvisor connect
Enter registration token: ****
Enter SaaS URL [https://api.fairvisor.com]:
Registering...
Edge ID: edge-abc123
Wrote credentials to /etc/fairvisor/edge.env
Downloaded initial policy bundle
```

## Non-interactive mode

Set `CI=true` or `FAIRVISOR_NON_INTERACTIVE=1` to skip prompts and fail with exit code 3 if any required value is missing.

```bash
FAIRVISOR_EDGE_TOKEN=tok-xxx \
CI=true \
fairvisor connect --output /etc/fairvisor/edge.env
```

## Using the env file

After connecting, source the env file before starting the container:

```bash
# Docker
docker run -d \
  --env-file /etc/fairvisor/edge.env \
  -v /etc/fairvisor/policy.json:/etc/fairvisor/policy.json:ro \
  ghcr.io/fairvisor/fairvisor-edge:latest
```

Or mount it as a Kubernetes secret (see [Helm deployment](/docs/deployment/helm/)).

## Exit codes

| Code | Meaning |
|---|---|
| `0` | Registration successful, env file written |
| `1` | Failed to write env file |
| `2` | Network error or HTTP 4xx/5xx from SaaS |
| `3` | Required token or URL not provided |