Skip to main content

Hetzner Cloud Agent Update

On Hetzner, the Fractal Cloud Agent runs as a Docker container on a Virtual Machine. Updating the agent involves SSH-ing into the VM, pulling the new image, and restarting the container.

For common prerequisites (regctl installation, Fractal registry authentication), see the main guide.

Availability

Hetzner Cloud Agent updates are currently available for enterprise customers only.

Step 1 — Identify the agent VM​

Locate the VM running the Fractal Cloud Agent. You can find it through the Hetzner Cloud Console or the CLI:

hcloud server list

Look for the server associated with the Fractal Cloud Agent (it will typically be tagged or named with a fractal identifier).

Step 2 — SSH into the VM​

ssh root@<SERVER_IP>

Step 3 — Authenticate with the Fractal private registry​

On the VM, log in to the Fractal private Docker Hub registry:

docker login -u <FRACTAL_DOCKER_USERNAME>

Enter your PAT when prompted.

Step 4 — Pull the new image and restart the container​

# Pull the new image
docker pull yanchware/fractal.cloudagent.hetzner.container:<NEW_VERSION>

# Find the running agent container
docker ps --filter "name=fractal" --format "{{.ID}} {{.Image}} {{.Names}}"

# Stop the current container
docker stop <CONTAINER_ID>

# Start the new container with the same configuration
# (use the same environment variables, volumes, and network settings as the previous container)
docker run -d \
  --name <CONTAINER_NAME> \
  --restart unless-stopped \
  --env-file /etc/fractal/agent.env \
  yanchware/fractal.cloudagent.hetzner.container:<NEW_VERSION>
Important

Make sure to preserve the existing environment variables and volume mounts when starting the new container. Check the current container's configuration with docker inspect <CONTAINER_ID> before stopping it.

Step 5 — Verify the update​

# Check the container is running
docker ps --filter "name=fractal"

# Check the logs for successful startup
docker logs --tail 50 <CONTAINER_NAME>

Confirm the agent is reporting to the Fractal Cloud control plane.

Step 6 — Clean up​

Remove the old image to free up disk space:

docker image prune -f