Azul AI

Connect your workstation

Turn a GPU machine you own into a place Azul can train and serve models, with one command.

Azul trains and serves on hardware you own. Connecting a machine takes one command, pasted into a shell on that machine. This guide covers what you need, where to get the command, how to confirm the machine is online, and how to fix the usual hiccups.

Requirements

Your machine needs:

  • Linux with an NVIDIA GPU. The NVIDIA driver should be installed, so nvidia-smi lists your GPU.
  • Docker Engine with the Compose plugin. docker compose version should work, and your user should be able to talk to the Docker daemon, usually by being in the docker group.
  • The NVIDIA Container Toolkit, registered with Docker as the nvidia runtime. It's a separate package from the driver, so a working nvidia-smi doesn't mean you have it. If this is the only thing missing, the installer offers to set it up for you. That works on Docker Engine managed by systemd, but not on Docker Desktop or rootless Docker. The installer never installs Docker or the driver itself.
  • Outbound HTTPS to azulai.dev. Nothing connects inbound to your machine, so there are no ports to open and no firewall rules to add.

Not sure? Run this on the machine:

nvidia-smi -L
docker compose version
docker info --format '{{range $k, $v := .Runtimes}}{{$k}} {{end}}'

The last line should include nvidia. The installer runs the same checks before it writes anything and lists everything that's missing at once, so you can also just run it and read what it says.

Get your connect command

  1. In Azul, open Settings and find the Connect infrastructure card.
  2. Click Generate connect command. You'll get a command like this, with your own token in it:
curl -fsSL https://azulai.dev/install.sh | bash -s -- azen_XXXXXXXXXXXXXXXX https://azulai.dev

The token identifies your account, and the same command works on every machine you own. Paste it by hand, or drop it into Ansible, pdsh or cloud-init as is.

Treat the token like a password: anyone who has it can add machines to your account. If it ever leaks, generate a new command from the same card. The old one stops working everywhere it was pasted, and machines that are already connected keep working with their own credentials.

Prefer one credential per machine? Settings can also add a single machine with a one-time command that works only for that machine.

Install the agent

Paste the command into a shell on the machine, as the user who normally runs Docker there. The installer:

  1. Checks the requirements above and reports every gap at once.
  2. Writes a small Docker setup to ~/azul-workstation: a Compose file, an env file with your token, and a bootstrap script.
  3. Starts one container from a public PyTorch image. Each time it starts, it downloads the Azul agent and runs it.

The first start pulls the image, so give it a few minutes on a slow connection. You don't need to keep the shell open afterwards. The container starts with Docker and survives reboots.

A second install on the same host is rare, but if you need one, set AZUL_HOME to a different directory before running the command so the two installs don't share ~/azul-workstation.

Confirm it's online

Back in Settings, the Connect infrastructure card lists machines as they appear, named after their hostname. A new machine shows Connecting, then Online once it has reported its GPUs, usually within seconds of the container starting. You'll see the GPUs it found.

From then on, when you start a training run, Where to train offers My workstation (or My workstations with a dropdown, once you have more than one). The run waits as Pending until the machine picks it up on its next poll, which takes seconds while it's online.

Everyday use

Updates

The agent checks for new releases of its own software and restarts itself to pick them up. There's nothing for you to do. If you're ever asked to restart it by hand:

docker compose -f ~/azul-workstation/docker-compose.yml restart

If the machine is off or asleep

It shows Offline in Settings. Runs you start for it wait as Pending until it's back, for up to a day, then fail with a message naming the machine.

Machines with more than one GPU

A run can use all of a machine's cards together. The training form offers Use all N GPUs and turns it on by default when the machine has more than one. In the card's GPU map you can also reserve cards for serving, so training never takes them.

Plan limits

The Free plan connects one machine, Pro four, Team sixteen. A machine counts once, however many GPUs it has. Removing a machine in Settings frees its slot.

Removing a machine

Remove it in Settings, then generate a new connect command. Removing it stops it from getting work; the new command stops it from registering itself again.

What stays on your machine

  • Training runs on your GPU inside the container. Datasets are downloaded to the machine for the run, finished model files are uploaded to Azul storage so your dashboard and your other machines can use them, and checkpoints stay on the machine.
  • Progress, loss curves and logs are sent to Azul so your dashboard works from anywhere.
  • The container only makes outbound HTTPS connections, to fetch work and report back.
  • If you deploy a model to the machine, it's served on the machine itself or your local network, never on the internet.

Troubleshooting

The container won't start, with "unknown or invalid runtime name: nvidia" or "could not select device driver". The NVIDIA Container Toolkit is missing or isn't registered with Docker. Install it, then register it and restart Docker:

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

Then run the connect command again. Restarting Docker briefly stops every container on the machine.

The machine never shows up in Settings. Run the connect command again and read its output; it names every missing requirement. If it finishes without complaint, look at the container:

docker ps
docker compose -f ~/azul-workstation/docker-compose.yml logs --tail 50

docker ps should show a container named like azul-workstation-azul-agent-1. The log tail tells you why it stopped. Most often it's a connect command that has since been replaced (generate a new one and run it again) or no route to azulai.dev.

It shows Offline. The container stopped or the machine lost its network. Bring it back with:

docker compose -f ~/azul-workstation/docker-compose.yml up -d

A run sits in Pending. The machine it was given to is Offline, or you changed its GPU map and no card is left for training. Pending runs wait up to a day, then fail with a message that names the machine.

A run failed because the machine went silent. Power, network, or the container stopped mid-run. Bring the machine back, then press Restart on the run's page. It starts over from the beginning.