Install on Linux

The script downloads the CLI for your architecture, installs it as /usr/bin/sxaccess, then registers the agent as a system service and starts it, as sudo sxaccess agent install and sudo sxaccess agent start would. Unless you are root, it asks for your password, so run it on its own and wait until it has finished.

Then connect the device. sxaccess start opens a browser so you can sign in, or prints the sign-in link when there is no browser to open. A server enrols with a key instead, see Headless servers.

It runs on Linux on amd64, arm64, 386 and 32-bit ARM, and it needs root rights: run it as root, or it uses sudo or doas and asks for your password. It refuses NixOS. It does not go through apt, dnf, yum or pacman, because there is no SXAccess package repository: it puts the one binary in place and registers the service.

Running it again is safe. On a machine that already has SXAccess it says so and replaces the installed version in place, which makes running it again the way to upgrade. If the registered service already runs that binary, the script restarts it; if not, it registers the service again.

The script has a single option. Anything else on its command line stops it with an error.

The script registers the agent with whichever init system the machine uses, systemd, SysV init, upstart or OpenRC, so it starts at boot. The agent commands manage it the same way on all of them; they need root, except agent info, which prints Agent service: Running while the agent runs.

The agent logs to /var/log/sxaccess/client.log, not to the journal, so journalctl shows little. To give the service a variable it reads, use sudo sxaccess agent reconfigure --service-env KEY=VALUE. It restarts a running agent by itself, and each run replaces the whole service environment; see Environment variables.

sxaccess start and sxaccess stop connect and disconnect the device without touching the service.

There is no browser on a server, so enrol it with an enrollment key. A device enrolled with a key has no owner and its session never expires, which is what a server needs. A device enrolled by signing in belongs to that member and has to sign in again when its session expires.

Pass the key with --enrollment-key (-k) for a one-off. When it comes from a secret store, point --enrollment-key-file at a file instead: that keeps the key out of ps and out of your shell history. The sxaccess command reads the file itself, so the account that runs it must be able to read the file. In a pipeline, set SX_ENROLLMENT_KEY; every flag can also be set as SX_<FLAG>. On a device that is already connected, start prints This device is already connected and does not use the key.

In a CI job that provides the key as the secret variable SX_ENROLLMENT_KEY, leave the key off the command line:

Run the agent in a container with the image and the command the dashboard shows under Add device → Docker. If you adapt that command for Compose, Kubernetes or Podman, keep what the agent needs:

• the capabilities NET_ADMIN and NET_RAW, each as its own flag: --cap-add NET_ADMIN --cap-add NET_RAW. --cap-add BPF is optional: it lets the agent use in-kernel helpers, which it otherwise replaces with user-space ones;
• the enrollment key and the device name as SX_ENROLLMENT_KEY and SX_HOSTNAME. The container reads every flag from its SX_<FLAG> variable;
• a persistent volume on /var/lib/sxaccess, so the container keeps its identity and its overlay address across restarts. Without it, every restart enrols a new device.

The container starts the agent, connects with those settings and writes the agent's log to the container's output, which docker logs shows. The command from Add device names the container sxaccess, so the commands below check it by that name. For clusters and pipelines, see Kubernetes and CI.

The installer recognises Synology: it installs to /usr/local/bin, loads the tun module and creates /dev/net/tun if it is missing. Any other appliance that runs Linux on a supported architecture installs like a server. Add it to a network as a routing device, and the resources behind it become reachable without installing anything on them.

A machine's identity is its private key, kept in /var/lib/sxaccess/default.json. Reset when that identity should not be reused: a VM that was cloned after enrolment, a machine being handed to someone else, or state that a fresh sxaccess start no longer recovers. Signing in again does not need a reset: sxaccess start renews an expired session.

The machine comes back as a new device, with a new key and a new overlay address. Starting clean uses the same steps on Linux and macOS. First disconnect, undo the DNS and route changes the agent recorded, and stop the service:

Now delete the device under Devices in the dashboard. That revokes the old key, and it frees the machine's DNS name: while the old entry exists, a new device gets that name with two numbers added.

Then delete the agent's state, which the agent creates again when it starts, and ~/.config/sxaccess, which records which identity the CLI uses. Start the service and enrol again. On a server, end with sxaccess start --enrollment-key-file <file> instead, as in Headless servers.

On Linux you remove the service, the binary and the data yourself, in this order. Stop the agent before you remove the service: sudo sxaccess agent remove unregisters it but does not stop an agent that is running.

Then delete the device under Devices in the dashboard so its key is revoked. On Synology the binary is /usr/local/bin/sxaccess instead.