Skip to content
Supercompute

Get started locally with a roaming node

This guide extends Get started locally with a Lima roaming guest (roaming-1) on Apple Silicon, using the dev-lima inventory. Mesh CIDR is 10.217.81.0/24 (disjoint from dev at 10.217.80.0/24).

Finish Get started locally first — you need task setup, a prepared static-1 VM, and familiarity with the dev flow.

Prerequisites

Section titled “Prerequisites”

You need Apple Silicon, Lima, a completed Get started locally setup, and an external Postgres instance (same requirement as dev — you set the connection URL in the dev-lima vault).

  • macOS on Apple Silicon
  • Lima
  • Completed Get started locally (task setup, prepared static-1, familiar with the dev flow)
  • Operator SSH key at ~/.ssh/<project>-dev-lima (inventory path ssh_private_key_file)
  • External Postgres instance (not installed by this automation)
Terminal window
brew install lima

task up ENV=dev-lima uses ~/.ssh/example-dev-lima, not the get-started example-dev key. If static-1 already has example-dev.pub in ops authorized_keys, copy that pair:

Terminal window
cp ~/.ssh/example-dev ~/.ssh/example-dev-lima
cp ~/.ssh/example-dev.pub ~/.ssh/example-dev-lima.pub
chmod 600 ~/.ssh/example-dev-lima
ssh-add ~/.ssh/example-dev-lima

Otherwise create a new Ed25519 key and install the public key on static-1 (ops user) as in Adding a public node.

Step 1: Prepare the dev-lima inventory

Section titled “Step 1: Prepare the dev-lima inventory”

Add the static hub and Lima roaming guest to the dev-lima inventory.

Edit inventories/dev-lima/hosts.yml — same all.vars shape as dev (project + hostname), plus static-1 and roaming-1. Fill placeholders for static-1 (public IP and SSH host-key fingerprint). Install this public key on the VM with static IP (ops user)—same prep as Adding a public node. Go and do that first.

---
all:
  vars:
    project: example
    hostname: example.com


nodes:
  hosts:
    static-1:
      public_ip: "159.203.27.69"
      ssh_ed25519_sha256: "SHA256:pRR...e+M"
      private_address: 10.217.81.11
    roaming-1:
      roaming: true
      node_lima_guest: true
      node_host_architecture: aarch64
      ssh_ed25519_sha256: "SHA256:FILLED_AUTOMATICALLY_BY_LIMA_UP"
      private_address: 10.217.81.21

lima-up fills roaming-1 ssh_ed25519_sha256 automatically.

Step 2: Configure DNS

Section titled “Step 2: Configure DNS”

Create records for the hostname you set in Step 1. Supercompute derives the rest by adding the hostname as a common suffix. Leave example.com at your registrar. If the DNS is hosted on Cloudflare, do not enable the proxy orange icons.

Prefix Name Type Value
ns ns.example.com A static-1 public IPv4
sc-api sc-api.example.com CNAME ns.example.com
sc-app sc-app.example.com CNAME ns.example.com

Later, dynamic app URLs use the same nameserver:

Prefix Name Type Value
apps apps.example.com NS ns.example.com

Supercompute’s Nameserver then serves *.apps.example.com.

To use different API or app hostnames, edit dns_prefix_api and dns_prefix_app (and other dns_prefix_* values if needed) in inventories/<env>/group_vars/all/main.yml, then create matching DNS records and re-run task up.

Step 3: Create the Lima guest

Section titled “Step 3: Create the Lima guest”

Start the Lima VM and let automation capture its SSH fingerprint.

Terminal window
task lima-up ENV=dev-lima
task lima-status ENV=dev-lima

Requires limactl, uv, and ssh-keyscan.

Step 4: Initialize the vault

Section titled “Step 4: Initialize the vault”

Create the encrypted vault and local password file for dev-lima.

Terminal window
task vault-init ENV=dev-lima

Creates inventories/dev-lima/.vault-pass and encrypted vault.yml with vault_meta, placeholder vault_database_url, and auto-generated vault_database_secret. The first task up adds WireGuard keypairs to the vault.

Decrypted inventories/dev-lima/group_vars/all/vault.yml looks like this:

---
vault_meta:
  project: example
  provider: dev-lima
vault_database_url: postgresql://REPLACE_WITH_USER:PASSWORD@HOST:5432/DATABASE
vault_database_secret: kR7xP2mN9qL4vB8wF3hJ6tY1cZ5aD0eG_sXu

PostgreSQL database

Section titled “PostgreSQL database”

Point the vault at your external Postgres before the first deploy.

Supercompute needs a Postgres database with owner role hosted outside of the Supercompute cloud.

Terminal window
task vault-edit ENV=dev-lima

task vault-edit decrypts inventories/dev-lima/group_vars/all/vault.yml in your editor. You should see vault_meta, vault_database_url, and vault_database_secret (WireGuard keys appear after the first task up). Replace only vault_database_url with your connection URI (same shape as the dev-lima tab). Leave everything else unchanged.

Example after you set the database URL:

---
vault_meta:
  project: example
  provider: dev-lima
vault_database_url: postgresql://app:[email protected]:5432/supercompute
vault_database_secret: kR7xP2mN9qL4vB8wF3hJ6tY1cZ5aD0eG_sXu

Save and exit the editor:

  • vim/vi (default on macOS): press EscapeEscape, type :wq, press EnterEnter
  • nano: press Control + OControl + O, EnterEnter, then Control + XControl + X

task up rejects the vault-init placeholder in vault_database_url.

Step 5: Bring up the cloud

Section titled “Step 5: Bring up the cloud”

Join the static hub and Lima guest to the WireGuard mesh.

Terminal window
task up ENV=dev-lima

When prompted for BECOME password, enter your macOS password.

Step 6: SSH to nodes

Section titled “Step 6: SSH to nodes”

Confirm you can reach both nodes over the mesh.

Terminal window
task ssh ENV=dev-lima NODE=static-1
task ssh ENV=dev-lima NODE=roaming-1

Optional latency check from a node to the Mac mesh peer:

Terminal window
ping -c 10 -I scwg0 10.217.81.1

If both nodes are reachable, you are done with this guide.

Public Lima tasks: lima-up and lima-status (task --list). Full reference: Task commands.

Next steps

Section titled “Next steps”