isard

Manage your IsardVDI virtual desktops on the Gencat educational platform (elmeuescriptori.gestioeducativa.gencat.cat) from the command line.

isard login          # authenticate (SAML + JWT)
isard list           # your desktops
isard create dev     # a desktop from a template
isard start dev      # power on
isard view dev       # open in virt-viewer
isard ssh dev        # ssh into it

Install

uv tool install isard      # recommended
pipx install isard
pip install isard

Requires Python 3.11 or newer. uv tool install fetches a suitable Python for you if the system one is older.

Upgrade the same way you installed:

uv tool upgrade isard
pipx upgrade isard
pip install --upgrade isard

Authenticate

Running any command prompts for your credentials. To skip the prompt, set them in the environment:

export GENCAT_USERNAME="12345678a"     # @edu.gencat.cat is added for you
export GENCAT_PASSWORD="your-password"

…or drop a .env file in your working directory:

GENCAT_USERNAME=12345678a
GENCAT_PASSWORD=your-password

Sessions are cached in ~/.config/isard/ (%APPDATA%\isard\ on Windows) with chmod 600, and refresh themselves when they expire. isard logout clears them.

Commands

Full reference with every flag and behaviour: docs/commands.md, also published at https://isard.xtec.dev/commands.

Examples

isard list --hardware                  # add CPU + memory columns
isard template --filter fedora         # narrow the template list
isard create dev --template fedora     # fuzzy: resolves to fedora-server-44
isard start dev --wait --timeout 300   # block until it's running
isard start gpu-box --book             # book a vGPU slot first, then start
isard delete dev --permanent --yes     # skip the trash and the prompt
isard media add ubuntu-24 --url https://releases.ubuntu.com/24.04/…-amd64.iso

Name resolution

Desktop and template names resolve by exact match first, then Jaro-Winkler fuzzy matching, then substring. A typo still finds the right desktop; an ambiguous name opens a picker. In scripts (no TTY) an ambiguous name is an error rather than a guess.

SSH

isard ssh handles the plumbing: it resolves your private key (--identity, ~/.ssh/id_ed25519, ~/.ssh/id_rsa, or generates a new ed25519 key), registers the public key with the IsardVDI bastion, starts the desktop if it's stopped, and connects through port 443.

The first connection to a desktop shows its guest credentials half-masked and asks you to confirm them. Confirmed desktops are remembered in ~/.config/isard/desktop-creds.json, which holds ids only — no passwords. Use --password to set new guest credentials (the desktop is stopped, updated, and restarted).

If OpenSSH isn't installed, an embedded pure-Python client takes over.

virt-viewer

isard view installs remote-viewer if it's missing:

Pass --no-install to skip that.

Building a template from a file

isard build takes one YAML file and gives back a finished template — newest ISO, a short manual install in a viewer, then packages and commands applied over the SSH bastion, and promote:

# ubuntu.yaml
image: { distro: ubuntu, variant: server, release: lts }
template: { name: ubuntu-lts-base, memory_gb: 8, disk_gb: 100 }
user:
  name: isard
  password_env: ISARD_TEMPLATE_PASSWORD
  ssh_key: ~/.ssh/id_ed25519.pub
packages: [git, curl, docker.io]
run:
  - systemctl enable --now docker

isard build ubuntu.yaml --dry-run   # see the plan without touching the API
isard build ubuntu.yaml

One step is yours: when the viewer opens, install the OS with the profile's username and password and an SSH server — three fields on the installer's own screens. Shut the machine down and the CLI takes over again. Full reference: docs/build-profiles.md, examples in examples/build/.

Unattended templates, by hand

The lower-level path is still there: build a seed ISO whose volume label the installer auto-discovers (CIDATA for cloud-init, OEMDRV for Anaconda), host it over HTTPS, and hand the URL to template create:

isard seed oemdrv --kickstart my-ks.cfg -o seed.iso
# host seed.iso somewhere IsardVDI can reach it
isard template create --seed-url https://your-host/seed.iso

Starter configs are in examples/seed/; the end-to-end runbook is docs/phase3-verification.md.

Use it as a library

Everything the CLI does is importable:

from isard import get_desktops, login_to_isardvdi

session = login_to_isardvdi("12345678a@edu.gencat.cat", "…")
for desktop in get_desktops(session):
    print(desktop.name, desktop.state)

See docs/library-api.md.

Development

git clone git@github.com:ddemingo/isard.git
cd isard
uv sync --dev
uv run pytest          # no network needed
uv run ruff check .
uv run isard --help

Design notes and invariants: docs/architecture.md. Every IsardVDI endpoint we call: docs/api-endpoints.md.

License

Licensed under either of MIT or Apache-2.0, at your option. Unless you state otherwise, any contribution you submit for inclusion is dual-licensed on those same terms.

Copyright © 2026 Optersoft, S.L.

Built for the Gencat educational platform — you'll need valid IsardVDI credentials to use it.