Hapimatic Cloud — Tailscale Setup

INFO

Hapimatic Cloud is in pilot. This page is for pilot users.

Tailscale is optional. Set it up if you want to reach your VM privately and mount its files on your own PC. If you'd rather get going first, jump to Skip for now — you can add Tailscale later.

What this gives you

Tailscale is a private mesh network. Connecting your VM to it lets you:

• Reach your VM by a stable private name from your own devices, and
• Mount your VM's files on your PC so you can edit them with your local tools.

The one rule that matters: it's your tailnet

Your VM joins your own Tailscale network (your "tailnet"), using a key you create. It never joins the operator's network (decision D999-8).

This is deliberate. You have a full shell on your VM, and your own devices are on the same tailnet — so the VM is treated as one of your machines, not a peer of the operator's home network or of any other user. The consequence for you: you create the key, and you control (and later remove) the VM's membership in your network.

Setting it up

Create a free Tailscale account

Go to tailscale.com and sign up (Google, Microsoft, or GitHub login works). The free tier is plenty for this.

Install Tailscale on your PC

Install the Tailscale client on the computer you'll use to reach your VM:

• macOS / Windows — download from tailscale.com/download and sign in.
• Linux — curl -fsSL https://tailscale.com/install.sh | sh then sudo tailscale up.

After signing in, your PC is on your tailnet. You can confirm with tailscale status.

Create an auth key for your VM

In the Tailscale admin console:

1. Go to Settings → Keys → Generate auth key.
2. Turn Ephemeral on and Reusable off. An ephemeral key makes your VM an ephemeral node: Tailscale automatically removes it from your tailnet shortly after it goes offline, so a destroyed VM cleans itself out of your network even if no explicit offboarding step runs (issue #2306).
3. Copy the key — it looks like tskey-auth-....

Treat the key like a password

Anyone with this key can add a machine to your tailnet. Share it only with the operator, at onboarding, and prefer a short expiry.

An ephemeral VM that stays offline a while needs a fresh key to rejoin

Ephemeral is the right default (self-cleanup), but it has one trade-off: Tailscale cannot tell "destroyed" from "offline for a while", so a VM left offline past the drop window (roughly 30–60 minutes) is removed from your tailnet. The join key is also used once and deleted from the VM at provision time, so bringing a long-offline VM back needs a fresh ephemeral key — create one with the steps above and re-join (see "Add it later" below).

Give the key to the operator at onboarding

Provide the tskey-auth-... key to the operator along with your email. During provisioning, the key is used once to join your VM to your tailnet and is then deleted from the VM — it is not stored (decision D999-8). Your VM appears in your Tailscale admin console as <your-subdomain>.

Under the hood, the operator passes your key explicitly to the provisioner (provision.sh --ts-authkey <your-key>, or the HAPI_TS_AUTHKEY environment variable). It is never taken from the operator's own configuration, so your VM can only ever join your tailnet — never the operator's (issue #2302).

Mount your VM's files on your PC

Once your VM is on your tailnet, you can reach it by its Tailscale name/IP (visible in your admin console) and mount its files locally:

• macOS / Linux — use SSHFS:

  # Replace with the details the operator gives you (VM Tailscale name, SSH user, key).
  sshfs <ssh-user>@<your-subdomain>:/home/hapimatic ~/hapimatic-vm

• Windows — use an SFTP client (e.g. WinSCP) or WinFsp + SSHFS-Win, pointed at the same Tailscale address.

Connection details come from the operator

The exact SSH user, key, and path for your own access to the VM are provided by the operator at onboarding — confirm them before mounting. Tailscale gets you a private route to the VM; the operator supplies how you authenticate to it.

Skip for now

You do not need Tailscale to sign in and use Hapimatic in the browser. If you skip it:

• You still reach your instance at https://<your-subdomain>.hapimatic.com and use it normally.
• You simply won't have the private drive-mount to your VM's files from your PC.

To add it later, create a fresh ephemeral auth key (steps above) and join your VM to your tailnet — either through your instance's self-service Connect Tailscale step, or by giving the key to the operator for a re-provision. Each join needs its own fresh key: the previous one was consumed and deleted at join time.

When you leave

Because the VM lives on your tailnet, the operator cannot remove it for you — and because the join uses an ephemeral key, they don't have to. Once the VM is destroyed and stays offline past the drop window (roughly 30–60 minutes), Tailscale removes the <your-subdomain> node automatically. If you want it gone immediately, or you used a non-ephemeral key, remove the node yourself from your Tailscale admin console (decision D999-12). See the Consent & Data-Handling Statement.