Machines

A Machine is the rented GPU box your pod runs on. It's separate from the Pod that owns it: the pod 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 built-in Environment 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 pod.

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
• Stop: captures the pod's environment and volume and releases the machine, see Stop, start, and move
• Move to another GPU: stops the pod and starts it on different hardware
• Close deployment: ends the deployment

There's no Restart action. The machine is either running, or stopped/closed, and coming back from stopped is a start on a fresh machine, 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
• Metrics: GPU, CPU, and system usage over time
• Terminal: appears when a live shell is available
• Settings: includes idle auto-stop 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 pod

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 pod.

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 pod

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 Restart for a machine, only Stop and Start:

• Stop: captures the pod's environment and volume and releases the machine, billing for compute stops
• Start: launches a fresh machine from the pod's saved environment and volume, on whatever matching capacity is available

See Stop, start, and move for the full mechanics, including what can change (provider, region, price) between stop and start.

Your machine's Volume persists across a stop/start cycle because Stop always captures it. It also saves itself periodically while the pod runs, so a provider taking the box away without warning loses at most the interval since the last save, not everything since the last Stop. The Volume page shows Saved <N> s ago, or a loud Last save failed if a save could not complete.

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

• Stop machines when you're not actively using them
• Use idle auto-stop (in the machine's Settings tab) to avoid paying for a forgotten machine
• On preemptible/spot-style capacity, the periodic save tick already bounds your worst case to one interval, but a manual Stop before a long unattended run is still the clean point to fall back to

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 pod.