canfar-lab

The canfar lab commands you run inside an AstroAI session on the CANFAR Science Platform. The same tree is the standalone canfar-lab binary.

Start and stop sessions with canfar (or the Science Portal). Inside the session, canfar lab does three jobs:

1. Project env — init / clone / save / resume (lockfiles on /arc)
2. Ray cluster — cluster start / status / run / jobs
3. Agents — agent setup / install / verify

flowchart LR
  subgraph laptop [Laptop or portal]
    Portal[Science Portal]
    CanfarCLI["canfar login / create"]
  end
  subgraph session [AstroAI session]
    Lab["canfar lab"]
    Tools["pixi / uv / Jupyter / CADC / Ray"]
  end
  Portal --> session
  CanfarCLI --> session
  Lab --> Tools

Images: canfar-containers.

Inside a session

canfar lab                      # status banner
canfar lab init mylab           # or: clone owner/repo
canfar lab save                    # lockfile snapshot to /arc
canfar lab resume mylab
canfar lab status                  # quotas, sessions (not the Ray cluster)

canfar lab cluster start
canfar lab cluster status
canfar lab run train.py --cpus 2

canfar lab kernel ensure
canfar lab agent setup

canfar lab status is this session’s CPU/disk/quota. canfar lab cluster status is whether the Ray cluster is up. canfar lab cluster stop tears down workers and the manager.

Help: canfar lab help · one command: canfar lab help -c cluster · cheat sheet: docs/help.md

Install

pip install canfar-lab
canfar-lab --help

Do not pass --user. On a CANFAR session that writes /arc/home/.local. If the image Python is not writable, uv pip install --python /opt/canfar canfar-lab. Upgrade with pip install -U canfar-lab. Session images that already include the package put canfar-lab on PATH.

Docs

Data movement is not this CLI. Use canfar data and vcp / vls.

Development

./scripts/ci.sh
pixi run test

MIT. canfar keeps its own license.