Machines

A Machine is the rented GPU box your setup runs on. It's separate from the Setup that owns it: the setup is your disk, image, and everything installed, and it outlives any one machine. Find your machines under Machines in the sidebar.

When to use a plain VM

Choose a VM when you need:

• Full control over the operating system
• Custom software installations and configurations
• Direct GPU access for specialized workloads
• Long-running processes or services
• Development environments with specific requirements

Consider alternatives when:

• You want a ready-to-run AI environment: use the ComfyUI or Torch + Jupyter starting point instead of a plain VM

Choosing an OS image

VM machines launch from one of the templates listed in VM Templates, Ubuntu, Alpine, Debian, CentOS, Fedora, Arch, or a PyTorch/TensorFlow image, each with its own list of providers that support it. See that page for the full list and provider support.

For how to actually launch one, see Launching a setup.

The machine page

Open a machine from Machines to get its detail page: breadcrumb GENERAL > Machines > Machine Details.

Header actions:

• Open terminal: opens a shell on the box directly in the console
• Save & pause: snapshots the setup and releases the machine, see Pausing and resuming
• Close deployment: ends the deployment

There's no Stop or Restart action. The machine is either running, or paused/closed, and coming back from paused is a resume, not a reboot.

The stat row shows Status (Running, with when the agent last replied), Uptime, Burn rate (cost per hour while it runs), and Spent so far.

Tabs:

• Overview: summary of the machine, including its deployment history and a Change machine action for moving the setup to different hardware
• Metrics: GPU, CPU, and system usage over time
• Terminal: appears when a live shell is available
• Settings: includes idle auto-pause configuration

Set up access credentials

SSH Keys

Manage your SSH keys from Settings > SSH keys (/settings/ssh-keys). You can add multiple keys and see which deployments each key is attached to.

1. Go to SSH keys in Settings and click Add SSH key
2. Paste your public key, generate one locally if needed:

   ssh-keygen -t rsa -b 4096 -C "your-email@example.com"
   cat ~/.ssh/id_rsa.pub

3. Give the key a name and save it
4. Select the saved key when launching your setup

Connect to your VM

SSH connection (command line)

1. Find your machine's connection details on its detail page
2. Copy the SSH command provided:

   ssh -i ~/.ssh/id_rsa user@[VM-IP-ADDRESS]

3. Accept the host key when prompted

VS Code Remote SSH

1. Install the Remote-SSH extension in VS Code
2. Add your VM to your SSH config:

   Host aquanode-vm
       HostName [VM-IP-ADDRESS]
       User user
       IdentityFile ~/.ssh/id_rsa

3. Connect via Command Palette: Remote-SSH: Connect to Host

Verify GPU access

Confirm your GPU is available and working:

# Check GPU status
nvidia-smi

# Verify CUDA installation
nvcc --version

# Test PyTorch GPU access (if installed)
python -c "import torch; print(torch.cuda.is_available())"

Install your software

Your VM comes with a base system. Install additional software as needed:

# Update system
sudo apt update && sudo apt upgrade -y

# Install Python packages
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
pip install jupyter jupyterlab
jupyter lab --ip=0.0.0.0 --allow-root

# Git and development essentials
sudo apt install git vim tmux htop -y

Startup Scripts

Startup scripts let you automate initialization: install packages, clone repos, or configure your environment automatically every time a machine launches from your setup.

1. Go to Settings > Startup Scripts (/settings/startup-scripts)
2. Click New script
3. Write your shell script, give it a name, and save it
4. Select the script when launching your setup

The script runs as root on first boot, so you can use it to:

• Install system packages (apt install, pip install)
• Clone and set up your codebase
• Configure environment variables or services
• Start background processes

Machine lifecycle

There's no Start/Stop/Restart for a machine, only pause and resume:

• Save & pause: snapshots the setup and releases the machine, billing for compute stops
• Resume: launches a fresh machine from the saved setup, on whatever matching capacity is available

See Pausing and resuming for the full mechanics, including what can change (provider, region, price) between pause and resume.

Your machine's storage persists across a pause/resume cycle only if it's captured, either by your own Save & pause, or by an automated snapshot if the provider takes the box away without warning. Whether a machine has automated snapshot paths, and on what interval, is shown on the Snapshots card of its Overview tab. That card is read-only: there is currently no console control to add a path or change the interval, so the capture you control is saving a version.

Best practices

Security

• Keep your SSH keys secure and rotate them regularly
• Keep your VM updated with security patches
• Use firewalls to restrict access to necessary ports only

Cost and reliability

• Save & pause machines when you're not actively using them
• Use idle auto-pause (in the machine's Settings tab) to avoid paying for a forgotten machine
• On community/spot-style capacity, save a version often. The provider can reclaim the machine without warning, and anything newer than the last capture is gone

Troubleshooting

VM won't start:

• Check your account credits and billing status
• Contact support if issues persist

Can't connect via SSH:

• Verify the SSH key is correctly formatted
• Check if the VM is fully booted
• Ensure your network allows SSH connections

GPU not detected:

• Run nvidia-smi to check driver status
• Contact support for persistent GPU issues

Ready to launch a machine? Head to Launching a setup.