CloudAddress -- Quick Start v1.0.0

1Subscribe and copy the key. Sign in at your Cloud Spectra account (we email you a sign-in code), choose the Developer or Enterprise plan and complete checkout. The licence key -- it begins CSTW1- -- is shown once when checkout completes. If you lose it, replace it from the same account page.

Save it where every Cloud Spectra tool looks for it by default. On macOS and Linux:

mkdir -p ~/.cloudspectra
umask 077 && printf '%s\n' 'CSTW1-...' > ~/.cloudspectra/credentials

On Windows, save the key in the file %USERPROFILE%\.cloudspectra\credentials.

To keep the file elsewhere, set CLOUDSPECTRA_LICENSE_KEY_FILE to its path. The tools read the key from a file, never from an environment variable's value: CLOUDSPECTRA_LICENSE_KEY is not honoured, because a key in the environment leaks into process listings and CI logs.

2Download and install cloudspectra_relay_client for your platform. The client is free and is published at https://downloads.cloudspectra.ai/gateway/1.0.0/clients/.

Debian or Ubuntu (use arm64 in the file name on ARM):

curl -fsSLO https://downloads.cloudspectra.ai/gateway/1.0.0/clients/cloudspectra-relay-client_1.0.0_linux_amd64.deb
sudo apt install ./cloudspectra-relay-client_1.0.0_linux_amd64.deb

apt also installs what the package depends on (wireguard-tools, nftables and a few others) and starts the client's background service.

macOS (use amd64 in the file name on an Intel Mac):

curl -fsSLO https://downloads.cloudspectra.ai/gateway/1.0.0/clients/cloudspectra-relay-client_1.0.0_macos_arm64.pkg
sudo installer -pkg cloudspectra-relay-client_1.0.0_macos_arm64.pkg -target /

This installs CloudSpectra.app, the background daemon, and the command-line client at /usr/local/bin/cloudspectra_relay_client.

Windows -- in PowerShell run as Administrator (use arm64 in the file name on ARM):

curl.exe -fsSLO https://downloads.cloudspectra.ai/gateway/1.0.0/clients/cloudspectra-relay-client_1.0.0_windows_amd64.msi
msiexec /i cloudspectra-relay-client_1.0.0_windows_amd64.msi

The installer puts the client in C:\Program Files\CloudSpectra\ and registers the CloudSpectra Relay service. It does not add that folder to PATH, so the Windows commands below use the full path.

Other Linux distributions use the standalone binary, plus wireguard-tools and nftables from your distribution:

curl -fsSL https://downloads.cloudspectra.ai/gateway/1.0.0/clients/cloudspectra_relay_client-linux-amd64.gz | gunzip > cloudspectra_relay_client
sudo install -m 0755 cloudspectra_relay_client /usr/local/sbin/cloudspectra_relay_client

Check the installation:

cloudspectra_relay_client version

3Let the client reach your cloud's API. The relay is created in your account with your credentials, which stay on your machine. The client reads each cloud's standard credential sources:

Optional: instead of using your own administrative credentials day to day, let the client create a dedicated least-privilege identity in your account and use that from then on:

cloudspectra_relay_client login --provider oci

login shows the exact permissions it will grant and asks before creating anything; logout deletes the identity again. See Cloud credentials for the per-cloud options.

4Run setup. On macOS and Linux, use sudo -E: raising the tunnel needs root, and -E keeps your environment -- your cloud credentials and your home directory, where the licence file is -- visible to the command.

sudo -E cloudspectra_relay_client setup --provider oci --name laptop --full-tunnel --daemonize

On Windows, in PowerShell run as Administrator:

& "C:\Program Files\CloudSpectra\cloudspectra_relay_client.exe" setup --provider oci --name laptop --full-tunnel --daemonize

A relay started from a stock image installs the relay software and its kernel on first boot and reboots, which takes a few minutes. On Oracle Cloud the first relay in a region and release imports the relay image into your tenancy instead -- several minutes, once -- and later relays start from that image. setup waits up to 30 minutes (--timeout). When the address is worn it prints:

relay ready -- this machine now wears <worn-address> (relay <public-ip>).
dashboard: https://<public-ip>:28300

  detached (pid <pid>). Logs: <log-file>
  stop the tunnel:  cloudspectra_relay_client disconnect --project default --name laptop
  destroy the relay: cloudspectra_relay_client teardown --project default --name laptop

<public-ip> is your CloudAddress. On Oracle Cloud, Azure and Google Cloud, <worn-address> is the relay's private address in its cloud network -- the cloud maps the public IP to it; on DigitalOcean the two are the same address.

5Check what this machine is wearing. status reads this machine's local state only -- no cloud, no network. The state was written by the administrator account, so read it the same way (an elevated prompt on Windows):

sudo cloudspectra_relay_client status --name laptop

It shows the worn address, the relay, the tunnel interface and MTU, and tunnel UP with the holding process's pid.

Check your egress address (full tunnel). Ask any "what is my IP" service; the answer is the relay's public IPv4:

curl -4 https://ifconfig.me

With the default split tunnel this still shows your own connection's address -- only the relay's network goes through the tunnel -- which is expected.

Check that you are inside the relay's network (split or full tunnel). On a machine that is not itself a cloud instance, the cloud metadata address is routed to the relay, so this returns the relay's instance document. On Oracle Cloud:

curl -s -H "Authorization: Bearer Oracle" http://169.254.169.254/opc/v2/instance/

On a machine that is itself a cloud instance, the metadata address deliberately stays local, so the same command reads that machine's own metadata.

Check inbound (optional). If you added --demo-web-server, open https://<public-ip>/ from another network as described above.

6Give the address back and destroy the relay. Use the same --provider (and --region, if you passed one) as for setup:

sudo -E cloudspectra_relay_client teardown --provider oci --name laptop

On Windows: & "C:\Program Files\CloudSpectra\cloudspectra_relay_client.exe" teardown --provider oci --name laptop

teardown brings the tunnel down, removes this machine from the relay, and destroys the relay, which stops its Cloud Spectra meter. By design it keeps two things, so that a later setup comes back on the same address:

• the public address, kept for the relay's address slot (--instance-index, 0 by default). Oracle Cloud does not charge for a kept reserved IP; Azure and Google Cloud do. DigitalOcean has no reserved address to keep.
• the network -- network, subnet, gateway and firewall -- which costs nothing to keep.

To remove everything and keep nothing, add --delete-all. A released public address cannot be recovered; the next relay gets a different one.

sudo -E cloudspectra_relay_client teardown --provider oci --name laptop --delete-all

Confirm what remains with cloudspectra_relay_client list --provider oci: a relay that has been destroyed but whose address or network was kept is listed with what was kept.