CloudAddress -- User Guide v1.0.0

Applies to Cloud Spectra 1.0.0. Every command and flag on this page is a command or flag of cloudspectra_relay_client 1.0.0; run any command with --help for its full option list.

This guide covers everything you operate in CloudAddress: installing the client, creating relays in each cloud, connecting and moving devices, routing, DNS, IPv6, firewalling, the relay's dashboard, monitoring, upgrades, the security model and troubleshooting. For a first run, start with the Quick Start; for what CloudAddress is and when to use it, see the Overview.

Concepts

Installing the client

The client is free and published for each release at https://downloads.cloudspectra.ai/gateway/<version>/clients/. For 1.0.0:

# Debian / Ubuntu
sudo apt install ./cloudspectra-relay-client_1.0.0_linux_amd64.deb
# macOS
sudo installer -pkg cloudspectra-relay-client_1.0.0_macos_arm64.pkg -target /
# Windows (Administrator PowerShell)
msiexec /i cloudspectra-relay-client_1.0.0_windows_amd64.msi
# check
cloudspectra_relay_client version

A running relay also serves the client matching its own release from its dashboard (Generate Token → Download the client).

Linux requirements. Kernel 5.10 or newer. The Linux client uses the kernel's WireGuard module by default; on a kernel without it, connect fails and names --user-mode-wireguard, which runs WireGuard in user space instead. macOS and Windows always use user-space WireGuard.

Desktop app. cloudspectra_relay_client gui opens the platform's native app -- the menu-bar app on macOS, the tray app on Windows, the indicator on Linux -- which drives the background service.

Cloud credentials

The client calls your cloud's API with your credentials; they stay on your machine and are never sent to Cloud Spectra. On macOS and Linux, commands that also need root (setup, connect, disconnect, teardown, pause, resume) are run with sudo -E, so that root sees your environment and your home directory.

login creates a dedicated cloudspectra-relay identity in your account with exactly the permissions the client needs -- it prints them and asks before creating anything (--yes skips the question) -- and stores it locally so later commands run as that identity rather than as your administrator. On DigitalOcean, which has no such identity to create, it stores a custom-scoped API token you paste. --cloud-shell creates the identity from your cloud's browser Cloud Shell instead, so no administrator credential is needed on your machine. logout --provider <cloud> deletes the identity and the local copy (it needs administrator credentials again).

Licence key. Read from the file named by CLOUDSPECTRA_LICENSE_KEY_FILE, by default ~/.cloudspectra/credentials (%USERPROFILE%\.cloudspectra\credentials on Windows). --license-key overrides it, but a value on the command line is visible to other local users. The old variable CLOUDSPECTRA_LICENSE_KEY is ignored, with a warning.

Creating a relay

There are two ways to create a relay:

• setup -- create (or adopt) the relay, wait for it, mint an enrolment token from its dashboard, and connect this machine, in one command. It is the right choice when the machine that creates the relay is the one that will wear it.
• create then connect -- create only provisions the relay and prints its address, its dashboard URL and the dashboard login, once; you then mint a token on the dashboard and run connect on the device that should wear the address. Use it when an administrator creates relays for other people, or when you need the dashboard password.

# one step, on the machine that will wear the address
sudo -E cloudspectra_relay_client setup --provider gcp --region europe-west1 --name office --daemonize

# two steps
cloudspectra_relay_client create --provider gcp --region europe-west1 --name office
sudo -E cloudspectra_relay_client connect --name office --token <token-from-dashboard>

Options for setup and create

Options only on create

create refuses --tunnel-members above 1 and the --compression flags: those settings belong to the relay's dashboard (see Throughput).

Options only on setup

Per-cloud notes

Sizing and cost. A relay that wears one address is light work; the default floor (1 vCPU, 2 GiB) is enough to start. cloudspectra_relay_client list-instance-types compares the recommended instance types across the clouds -- price, vCPUs, memory and sustained network bandwidth -- with the monthly Cloud Spectra cost of each (--all shows every recorded type; --offline uses the catalogue built into the client).

Connecting devices

A relay has one wearer at a time. A device joins with a single-use enrolment token the first time; after that it reconnects with no token, no dashboard and -- if you pass --relay -- no cloud credentials.

Minting a token

Sign in to the relay's dashboard at https://<public-ip>:28300 (its certificate is self-signed) and open Generate Token. A token is single-use, expires after two minutes unless the relay was created with a longer --token-ttl or you choose another lifetime, and minting a new one replaces any outstanding token. The dashboard can also mint a multi-use token, valid for every use until it expires; the audit log records that it was issued.

connect

# on a machine with the cloud credentials: the relay is found by its tags
sudo -E cloudspectra_relay_client connect --name office --token <token>

# on a machine without cloud credentials: name the relay's address
sudo cloudspectra_relay_client connect --name office --relay <public-ip> --token <token>

# later, from the same machine: no token
sudo cloudspectra_relay_client connect --name office --relay <public-ip>

On Windows run the same commands from an elevated prompt as & "C:\Program Files\CloudSpectra\cloudspectra_relay_client.exe" connect .... By default connect raises the tunnel, hands it to a background process and returns; --foreground holds it in the terminal instead. That background process does not survive a reboot -- for that, see Keeping the address across reboots.

disconnect, and moving the address

# bring the tunnel down; this machine stays enrolled and reconnects without a token
sudo -E cloudspectra_relay_client disconnect --name office

# also give the address back: the relay wears nobody and this machine forgets its key
sudo -E cloudspectra_relay_client disconnect --name office --vacate

To move the address to another machine, mint a token and run connect --takeover there (or setup --takeover --admin-password ...). The machine that held it is evicted; reconnecting it later needs a new token. The address, and every allow-list and DNS record that names it, stays the same.

Keeping the address across reboots

For a machine that should wear the address permanently -- a home server, an office desktop -- enrol it with the client's background service, which the installers set up (cloudspectra-relay-daemon on Linux, the ai.cloudspectra.relay.daemon LaunchDaemon on macOS, the CloudSpectra Relay service on Windows). The service starts at boot, raises the tunnel from the stored enrolment, and repairs routing after network changes, sleep and wake.

# enrol into the service's state (once, with a token from the dashboard)
sudo cloudspectra_relay_client enrol --relay <public-ip> --token <token>
# raise the tunnel now; at every later boot the service raises it by itself
sudo cloudspectra_relay_client ctl connect

sudo cloudspectra_relay_client ctl status        # live tunnel state (add -json for JSON)
sudo cloudspectra_relay_client ctl diagnostics   # detailed diagnostics
sudo cloudspectra_relay_client ctl disconnect

enrol also accepts --full-tunnel, --takeover, --name (the dashboard label) and --wait <duration>, which keeps retrying while a just-created relay is still booting. ctl split-tunnel on|off switches the service's tunnel between split and full. On Windows, run these from an elevated prompt with the full path to the client.

Phones and tablets

Phones and tablets use the stock WireGuard app for iOS or Android; there is no Cloud Spectra app to install. Because the phone cannot generate a key and send only its public half, the relay generates the phone's key pair and puts the whole configuration -- including the private key -- in the QR code. Anyone who photographs the code has the device's credential; it is shown once and stored nowhere.

• From the dashboard: Generate Token → Enrol a phone, choose split or full tunnel, and scan the code in the WireGuard app (Add tunnel → Create from QR code). This makes the phone the relay's wearer, replacing whichever device held the address.
• From the CLI: mint a token, then print the code in a terminal:

  cloudspectra_relay_client qr --relay <public-ip> --token <token> [--full-tunnel] [--compact] [--show-config]

  This path refuses (409) while another device has a live session; disconnect that device first, or use the dashboard. --compact halves the width for an 80-column terminal, --invert helps a camera that cannot read the default colours, and --show-config also prints the configuration as text.

A phone on a split tunnel sends only the relay's network through the tunnel, so inbound connections to the address cannot be answered by it directly. The dashboard's Firewall page has an Inbound to your phone setting for the ports you need; on those ports the relay translates the visitor's address, so your service sees one address for every visitor.

Sharing the address with LAN devices

Consoles, NAS boxes, cameras and other devices that cannot run a client can wear the cloud address through a Windows, macOS or Linux machine that does. That machine remains the relay's one wearer; it routes the shared devices' traffic into the tunnel and translates it to the worn address. Nothing is shared until you name a device.

sudo -E cloudspectra_relay_client connect --name home --share-with 192.168.1.50 --forward udp/3074:192.168.1.50

The same flags are accepted by setup. A shared device acts as your identity: it leaves the internet from your address, so share only with devices you trust.

Routing: split and full tunnel

A full tunnel takes over the machine's default route, so existing connections -- including an SSH session into the machine -- move with it. After taking the default route, the client checks that the tunnel carries traffic; if it does not, it rolls the change back so the machine keeps its own connectivity, and reports tunnel did not carry traffic ... after taking the default route. When the tunnel goes down, the machine gets its own egress back.

Reaching the relay's network

On Azure, Google Cloud and Oracle Cloud the device wears the relay's private address, so other instances in the relay's network reach the device at that address, and the device reaches them through the tunnel -- subject to your cloud's firewall rules. In a network the client created, the device routes that whole network range; when you place the relay in an existing network (--vpc <id> --subnet <id>), it routes the relay's own subnet.

Instance metadata

On a device that is not itself a cloud instance, the cloud metadata address 169.254.169.254 (and Azure's 168.63.129.16) is routed to the relay when the relay grants metadata access, so cloud tooling on the device reads the relay's instance metadata. A device that is itself a cloud instance keeps its own metadata service: the client deliberately does not capture it there.

DNS

At enrolment the relay gives the device the resolver it uses itself -- its cloud network's resolver -- and its internal search domain, on every supported cloud. The client applies them while the tunnel is up and removes them when it goes down:

• Linux: with systemd-resolved, the resolver and domains are attached to the tunnel interface (resolvectl), and the tunnel does not become the default resolver. Without it, /etc/resolv.conf is backed up to /run/cloudspectra/resolv.conf.bak, replaced, and restored afterwards.
• macOS: on a split tunnel, a resolver scoped to the network's domains (none is installed if the relay issued no search domain); on a full tunnel, the relay's resolver answers every name. Your network services' own settings are not edited.
• Windows: the resolver is set on the tunnel adapter, and the search domains are added to the suffix search list.
• Phones: the resolver is part of the WireGuard configuration in the QR code.

IPv6

• Default (IPv4 endpoint). The device reaches the relay over IPv4. If the relay also holds a public IPv6 address, the device wears it as well.
• --addr ipv6. The relay is reached on its IPv6 address and gets no public IPv4, so no public IPv4 is billed. All four supported clouds implement it. Your device needs working IPv6 to reach the relay, the dashboard is at https://[<ipv6>]:28300, and a full tunnel is refused -- before the enrolment token is used -- because there is no public IPv4 to leave from. On Google Cloud the client creates an isolated network for it.
• If you ask for --addr ipv6 and the cloud assigns no public IPv6, create warns you.

Inbound traffic and firewalling

Three layers decide what reaches your device on the worn address:

1. The relay's cloud firewall (security group, network security group, security list or cloud firewall, created with the relay). It admits the relay's own ports -- TCP 28300 (dashboard and enrolment), TCP 28301 (recovery SSH) and UDP 28302-28349 (the tunnel) -- plus the ports you choose with --open-port, which default to TCP 22. Sources default to anywhere. --forward and --demo-web-server open their ports for you.
2. The reserved band. Ports 28300-28349 on the address always stay with the relay and never reach your device. Every other port that the firewall admits is delivered to your device with the visitor's address intact.
3. Your device's own firewall, which decides what the device answers.

The dashboard's Firewall page filters only traffic that terminates on the relay itself; it cannot filter traffic tunnelled to your device. To change the ports open to your device after the relay exists, edit the inbound rules of the relay's firewall in your cloud console (on Oracle Cloud, the security list of the relay's subnet).

The dashboard's Policy page (Where devices may go) can filter the destinations your device reaches through the relay: off by default; the most specific rule wins and a deny wins over an allow for the same network; changes apply when the relay restarts.

The relay dashboard

Every relay serves its dashboard at https://<public-ip>:28300 with a self-signed certificate. Sign in as admin (or your --admin-user) with the dashboard password.

The Access page also shows the relay mode: a CloudAddress relay reads CloudAddress Relay (1:1 address transfer), and the mode picker lists CloudAddress as Cloud IP. Changing the mode changes which product the relay runs; it takes effect when the relay restarts, and every enrolled device must enrol again afterwards -- so leave it unless you mean to.

Status, monitoring and logs

Client logs: a daemonized setup prints the path of its log file; the background service logs to the systemd journal on Linux (journalctl -u cloudspectra-relay-daemon), to /var/log/cloudspectra-relay-daemon.log on macOS, and to %ProgramData%\CloudSpectra\relay\service.log on Windows. Relay logs: the dashboard's Logs page; with a recovery SSH key, journalctl -u cloudspectra-relay and journalctl -u cloudspectra-relay-dash over SSH on port 28301. Alerts: the dashboard can post alerts to a webhook and send its activity log to a SIEM (Settings).

Exit codes are a stable contract for scripts: 0 success, 1 failure, 2 usage error or missing credentials or a capability the cloud lacks, 6 relay not found, 7 a live session exists (pass --takeover), 8 the relay is paused (resume it).

Pause, resume, destroy and kept addresses

pause and resume

sudo -E cloudspectra_relay_client pause --name office     # stop the relay's instance
sudo -E cloudspectra_relay_client resume --name office    # start it, wait until it serves, reconnect

pause stops the relay's instance and keeps its addresses and disk; the Cloud Spectra meter stops (your cloud may still charge for the kept disk and address). Without --name it pauses the relay whose tunnel this machine is running. resume starts it, waits until it serves, and raises this machine's tunnel again if it was wearing the address when paused (--no-reconnect skips that). If you created the relay with --ephemeral-ip, pausing can change its public IPv4 on Google Cloud and Oracle Cloud; a reserved address -- the default -- is kept.

destroy and teardown

teardown is the mirror of setup: it disconnects this machine, gives the address back, and destroys the relay (--keep-relay does everything except the destroy). destroy destroys relays without touching the local tunnel; with no --name it destroys every relay in the project, and --dry-run prints the plan first. Both keep some things by default:

--delete-all is all four at once. A managed filesystem (--managed-fs) is always deleted with its relay. Everything kept is named in the command's output.

Kept addresses

Because addresses belong to the instance index, you can rebuild a relay -- to change its size or move it to a newer release -- without changing its address: teardown (or destroy) without --delete-address, then setup (or create) again in the same project and region with the same --instance-index -- and, on Azure, the same name. On Azure, Google Cloud and Oracle Cloud the new relay comes back on the same public IPv4 and private IPv4; on Oracle Cloud its IPv6 is kept too, for as long as the network is kept. On DigitalOcean nothing is kept, and the new relay has new addresses.

Throughput: bonding, compression and MTU

• Bonding. A tunnel can be bonded across several WireGuard members (1 to 32) to spread it over more network paths. Set it on the dashboard or with setup --bond N; it takes effect at the relay's next restart, and an unlicensed relay uses 1. status shows the members this machine agreed with the relay.
• Compression. Payload compression can cut the relay's egress on the download leg at the cost of CPU. Turn it on on the dashboard or with setup --enable-compression (it takes effect at the relay's next restart); on a machine enrolled with the background service, ctl compression no|auto|yes sets this machine's side.
• MTU. The client chooses and checks a tunnel MTU for the path it is on. create --mtu-mobile starts from the conservative 1180-byte setting meant for mobile and CGNAT networks.

Storage add-ons

Optional storage that devices holding the address can use. Read the lifetimes carefully -- they differ, and one of them deletes your files with the relay.

On Oracle Cloud, a scoped identity needs File Storage permission for the filesystem options: create it with login --provider oci --fss.

Configuration file

Every option can be given a default in a YAML file, by default config.yaml in the client's state directory (/etc/cloudspectra/relay on Linux, /usr/local/etc/cloudspectra/relay on macOS, C:\ProgramData\CloudSpectra\relay on Windows), or the file named by --config. The file has one section per command (setup, create, connect, disconnect, status, list, describe, destroy, teardown, pause, resume); keys are the flag names without the dashes. A flag typed on the command line always wins. cloudspectra_relay_client print-config writes a fully commented example.

setup:
  provider: oci
  region: eu-frankfurt-1
  name: laptop
connect:
  full-tunnel: true

Upgrades

The client does not update itself. To upgrade, install the newer release's package over the old one: the Debian package restarts the background service on upgrade, the macOS package replaces the running daemon, and the Windows installer upgrades in place. Enrolments survive the upgrade.

The relay is pinned to a release: by default the release of the client that created it (--package-version overrides it). At every boot, before the relay starts serving, it checks its release bucket and installs that build if it is not already running it, verifying the package's signature against the Cloud Spectra release-signing key; the check never interrupts a running tunnel, and if the bucket cannot be reached the relay starts on what it has. To move a relay to a newer release, rebuild it with the newer client on the same instance index, as described under Kept addresses.

Security model

Where things run

• The relay is an instance in your cloud account, created with your credentials, which never leave your machine. Your tunnel traffic flows between your device, your relay and the internet; it does not pass through Cloud Spectra.
• The relay talks to Cloud Spectra for three things: it validates its licence and reports the usage it is billed for (check-ins every two minutes), it obtains its signed datapath at start-up by presenting the licence key, and it downloads its signed software package and kernel.
• Licence enforcement fails closed at start and soft in flight. A relay with no licence, or one that does not verify, starts parked: its dashboard answers and says why, and it forwards nothing. A relay that has been entitled keeps serving for 24 hours if the control plane becomes unreachable, then parks.

Keys, tokens and passwords

• The device generates its own WireGuard key pair and sends only the public key; the private key is stored on the device readable by root only (on Windows, by SYSTEM and Administrators). The relay's own key is created by the client at provisioning and delivered to the instance in its first-boot data, inside your cloud account.
• For phones the relay generates the key pair and the QR code contains the private key; it is shown once and stored nowhere.
• Enrolment tokens are single-use, short-lived, replace any outstanding token, and are compared in constant time. A refusal -- another device holds a live session, or a full tunnel this relay cannot carry -- does not use the token up.
• A live session cannot be taken over without --takeover. An operator signed in to the dashboard can still replace the device, by enrolling a phone or removing the device on the Access page.
• The dashboard is reachable on port 28300 from anywhere by default and protected by its password, which the relay holds only as a bcrypt hash; failed sign-ins are rate-limited. Its certificate is self-signed, so the client does not verify it unless you pass --verify-tls.
• The licence key is read from a file, never from an environment value. On the relay it is stored in root-only files.

The relay instance

• First boot verifies the signatures of the package and the kernel against the release-signing key before installing either (--insecure-skip-signature exists for lab use only), then boots Cloud Spectra's hardened kernel.
• The relay's own SSH listens only on port 28301, and only with a key you supplied with --ssh-key; port 22 on the address belongs to your device.
• Your device's exposure is decided by the relay's cloud firewall and your device's own firewall; the dashboard's firewall protects only the relay.

Troubleshooting

Still stuck? Email support@cloudspectra.ai with the command you ran, its output, and the client's log (see Status, monitoring and logs).

Teardown checklist

1. Bring each device's tunnel down: disconnect --vacate, or ctl disconnect for the background service.
2. Destroy the relay: sudo -E cloudspectra_relay_client teardown --provider <cloud> [--region <region>] --name <name>.
3. Decide what to keep: add --delete-address to release the address (irreversible), --delete-drive for a cloud drive, or --delete-all to keep nothing.
4. Check with cloudspectra_relay_client list --provider <cloud> [--region <region>] that nothing you meant to delete is still listed.
5. Optionally remove the scoped identity with logout --provider <cloud>, and uninstall the client.