hangar.
Sign inStart your first jobB
All docs

Quickstart

Quickstart. Quickstart takes you from nothing to a verified GPU job in three commands. A job uses your prepaid credit: an NVIDIA L4 costs A$4.55 an hour including GST, charged by the second.

On your machine#

  1. Install:

$ brew install talos-defence/hangar/hangar

  1. Sign in. Your browser opens. If you are not signed in to Hangar, the browser asks for a code that Hangar sends by email, then for your passkey. Check that the browser shows the same code as the terminal, and approve with your passkey. hangar login prints your credit, then offers to write a first job:

``` $ hangar login Open https://gethangar.au/device and enter the code WDJB-MJHT. Your browser is open at that address. Approve the sign-in there. Waiting for approval. Signed in as alex@harbourwater.com.au for Harbour Water Pty Ltd. Credit A$50.00.

Write a first job to ./hello_gpu? [Y/n] y Wrote hello_gpu/hangar.toml: an NVIDIA L4 in Sydney prints its name and memory. Run it with cd hello_gpu && hangar run ```

hello_gpu/hangar.toml sets the GPU, a public CUDA image (by its digest) and the command. Hangar fetches the image into Sydney, so you do not need Docker on your machine.

  1. Start the first job, and watch it from the image to the certificate:

``` $ cd hello_gpu && hangar run docker.io/nvidia/cuda@sha256:5c0e9a17d2b4 NVIDIA L4, Sydney alex@harbourwater.com.au

✓ Image sha256:5c0e9a17d2b4 ✓ Session HG-C9P4WD, A$4.55 an hour by the second, ends by 16:12:31 AEDT ✓ Instance fresh L4 in apse2-az1 attested at 15:12:32, reset passed at 15:12:33 ● Running 0:00:04 A$0.01 so far ────────────────────────────────────────────────────────────────────────────── 15:12:33 name, memory.total [MiB] 15:12:33 NVIDIA L4, 23034 MiB ✓ Returned succeeded in 0:00:09 A$0.02, including GST of A$0.01

Certificate HG-C9P4WD signed 15:13:44 verified on this machine ✓ hangar verify HG-C9P4WD https://gethangar.au/c/C9P4WD ```

The certificate is the record of the job that Hangar signs. The certificate shows the fresh instance, the image digest, the times and the outcome. To check the certificate again, run hangar verify HG-C9P4WD. To check a certificate file on any machine, run hangar verify FILE. Checking a file needs no account and no network.

  1. Run your own image the same way. Choose the GPU or CPU with a flag:

$ hangar run --gpu l4 myteam/eval:v3 -- python eval.py $ hangar run --gpu h100 myteam/train:v3 --limit 60 -- python train.py $ hangar run --cpu 4 myteam/etl:v3 -- python etl.py

To send an image that you built, run hangar upload --image ./eval.oci.tar --name myteam/eval:v3. To use a public image, give its digest. To see the GPUs free now with their prices, your jobs and the next command to type, run hangar with no arguments.

From CI#

A CI pipeline sends its image, runs the image on a GPU and keeps the verified certificate. The pipeline uses a request key, and no person is signed in. A request key, a pipe or the CI variable turns every question off. If a value is missing, the error shows the flag to add.

  1. An owner makes a key with the jobs and uploads capabilities and a spend limit. The owner does this once, and keeps the secret in the secret store of the CI system:

$ hangar keys create --name ci --capability jobs --capability uploads --spend-limit 200 --save ci.key Key hgk_syd_7c41e0b3d9f2a81c5e604b2d made for Harbour Water Pty Ltd ✓ capabilities jobs, uploads scope the organisation ends Thu 21 Jan 2027 spend limit A$200.00

  1. The pipeline sets HANGAR_KEY_ID to the id of the key. The pipeline sets HANGAR_KEY_FILE to the file that contains the secret of the key. Set the file mode to 0600.
  2. The pipeline sends its image:

$ hangar upload --image ./trainer.oci.tar --name trainer:v1

  1. The pipeline runs the image on a GPU and waits for the job to end. The first line of the view shows the key. The exit status shows the result of the job: 0 when your command ended with exit code 0, and 1 when it did not. Hangar prints the certificate in both cases:

``` $ hangar run --gpu l4 trainer:v1 -- python train.py trainer:v1 NVIDIA L4, Sydney key hgk_syd_7c41e0b3

✓ Image sha256:1e7b30c4a9d5 trainer:v1 ✓ Session HG-C9P4WD, A$4.55 an hour by the second, ends by 16:12:31 AEDT started by key hgk_syd_7c41e0b3 ... Certificate HG-C9P4WD signed 15:13:44 verified on this machine ✓ ```

With --json, the command prints one JSON document when the job ends. To read the certificate id, run hangar run --gpu l4 trainer:v1 --json -- python train.py | jq -r .certificate.id.

  1. The pipeline keeps the outputs and the certificate as build artefacts:

$ hangar pull HG-C9P4WD ./artefacts

hangar pull checks every output against its digest, and verifies the certificate before it saves the certificate. hangar verify ./artefacts/HG-C9P4WD.cert checks the certificate file again, offline, on any machine.

A key pays only for the jobs that the key starts. A key never spends more than its spend limit. When a key reaches the limit, Hangar starts no job for the key, and hangar run shows why:

  ✗ Refused    This key has reached its A$200.00 spend limit, so Hangar started
               nothing and charged nothing.
  Raise the limit with hangar keys limit, or create a new key.
  If you cannot change keys, ask an owner of your organisation to raise the limit.

An owner raises the limit with hangar keys limit hgk_syd_7c41e0b3 300. hangar keys list and the Keys page show what each key has spent, how many jobs the key started and how many images the key sent.