GCP

Provision the VM

1. Set up gcloud and the project. Install the CLI from cloud.google.com/sdk/docs/install, then:

   gcloud init
   gcloud projects create my-assistant-project
   gcloud config set project my-assistant-project
   gcloud services enable compute.googleapis.com

   Enable billing in the Billing console, or Compute Engine won't start an instance.

2. Create the VM. e2-standard-4 (4 vCPU, 16 GB) is a comfortable default; e2-standard-2 works for light use. Pick a zone near you. 20 GB of disk is plenty to start; boot disks can be grown later, never shrunk.

   gcloud compute instances create mycadet \
     --zone=us-central1-a \
     --machine-type=e2-standard-4 \
     --boot-disk-size=20GB \
     --image-family=debian-12 \
     --image-project=debian-cloud

   Note: an always-on VM bills continuously, so check Google's pricing calculator for what your choices cost per month.

3. SSH in. Key propagation takes a minute or two after the VM is created, so retry if the first attempt is refused.

   gcloud compute ssh cadet --zone=us-central1-a

Install and hatch

Everything from here runs on the VM.

1. Install Cadet and its dependencies.

   # Bun's installer needs curl and unzip
   sudo apt-get update
   sudo apt-get install -y curl unzip git
   
   # Cadet ships as a Bun package, so Bun needs to be installed
   curl -fsSL https://bun.sh/install | bash -s "bun-v1.3.11"
   source ~/.bashrc
   
   # Install Cadet itself
   bun install -g cadet

2. Hatch the assistant.

   cadet hatch

   You'll be asked to pick an LLM provider and enter an API key for it. It then starts the assistant and gateway, and prints a local runtime URL like http://127.0.0.1:7830.

3. Talk to it. Your assistant is alive! Message it interactively from the terminal and confirm everything works.

   cadet client

4. (Optional) Pair for remote access. So far the assistant is only reachable via CLI from the VM itself. You can set up a tunnel, then pair to it from your phone or laptop. To learn more, see Pair a device.

Day to day

• cadet ps shows what's running; cadet wake and cadet sleep start and stop it, keeping the workspace on disk.
• If you paired any devices, cadet devices lists them and cadet devices revoke <id> cuts one off.

Nothing restarts on its own after a VM reboot. Bring the assistant back with cadet wake, and restart your tunnel too if you set one up.

Stopping the instance keeps the disk and everything on it. Deleting it takes the workspace too, unless you kept the disk.

Troubleshooting

Creating the VM fails

New projects start with low CPU quotas, and a zone can run out of a machine type. A quota error means you need more CPUs in that region; a zone-capacity error means the type isn't available there right now. Retry in another zone (--zone=us-central1-b) or with a smaller --machine-type.

SSH won't connect, or the installs on the VM fail

Some organizations block external IP addresses by policy. A VM without one is reachable through Identity-Aware Proxy, by adding --tunnel-through-iap to gcloud compute ssh, but it also has no outbound internet until someone configures Cloud NAT, which is what makes apt-get and the Bun installer hang or fail.

cadet: command not found

Bun's install directory isn't on your PATH in this shell. Open a new SSH session, or run source ~/.bashrc.