# Devices

> Install the client, handle platform differences, approve and manage devices, and use the wwnet command line.

Source: https://www.widewired.com/page/docs/devices

## Device status

The device list is under **Configuration → Devices**.

| Column | Meaning |
| --- | --- |
| Device | Hostname |
| Alias | Optional display name |
| Virtual address | Overlay IP in the current network |
| Platform | Operating system and architecture |
| Approval | Pending / Approved / Blocked |
| Online | Current online state |
| Last communication | Most recent service synchronization |

Details shows static inventory: operating system, kernel, architecture, CPU model,
memory and swap capacity, interfaces, and disk capacity. It does not show live CPU,
memory, disk, or network utilization. These fields remain empty until the first report.

## Installing the client

### Desktop and server platforms

| System | Architectures | Service manager | Install location |
| --- | --- | --- | --- |
| Linux | x86-64, ARM64 | systemd; procd on OpenWrt | `/usr/local/bin`; `/usr/bin` on OpenWrt |
| macOS | Apple Silicon only | launchd | `/usr/local/bin` |
| Windows | x86-64, ARM64 | Windows service | `%ProgramData%\wwnet` |

### Prerequisites

- Administrator rights: `sudo` on Linux/macOS or an elevated PowerShell on Windows.
- `curl` on Linux/macOS.
- Outbound access to the release origin and WideWired services.
- Operating-system support for a TUN/virtual network interface.

No public IP or inbound port is required.

### Getting the install command

Open **Configuration → Devices** in the console and choose Add device. The generated command already contains the site domain and current network ID.

Linux / macOS:

```
curl -fsSL https://<your site's API domain>/wwnet/install/join/<network-id>.sh | sudo sh
```

Windows (Administrator PowerShell):

```
powershell -c "irm https://<your site's API domain>/wwnet/install/join/<network-id>.ps1|iex"
```

The angle brackets illustrate the format. Copy the complete generated command and do not substitute values manually.

The installer selects the version for the current platform, verifies the download, installs the background service and registers the device with the network ID. The device then enters **Pending**.

### Linux

Linux supports x86-64 (`x86_64` / `amd64`) and ARM64 (`aarch64` / `arm64`). The installer uses OpenWrt/procd when `/sbin/procd` and `/etc/rc.common` exist; other environments require systemd. An unmatched system is rejected.

Before installation, confirm that `/dev/net/tun` is available. On OpenWrt, also confirm that the partition containing `/usr` has enough installation space.

Inspect systemd and its logs:

```
systemctl status wwnet
journalctl -u wwnet -n 100 --no-pager
```

OpenWrt:

```
/etc/init.d/wwnet status
logread | grep wwnet
```

### macOS

Only Apple Silicon Macs are supported. `uname -m` returns `arm64` in a native Apple Silicon terminal. If it returns `x86_64`, confirm the chip under About This Mac and retry outside a Rosetta terminal.

`sudo` requests the current macOS user password. Inspect launchd with:

```
sudo launchctl list | grep wwnet
```

The client creates an automatically numbered `utun` interface. It requires no manual configuration and is removed during uninstall.

### Windows

A regular PowerShell triggers Windows elevation and continues as Administrator after confirmation; an already elevated PowerShell can run the command directly.

Windows or corporate endpoint protection may require approval on first download or execution. The installer verifies the release-manifest signature and binary SHA-256. Do not bypass a verification failure or use a program from another source.

Inspect the Windows service:

```
Get-Service wwnet
```

The client creates a wintun adapter visible under Network Connections. It requires no manual configuration and must remain enabled. Uninstall removes it automatically.

### Mobile devices

Android, iOS and HarmonyOS use the WideWired mobile app. After installing the app:

1. Select the site where the account is registered.
2. Enter the 12-character network ID shown in the console.
3. Select Connect and allow the system to create a VPN connection.
4. Return to **Configuration → Devices** and approve the new device.

A mobile device can reach overlay peers and published site routes, and can apply forward rules where it is the source device. It does not act as a peer relay, site-route device or forwarding exit, and it does not run device automation scripts.

## Managing devices

### Approving a device

A newly registered device is **Pending** and cannot communicate. Under **Configuration → Devices**, verify the hostname and platform, then approve it. Once **Approved**, the system creates links to the other devices.

The network ID is not an authentication credential, so approval is required before a device receives network access.

### Editing a device

Edit supports:

- **Alias**: display only.
- **Virtual address**: must be inside the network CIDR and unique; applies at the next configuration sync.
- **Transport protocol**: controls the transport used by direct connections.

After changing an overlay IP, update scripts, firewall rules and monitoring configuration that reference the old address.

### Blocking and unblocking

Blocking retains the device record and configuration. Existing connections may take a short time to stop. Unblocking returns the device to Approved. Blocking does not uninstall the client or mobile app.

### Peer relay

When Peer relay is enabled, the device can forward traffic for two other devices that cannot connect directly. It uses the device and its bandwidth and does not incur cloud-relay charges.

Selection still depends on platform capability and reachability. Disable the option on bandwidth-constrained or metered devices.

### Deleting a device

Console deletion removes the device from the network and deletes its device record, but it does not remove the host program. To clean up the host, run:

```
wwnet uninstall
```

## Command-line reference

Network and policy configuration lives in the console. `wwnet` handles registration, status, updates, leaving a network and uninstalling.

| Command | Purpose |
| --- | --- |
| `wwnet` | Shows the status table: network, network address and one row per peer |
| `wwnet join <network-id>` | Joins with the 12-character ID from the console |
| `wwnet leave` | Leaves the network, restores network configuration and removes the service |
| `wwnet uninstall` | Fully cleans the local installation without requiring the service |
| `wwnet update` | Checks for and installs a new version immediately |
| `wwnet version` | Shows the current version |
| `wwnet help` | Shows command usage |

`join`, `leave` and `uninstall` require Administrator rights. `leave` takes no network ID because one installation belongs to only one network at a time.

### Status and paths

Run `wwnet` directly. It prints a two-column table; column widths grow with the
content, so nothing is truncated. Human-readable output is always English.

| Field | Meaning |
| --- | --- |
| `console` | The console this device reports to; open it in a browser |
| `version` | Installed client version |
| `status` | Connection state; see the table below |
| `device name` | Local hostname |
| `device id` | Device ID, as shown in the console |
| `network name` | Network name, as shown in the console |
| `network id` | 12-character network ID |
| `network address` | This device's address inside the network |
| `peers` | One row per peer: `<name> (<network address>) - <path type>, <state>` |

A value the device cannot determine is printed as `unknown`. Path types are
`direct`, `peer relay` and `cloud relay`; states are `healthy`, `needs attention`
and `checking`.

| `status` | Meaning |
| --- | --- |
| `connected` | Connected and able to communicate with peers |
| `awaiting approval` | Registered and waiting for console approval |
| `connecting` | Fetching or applying configuration |
| `disconnecting` | Leaving and restoring local configuration |
| `paused by an administrator` | An administrator paused this device in the console |
| `needs attention` | Connectivity stopped, or the previous leave/uninstall did not finish; a `reason` row gives the detail |
| `not joined to a network` | Installed but not joined |
| `background service not running` | Background service is not running |

Statuses that need you to act carry their next step in the table: `approve at`
for a device awaiting approval, and `what to do` for a paused device or one that
needs attention. When something needs attention the table adds rows in place:
`reason` when the connection has stopped, and `stage` / `code` / `reason` / `what to do` when cleanup is incomplete.

### Updating

The client checks for updates at startup and while running, and allows forward upgrades only. Every update verifies origin, signature and integrity. Check immediately with:

```
wwnet update
```

When a version is available, the command installs it and restarts the service. A version that fails its health observation automatically rolls back. Use `wwnet version` to inspect the current version.

### Leaving a network

```
wwnet leave
```

The command disconnects the network, restores routes, DNS, firewall rules and the virtual adapter, deletes the local device identity and removes the service. To move to another network, complete `leave` before running the new network's install command; a direct second join returns `E1042`.

### Uninstalling

```
wwnet uninstall
```

`uninstall` stops the service, restores network configuration and then removes the program and local data. It does not depend on the service, so it also handles a service that cannot start or an incomplete previous cleanup.

If restoration is incomplete, the client returns `E1060` and reports `needs attention`. Repeat `wwnet uninstall`; do not remove program or recovery data before success.

### Diagnostics

Crash reports and error logs remain locally with bounded retention and are not
uploaded automatically. There is no local diagnostic bundle to export: when you
need help, send the `wwnet` output together with the error code and time. See
[getting support](https://www.widewired.com/page/docs/support).

### Exit codes

| Exit code | Meaning |
| --- | --- |
| `0` | Success |
| `1` | Operation failed; read the error message |
| `2` | Invalid command or argument |
| `4` | Administrator rights required |

## Quick troubleshooting

| Symptom | Check and action |
| --- | --- |
| The install command fails immediately | Check Administrator rights, architecture, `curl` and outbound access, then copy the complete command again from **Configuration → Devices** |
| Signature or SHA-256 verification fails | Do not bypass verification; retry on another network and contact support if persistent |
| Linux has no `/dev/net/tun` | Load TUN support or use a kernel/host environment that provides it |
| macOS reports that Intel is unsupported | The current client requires Apple Silicon; check whether the terminal is running under Rosetta |
| Windows endpoint protection blocks the program | Have an administrator allow it under organizational policy; do not use an unverified substitute |
| `status` is `awaiting approval` | Approve the device in the console; this is the normal post-registration state |
| An approved device remains offline | Inspect the `peers` rows in `wwnet`, the service and Last communication |
| Access fails after changing the virtual address | Wait for configuration sync, check uniqueness and update every caller |
| `status` is `background service not running` | Inspect the platform service and logs; the corresponding code is `E1002` |
| `status` is `connecting` | Wait for configuration sync; for `E1003`, do not repeatedly restart the service |
| `status` is `error` | Read the `reason` row for the detailed cause and code |
| `needs attention` | Repeat `wwnet uninstall`; do not remove related directories before success |

See [troubleshooting](https://www.widewired.com/page/docs/troubleshooting) for every error code.