CloudVpn -- Quick Start v1.0.0

Create a CloudVpn relay, connect your devices, and confirm they all leave from one address.

1. What you will build

By the end of this guide you will have one CloudVpn relay running in your own Oracle Cloud Infrastructure (OCI) tenancy, at least two devices connected to it over their own WireGuard tunnels, and proof that both devices reach the internet from the relay's single public IPv4 address.

The examples use the project name acme, the relay name team, the OCI region us-ashburn-1 and the documentation address 203.0.113.40 for the relay's public IPv4. Substitute your own values.

Before you start: read the Overview if you have not, so you know what CloudVpn does and does not do -- in particular that it carries IPv4 TCP and UDP only, and that devices are not reachable from the internet through it.

2. Prerequisites

You needDetails
A Cloud Spectra licence keyIt begins CSTW1-. Buy one from Pricing; manage keys on the account page.
An OCI tenancyCloudVpn relays are created on Oracle Cloud Infrastructure in 1.0.0. Relays on AWS are not available to customers in this release.
OCI credentials on your admin machineAn OCI CLI configuration in ~/.oci/config. Alternatively, cloudspectra_relay_client login --provider oci creates a scoped identity for the client to use. The client uses these credentials to create the relay; they are not copied to the relay.
Administrator rights on each deviceConnecting creates a network interface: sudo on Linux and macOS, an elevated prompt on Windows.
Outbound network access from devicesDevices must reach the relay on UDP 28302 (the tunnel) and TCP 28300 (enrolment).

3. Install the client

Install the Cloud Spectra client, cloudspectra_relay_client, on your admin machine and on every computer that will connect. The same client creates relays and connects devices. Release 1.0.0 is published at https://downloads.cloudspectra.ai/gateway/1.0.0/clients/; no licence or sign-in is needed to download it.

PlatformFile
Linux (Debian, Ubuntu) x86-64cloudspectra-relay-client_1.0.0_linux_amd64.deb
Linux (Debian, Ubuntu) Arm64cloudspectra-relay-client_1.0.0_linux_arm64.deb
macOS 13 or later, Apple siliconcloudspectra-relay-client_1.0.0_macos_arm64.pkg
macOS 13 or later, Intelcloudspectra-relay-client_1.0.0_macos_amd64.pkg
Windows x64cloudspectra-relay-client_1.0.0_windows_amd64.msi
Windows Arm64cloudspectra-relay-client_1.0.0_windows_arm64.msi
Standalone binary (any of the above)cloudspectra_relay_client-<linux|macos|windows>-<amd64|arm64>[.exe].gz

Linux (Debian or Ubuntu)

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

On Arm64, use the linux_arm64 file. The package installs the client to /usr/sbin/cloudspectra_relay_client and pulls in its dependencies, including wireguard-tools and nftables.

Debian: /usr/sbin is not on a regular user's PATH on Debian. For commands you run without sudo, such as create, call /usr/sbin/cloudspectra_relay_client or add /usr/sbin to your PATH.

macOS

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 /

On an Intel Mac, use the macos_amd64 file. The package installs the CloudSpectra app and links the client at /usr/local/bin/cloudspectra_relay_client.

Windows

In PowerShell opened with Run as administrator:

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

On Arm64, use the windows_arm64 file. The client is installed in C:\Program Files\CloudSpectra\; run it from an elevated Command Prompt or PowerShell in that folder.

Other Linux distributions: the standalone binary

curl -fsSL https://downloads.cloudspectra.ai/gateway/1.0.0/clients/cloudspectra_relay_client-linux-amd64.gz | gunzip > cloudspectra_relay_client
chmod +x cloudspectra_relay_client
sudo mv cloudspectra_relay_client /usr/local/bin/

The standalone binary installs no dependencies. The .deb package depends on wireguard-tools and nftables; install your distribution's equivalents.

Check the installation:

cloudspectra_relay_client version

4. Save your licence key

The client reads your licence key from a file, never from an environment value. The default file is ~/.cloudspectra/credentials (on Windows, %USERPROFILE%\.cloudspectra\credentials). On your admin machine:

mkdir -p ~/.cloudspectra && chmod 700 ~/.cloudspectra
cat > ~/.cloudspectra/credentials      # paste your CSTW1-... key, press Enter, then Ctrl-D
chmod 600 ~/.cloudspectra/credentials

To keep the key somewhere else, set CLOUDSPECTRA_LICENSE_KEY_FILE to the file's path.

Without a licence key the relay is created but forwards nothing. It boots, answers on its dashboard and stays parked. If that happens, save the key and create the relay again.

5. Create the relay

Run create on your admin machine. CloudVpn relays are created on Oracle Cloud (OCI) in 1.0.0.

cloudspectra_relay_client create --provider oci --region us-ashburn-1 \
    --project acme --name team --mode cloud_vpn

Without --region, the region comes from ~/.oci/config. The first relay of a release in a tenancy and region imports the published relay image once, which adds several minutes; later relays of that release reuse it.

Always pass --mode cloud_vpn. The default mode of create is cloud_address, which lends the relay's address to a single device and does not share it. To see what would be created without changing anything in your cloud, add --dry-run --json; the "mode" field of the output must read "cloud_vpn".

When create finishes it prints the relay's details. The lines you need:

LineWhat it is
publicThe relay's public IPv4 -- the address every device will share, and the value you pass to connect --relay.
dashboardThe dashboard URL, https://<public address>:28300.
DASHBOARD LOGINThe user (admin) and a generated password. It is shown once and stored nowhere; save it now. To choose your own instead, pass --admin-password to create.

create is idempotent per project and name: running it again with the same --project and --name adopts the existing relay instead of creating a second one.

6. Sign in to the dashboard

The relay finishes installing after create returns, so its dashboard can take a few minutes to answer. Then:

  1. Open https://203.0.113.40:28300 (your relay's dashboard URL). A new relay uses a self-signed certificate, so your browser shows a warning the first time; you can give the dashboard a trusted certificate later (see Dashboard and monitoring).
  2. Sign in as admin with the password from create.
  3. Open Access. Under Relay mode the page should say This relay is running SNAT (shared egress), with the Cloud VPN option selected.
Wrong mode? If the Access page says CloudAddress Relay (1:1 address transfer), the relay was created without --mode cloud_vpn. Destroy it and create it again with the flag, or switch it as described in Deploying a CloudVpn relay.

7. Connect your devices

Repeat these steps for every computer. Each device needs its own token.

1Mint a token on the dashboard

Open Generate Token, choose how long the token stays valid under Valid for (2 minutes by default), and press Generate enrolment token. Copy the token.

Only one unused token exists at a time -- generating another cancels it -- so mint each device's token just before you use it.

2Connect the device

Linux and macOS:

sudo cloudspectra_relay_client connect --project acme --name team \
    --relay 203.0.113.40 --token <token> --full-tunnel

Windows, in an elevated Command Prompt:

cd "C:\Program Files\CloudSpectra"
cloudspectra_relay_client.exe connect --project acme --name team --relay 203.0.113.40 --token <token> --full-tunnel
  • --full-tunnel sends all of the device's IPv4 traffic through the relay, so it leaves as the relay's address. Without it the device uses a split tunnel and its internet traffic does not use the relay.
  • --relay is the relay's public IPv4. A machine holding the cloud credentials for the relay's account can omit it; the client then looks the relay up by its project and name.
  • Add --device-name laptop-jane to choose how the device is labelled on the dashboard.

connect returns once the tunnel is up and leaves a background process holding it until you disconnect.

3Phones (iOS and Android)

On the Generate Token page, under Enrol a phone, enter a name, choose Full tunnel as the mode and press Enrol a phone. Scan the QR code with the official WireGuard app. The QR code contains the phone's private key and is shown only once.

8. Verify

On each connected computer, ask a public echo service which address it sees:

curl -4 https://api.ipify.org

On Windows, use curl.exe -4 https://api.ipify.org. Every device should print the relay's public IPv4 (203.0.113.40 in this guide) rather than its own.

Then check from both ends:

  • On a device: cloudspectra_relay_client status --project acme --name team shows the enrolment and the device's tunnel address.
  • On the dashboard, Access lists every enrolled device with its own 10.99.x.x address, and Monitoring shows Devices enrolled and Devices connected now.
ping does not work through CloudVpn. The relay translates TCP and UDP only, so ICMP is dropped. Use curl or another TCP or UDP tool to test.

9. Tear down

On each computer, bring the tunnel down:

sudo cloudspectra_relay_client disconnect --project acme --name team

The device stays enrolled, so a later connect --project acme --name team needs no token. Add --vacate to also remove the device from the relay. Remove a phone by deleting its tunnel in the WireGuard app and retiring it on the dashboard's Access page.

Then destroy the relay from your admin machine:

cloudspectra_relay_client destroy --provider oci --region us-ashburn-1 --project acme --name team
  • destroy prints a notice and proceeds; there is no confirmation prompt. Always pass --name: without it, destroy deletes every relay in the project.
  • By default the relay's public IPv4 is kept for its slot, so a relay you create again with the same project, region and --instance-index comes back on the same address. OCI does not charge for a reserved public IP, and the kept network costs nothing either.
  • To remove everything, including the public address, add --delete-all. A released address cannot be recovered.

10. Next steps

Where to go from here: restrict where devices may go with the destination policy, and read the security model before you put the relay into production. The known limitations list what 1.0.0 does not do. For help, email support@cloudspectra.ai.