edgible agent

Manage the local Edgible agent (daemon installations only)

`edgible agent status`

Check local agent status

edgible agent status [flags]

Flag	Description
`--watch`	Watch status changes in real-time

Examples

edgible agent status
edgible agent status --watch    # re-render whenever the agent's state changes

Reports what this host knows: the recorded install type and the service manager’s view of the unit. For what the control plane thinks of the device, use edgible device list; the two disagreeing is itself the diagnosis.

`edgible agent install`

Install the local agent: with sudo as an always-on system service, without sudo under your own account

edgible agent install [flags]

Flag	Description
`--device-type <deviceType>`	Device type: serving (default)
`--dev`	Run in development mode (foreground, no daemon)
`--local`	Use a local agent build from the source checkout (development only)
`--auto-install-deps`	Install missing dependencies (WireGuard, Caddy, etc.) without prompting
`--skip-dep-check`	Skip the dependency check entirely (for pre-provisioned hosts/CI images that already have the tools)
`--upload-diagnostics`	If this command fails, upload the redacted diagnostics file to Edgible support (or set EDGIBLE_DIAGNOSTICS_UPLOAD=1). Off by default; the file is always written locally
`--vm`	Install the agent inside an isolated QEMU VM (serving, Linux host)
`--vm-memory <mb>`	VM memory in MB (with —vm; default 4096)
`--vm-cpus <n>`	VM vCPU count (with —vm; default 2)
`--vm-base-image <path>`	Override the guest base image qcow2 (with —vm)
`--device <id>`	Bind to this existing device, by id (see notes for why not a name)
`--device-name <name>`	Create a new device with this name and bind to it; alternative to —device
`--device-password <password>`	One-time device password; can use EDGIBLE_DEVICE_PASSWORD
`-y, --yes`	Never prompt (CI/VMs): use config, —device-name to create a device, or —device/—device-password

Examples

sudo edgible agent install
# An always-on system service: starts at boot, runs when nobody is logged
# in. On Linux the tunnel is the kernel's WireGuard.

edgible agent install
# Under your own account, no sudo: a per-user service with the agent's
# built-in tunnel. The web server that puts your apps online comes with
# the agent, so nothing is installed on the machine and its network
# settings are unchanged. It stops when you log out unless you enable
# lingering (Linux) — the command tells you exactly that, and the one line
# that changes it, before it starts.

edgible agent install --device-name web-01 --yes
# CI / cloud-init. Creates the device, then installs without ever asking.

EDGIBLE_DEVICE_ID=... EDGIBLE_DEVICE_PASSWORD=... edgible agent install --yes
# The sessionless path: redeems a one-time device credential. Needs no
# login and no organization in config; the backend derives both from the
# device row. Same as passing --device/--device-password.

edgible agent install --vm
# The agent runs inside a QEMU guest; the host only supervises it.

sudo edgible agent install --skip-dep-check --yes
# A pre-provisioned host that already carries WireGuard/Caddy/iptables and
# whose paths the checker cannot see. Only a sudo install looks for those:
# without sudo the web server comes with the agent.

Sudo or not is the only install choice. Before anything is written the command says what that choice means on this machine (what runs, as whom, what happens when you log out) and asks whether to continue. --yes skips the question, never the summary. A machine can hold one agent: installing it the other way round stops first and names the uninstall that clears the way.

--vm — VM-isolated install. Serving only, Linux + QEMU only. Installs the agent inside the guest, not on this host.
--dev — Development mode: run in the foreground, no daemon at all.

--device-type says what kind of device this is, not how the agent is installed. It has to be right at install time because it selects which agent build is copied.

Exit codes are a contract here: agent install exits 0 if and only if the agent ended up installed and running. Every abort (a failed pre-flight, missing dependencies, a service that never came online, a declined prompt) exits non-zero and writes a redacted diagnostics file whose path it prints. The file stays local unless you pass --upload-diagnostics.

Which entry point is yours

One machine, one device — the default. Everything in one command:
Terminal window
```
sudo edgible agent install     # always-on system service
edgible agent install          # under your own account, no sudo
```
Whether you use sudo is the only choice: it decides how the agent is installed, and the command tells you what that means before it starts.
Baking an image (a VM template, a CI runner, an appliance) — the device does not exist yet and must not be baked in. Split the slow, identity-free half from the identity-bound half:
Terminal window
```
edgible agent provision              # in the image build: files + unit
edgible agent enroll --device-name web-01   # on first boot: bind + start
```
provision needs no login at all. enroll fails loudly if nothing was provisioned, rather than silently doing a full install.
You want the agent contained rather than on the host (Linux + QEMU):
Terminal window
```
edgible agent install --vm
```

What the sudo choice decides

Whether you use sudo is the only install choice, and it settles everything else:

You run	What you get
`sudo edgible agent install`	A system service. It starts at boot and keeps running when nobody is logged in. On Linux the secure tunnel uses the machine’s kernel WireGuard, and the web server that fronts your apps is installed on the host.
`edgible agent install`	A service under your own account, with the agent’s files in your own data directory and its bundled tunnel and web server. Nothing in the machine’s network settings changes, and nothing is installed system-wide. Serving devices only.

--device-name follows the shared resource-name rule: lowercase letters, digits and hyphens, 1–63 characters, starting and ending with a letter or digit. A name derived from the hostname is slugified to fit.

A machine can hold one agent. Installing it the other way round stops the existing one first and names the uninstall that clears the way (EDG145).

Installing without sudo is covered end to end in Install the agent without sudo.

`edgible agent provision`

Provision agent files + daemon unit without a device (identity-free; pair with agent enroll)

edgible agent provision [flags]

Flag	Description
`--type <type>`	Override the service type (systemd); normally decided by whether you used sudo
`--upload-diagnostics`	If this command fails, upload the redacted diagnostics file to Edgible support (or set EDGIBLE_DIAGNOSTICS_UPLOAD=1). Off by default; the file is always written locally
`--device-type <deviceType>`	Device type: serving (default)
`--local`	Use a local agent build from the source checkout (development only)
`--auto-install-deps`	Install missing dependencies (WireGuard, Caddy, etc.) without prompting
`-y, --yes`	Never prompt (CI/VMs); pick the daemon type for this platform

Examples

edgible agent provision --yes --type systemd
# The image-bake half: copy the agent build, run its production install,
# write the daemon unit. Creates no device and starts nothing.

edgible agent provision --yes --local
# Provision from a local agent build instead of the release channel
# (development only); pair it with 'agent enroll --local'.

Needs NO login: nothing here talks to the control plane, which is why the EDG220 session check is skipped for this verb. Pair it with agent enroll on first boot; enroll does not run if this never did.

Which entry point is yours

One machine, one device — the default. Everything in one command:
Terminal window
```
sudo edgible agent install     # always-on system service
edgible agent install          # under your own account, no sudo
```
Whether you use sudo is the only choice: it decides how the agent is installed, and the command tells you what that means before it starts.
Baking an image (a VM template, a CI runner, an appliance) — the device does not exist yet and must not be baked in. Split the slow, identity-free half from the identity-bound half:
Terminal window
```
edgible agent provision              # in the image build: files + unit
edgible agent enroll --device-name web-01   # on first boot: bind + start
```
provision needs no login at all. enroll fails loudly if nothing was provisioned, rather than silently doing a full install.
You want the agent contained rather than on the host (Linux + QEMU):
Terminal window
```
edgible agent install --vm
```

`edgible agent enroll`

Bind a device to an already-provisioned agent and start it (the identity-bound half of install)

edgible agent enroll [flags]

Flag	Description
`--type <type>`	Service type the agent was provisioned as (systemd); normally read from the provision
`--upload-diagnostics`	If this command fails, upload the redacted diagnostics file to Edgible support (or set EDGIBLE_DIAGNOSTICS_UPLOAD=1). Off by default; the file is always written locally
`--device-type <deviceType>`	Device type: serving (default)
`--local`	Pair with a —local provision (development only)
`--device <id>`	Bind to this existing device, by id (see notes for why not a name)
`--device-name <name>`	Create a new device with this name and bind to it; alternative to —device
`--device-password <password>`	One-time device password; can use EDGIBLE_DEVICE_PASSWORD
`-y, --yes`	Never prompt (CI/VMs): use config, —device-name to create a device, or —device/—device-password

Examples

edgible agent enroll --device-name web-01 --yes
# First boot of a provisioned image: create the device, write its
# credentials, start the agent, verify it came online.

edgible agent enroll --device dev_abc123 --device-password "$PW" --yes
# Bind to a device someone already created ('edgible device create' prints
# the password once). Needs no login — the credential carries its own
# identity.

edgible agent enroll
# Interactively pick an existing device on a host that was provisioned
# earlier.

Fails, and never falls back to a full install, if agent provision did not run here first. That is deliberate: a silent fallback would mask a stale image and re-introduce the slow path provisioning exists to remove.

Which entry point is yours

One machine, one device — the default. Everything in one command:
Terminal window
```
sudo edgible agent install     # always-on system service
edgible agent install          # under your own account, no sudo
```
Whether you use sudo is the only choice: it decides how the agent is installed, and the command tells you what that means before it starts.
Baking an image (a VM template, a CI runner, an appliance) — the device does not exist yet and must not be baked in. Split the slow, identity-free half from the identity-bound half:
Terminal window
```
edgible agent provision              # in the image build: files + unit
edgible agent enroll --device-name web-01   # on first boot: bind + start
```
provision needs no login at all. enroll fails loudly if nothing was provisioned, rather than silently doing a full install.
You want the agent contained rather than on the host (Linux + QEMU):
Terminal window
```
edgible agent install --vm
```

`edgible agent start`

Start the local agent (uses the device configured during install)

edgible agent start [flags]

Flag	Description
`--passthrough`	Run agent with interactive output (required for sudo password prompt)
`--debug`	Enable debug logging
`--root`	Run agent with sudo/root privileges (required for WireGuard and iptables management)
`--auto-install-deps`	Install missing dependencies without prompting (for scripts/CI)
`--skip-dep-check`	Skip the dependency check entirely (host is known to have the required tools)

Examples

edgible agent start
edgible agent start --root         # WireGuard/iptables management needs it
edgible agent start --debug        # verbose agent logging for one run
edgible agent start --skip-dep-check --auto-install-deps   # scripted start

Runs as the device chosen at install time and no other — device selection lives in ‘agent install’/‘agent enroll’. To point this host at a different device, re-run one of those.

`edgible agent stop`

Stop the local agent

edgible agent stop [flags]

Examples

edgible agent stop

Stops the service (or powers the VM down gracefully, on a --vm install). The device stays enrolled and the unit stays installed — use agent uninstall to undo the install itself.

`edgible agent restart`

Restart the local agent

edgible agent restart [flags]

Examples

edgible agent restart

Use after editing agent config by hand. agent set-log-level already restarts for you unless you pass --no-restart.

`edgible agent vm`

Manage the VM-isolated agent install (edgible agent install —vm)

edgible agent vm [flags]

`edgible agent vm ssh`

Open an interactive SSH shell into the agent VM

edgible agent vm ssh [flags]

Examples

edgible agent vm ssh

Only meaningful after edgible agent install --vm. Requires sshpass on the host; the guest is reached over the forwarded port recorded in CLI config.

`edgible agent vm console`

Attach to the agent VM console (headless; use agent vm ssh)

edgible agent vm console [flags]

Examples

edgible agent vm console

The guest runs headless with no serial console wired up, so this currently just points you at edgible agent vm ssh.

`edgible agent vm build-image`

Build the guest base image used by VM-isolated installs

edgible agent vm build-image [flags]

Examples

edgible agent vm build-image

Builds the qcow2 base that agent install --vm overlays. Only available from a dev checkout — the builder script ships with the repo, not the release.

`edgible agent logs`

View agent logs

edgible agent logs [flags]

Flag	Description
`-f, --follow`	Follow log output in real-time
`-n, --lines <number>`	Number of lines to show (default: `100`)
`-l, --level <level>`	Log level filter (error, warn, info, debug, all) (default: `all`)
`-m, --module <module>`	Filter logs by module name (comma-separated for multiple modules, e.g., “agent,caddy”)
`-c, --comprehensive`	Show comprehensive diagnostics (raw output without filtering)
`--single-line`	Exclude data and error traces from output (single line per log entry)
`--stdout`	Read from stdout.log instead of agent.log
`--stderr`	Read from stderr.log instead of agent.log

Examples

edgible agent logs
edgible agent logs -f                      # follow
edgible agent logs -n 500 -l error         # last 500 lines, errors only
edgible agent logs -m agent,caddy          # only these modules
edgible agent logs --single-line | grep -i wireguard
edgible agent logs --stderr                # crash output, if it died early

The log text is the only thing on stdout, so piping and grepping work; the no logs matched that filter notice goes to stderr where it cannot be mistaken for a log line.

`edgible agent uninstall`

Uninstall the agent daemon

edgible agent uninstall [flags]

Flag	Description
`--remove-files`	Also remove agent files and configuration
`-y, --yes`	Skip the confirmation prompts

Examples

edgible agent uninstall
edgible agent uninstall --yes                  # no confirmation (CI)
edgible agent uninstall --remove-files --yes   # also delete agent files

Removes the daemon unit and clears the device credentials from CLI config. The device record in your organization is untouched — delete it with edgible device delete if you are decommissioning the machine for good.

`edgible agent set-log-level`

Set the agent log level

edgible agent set-log-level [flags]

Flag	Description
`-l, --level <level>`	Log level: debug, info, warn, or error
`--no-restart`	Do not restart the agent after updating log level

Examples

edgible agent set-log-level -l debug
edgible agent set-log-level -l info --no-restart
edgible agent set-log-level             # pick the level interactively

Writes logLevel into agent.config.json and restarts the agent so it takes effect. Pass --no-restart to batch the change with other edits and restart once.

`edgible agent reconcile`

Trigger an immediate full-state reconcile against the local running agent (debug / recovery)

edgible agent reconcile [flags]

Flag	Description
`--timeout <ms>`	Maximum time to wait for the agent to respond (default: `60000`)

Examples

edgible agent reconcile
edgible agent reconcile --json | jq '.report.errors'
edgible agent reconcile --timeout 120000    # a device with many pools

Talks to the running agent over its local control socket — it is a recovery and debugging tool, not part of normal operation; the agent reconciles on its own schedule. Exits non-zero when the agent cannot be reached or the reconcile reported stage errors.

`edgible agent setup`

Setup agent dependencies and configure the agent

edgible agent setup [flags]

Flag	Description
`--wireguard-mode <mode>`	Explicit WireGuard mode override (kernel\|userspace\|netstack); omit to let the agent resolve it at boot
`--wireguard-go-binary <path>`	Explicit wireguard-go binary override; omit to let the agent resolve ‘wireguard-go’ on PATH
`--auto-install`	Automatically install missing dependencies without prompting

Examples

edgible agent setup --auto-install
edgible agent setup --wireguard-mode userspace
edgible agent setup --wireguard-go-binary /opt/wg/bin/wireguard-go

Both —wireguard-* flags are host overrides, not defaults: omit them and nothing is recorded, so the agent resolves the mode and the binary from the platform at boot. That is almost always what you want — a pinned kernel on a host that later loses the kernel module crash-loops the device out of remote management.