The glac command line

Questa pagina non è ancora tradotta in italiano: eccola in inglese.

glac calls the same API as the SDKs. Its commands are grouped by product, as the platform is: glac cube …, glac sandboxes …, glac drives …, with the project and the account at the top. It is written for three kinds of user: a person at a terminal, a script in CI, and a coding agent. So:

• By default it prints the one thing you asked for (an id, a table, the command’s own output). Every command takes --json and then prints what the API returned, errors too.
• glac run, glac sandboxes exec and glac sandboxes shell exit with the exit code of the command in the sandbox. A failure that is not the command’s is 125.
• On an error it prints the API’s message and code on stderr.
• It never waits for input it was not asked to read, and never deletes what it was not asked to delete.

Install

glac is one file (1.7 MB on macOS arm64, 2.3 MB on Linux x86_64) that starts in about 3 ms. Install it with:

curl -fsSL https://glac.ai/install.sh | sh

Configure

glac reads GLAC_API_URL and GLAC_API_KEY (the same two as the SDKs), then the file glac login writes (~/.config/glac/config.json, mode 0600; $XDG_CONFIG_HOME and GLAC_CONFIG move it). Without either, it talks to https://api.glac.ai.

glac login --api-url https://api.glac.ai --api-key -     # reads the key from standard input

A token for one sandbox (st_…) works as a key too, for exec, cp, shell and url on that sandbox. HTTPS uses the Mozilla root certificates built into glac; SSL_CERT_FILE adds your own. Redirects are not followed, so a key is never sent elsewhere.

The commands

glac deploy IMAGE …              the same as glac cube deploy
glac run COMMAND …               the same as glac sandboxes run
glac install APP …               the same as glac installations create

glac cube       deploy | ls | get | update | rm | versions | rollback | upgrade | upgrades | logs | log-usage | log-delete | metrics
glac cube instances       create | ls | get | rm
glac cube instances ports ls | open | close
glac cube key-secrets     create | ls | get | rm
glac cube keys            sign
glac compose    up | config | down | ps | logs | restart
glac deploys    create | ls | get
glac sandboxes  run | create | ls | get | update | rm | sleep | restart | exec | ps | logs | kill
                | shell | cp | url | fork | restore | ssh
glac sandboxes snapshots  create | ls | get | rename | rm
glac sandboxes ssh-keys   add | ls | get | rm
glac sandboxes tokens     revoke
glac sandboxes ports      ls | open | close
glac browsers   create | ls | get | update | sleep | rotate-url | live | save-profile | profiles ls | profiles rm | rm
glac drives     create | ls | get | rename | rm | attach | detach | fork | restore
glac drives snapshots     create | ls | get | rm
glac volumes    create | ls | get | rm | attach | detach
glac backups    ls | create | get | rm | restore
glac domains    create | ls | get | update | rm
glac db         create | ls | get | update | rm | sleep | wake | restore | roles | reset-password
glac db branches          ls | get | create | rm
glac catalogue  ls | get
glac installations  create | ls | get | update | rm

glac project · glac variables put | ls | rm · glac secrets put | hosts | ls | rm · glac events · glac audit
glac webhooks   create | ls | get | update | rm
glac keys       create | ls | get | rm
glac destinations   create | ls | get | update | test | rm
glac limits · glac limits request | requests
glac usage · glac account … · glac billing … · glac login · glac logout · glac version

Every group answers to its singular too (glac sandbox, glac browser, glac drive, glac volume, glac backup, glac secret, glac variable, glac domain, glac database, glac installation, glac db branch, glac cube instance, glac sandboxes snapshot, glac sandboxes ssh-key, glac sandboxes token, glac sandboxes port, glac drives snapshot), glac workers is glac cube, and glac sbx is glac sandboxes: glac sbx exec web ls is glac sandboxes exec web ls. glac help lists every command by product, glac help sandboxes the commands of one group, glac help sandboxes exec what one command takes. Options and columns keep the API’s names: a Cube is an app there. An app, a sandbox, a snapshot, a Drive, a volume and an SSH key are named by their id or their name, a version of an app by its number or its id, and a snapshot of a Drive (dsnap-…) and a backup (bak-…) by their ids.

Cube

Cube runs an image as a service, a Cube, which the API calls an app. glac workers … (or glac worker …) is another name for glac cube ….

Sandbox

How a command is written: one argument is a line for sh -c (glac sandboxes exec web 'ls | wc -l'); several are a program and its arguments, run as they are. Standard input that is not a terminal is passed to glac sandboxes exec (tar c . | glac sbx exec web tar x -C /srv); --no-stdin stops that. The first Ctrl-C goes to the command; a second leaves it running. A command belongs to the sandbox, not to the connection: glac sandboxes exec and glac sandboxes logs --follow pick up where they were after a dropped connection.

Only the last 16 MiB of a command’s output is kept, and a command never waits for a slow reader. When glac sandboxes exec misses part of the output it says how much and exits 125, rather than pass on output with a hole in it. Write large output to a file and glac sandboxes cp it out.

Drive

A Drive is a disk of the project’s that outlives the sandboxes that use it: one sandbox has it at a time, read-write, and what it holds stays for the next sandbox: of its region, or of another whose machines read its home’s object store (glac drives home, below). It is copied into its region’s object store as it is written, so a sandbox on another node mounts it too. Only what is written is billed. Drives are a control plane’s: against a node that stands alone glac drives … gets the node’s 404 (exit 4), and says that its disks are volumes.

A snapshot is mounted read-only by any number of sandboxes at once, on any machine of the Drive’s region, whatever has the Drive and after it is deleted: glac sandboxes create --drive data:/snap:dsnap-… for a new sandbox (--snapshot there is the sandbox snapshot it goes on from, so a Drive’s snapshot rides on --drive, as :ro rides on --volume), glac drives attach data web:/snap --snapshot dsnap-… for one that runs. The guest cannot write it, and a sandbox that has one is not moved to another machine. An app’s version mounts a Drive read-write only.

Billing: a snapshot is billed for what it keeps alone (exclusive_bytes), by the hour, at the Drives’ data price ($0.02 a GB-month). A fork is billed like any Drive, by its used_bytes, its full logical contents: a fork of a 10 GB snapshot is billed as a 10 GB Drive. What a sandbox reads through a read-only mount costs nothing. glac usage --drive data reports what one Drive kept, was written and read cold, and glac usage --snapshot dsnap-… what one snapshot kept.

Domains

Browser

Not open yet. Browser is not open to accounts yet: what follows is the command line as it stands, ahead of its opening.

A session is a hosted Chromium that Playwright, Puppeteer or any other client of the Chrome DevTools Protocol (CDP) drives from outside. It is awake while a client is connected and falls asleep, its pages kept, a few seconds after the last one leaves.

CDP=$(glac browsers create --name agent-42)
npx @playwright/mcp --cdp-endpoint "$CDP"        # or any CDP client

A session is billed by the Cube resources it uses, as any instance is: its CPU while it computes, its memory while it is awake and its traffic out (pricing and plans). glac usage gives a session’s use beside its sandbox.

Databases

A database is a managed Postgres: a PostgreSQL of its own on a Drive, asleep when nothing asks anything of it and woken by a connection, its sessions kept. The owner’s password is in the API’s answer to a create and to a reset alone, and kept nowhere: so create and reset-password print the connection string with it, and no other command prints it.

URI=$(glac db create shop)                                    # the owner's password is in it
glac sandboxes create --name client --project-network --image postgres:17-alpine
glac sandboxes exec client -- psql "$URI" -c 'select 1'       # on the project's network

A database is reached today on the project’s network, from its sandboxes (--project-network) and services, at its name; its public address comes with the platform’s public entrance, and create prints it instead where the API gives one (--private prints the one on the project’s network whatever there is). --json prints what the API answered: the password is in a create’s and a reset’s answers alone.

Managed Applications

An application of the catalogue (Rivet, say) is installed in the project as its own Cube resources: its apps, Volumes, secrets and buckets, labelled with the installation, changed through it alone, and billed as they are (Managed Applications).

glac catalogue get rivet
glac install rivet --set disk_gib=20 --set size.vcpus=2

The project: secrets, shared variables, events and the audit log

Account, usage and billing

Changing billing, secrets, domains and keys needs a key with the admin scope.

Buying at once (--start-now). A consumer in the European Economic Area or the United Kingdom (an account with no tax id that is verified or being verified) may withdraw from a purchase within 14 days, and what it buys is provided at once only at its own express request. --start-now on glac billing topup, glac billing plan (a plan that is bought: from Free, or a move up) and glac billing auto-reload on (for every auto reload while auto reload stays on) carries that request, in the words the console shows beside its box (and GET /v1/billing/withdrawals has, right.start_now):

I ask for this purchase to be provided at once, within the 14 days in which I may withdraw from it. If I withdraw, I pay for what was provided until then. I understand that once all the Credits of a top-up are used, it has been provided in full and I can no longer withdraw from it.

The service starts now; within the 14 days the buyer may still withdraw, and pays for what was provided until then; once it is fully provided (a top-up whose Credits are all used), the right to withdraw is lost. Give it only when the person buying asks for that: glac never sends it unless it is given. Without it, such an account’s purchase is the API’s 400 start_now_required, and nothing is bought. Then, where standard input and standard error are both a terminal, glac shows the words and what they mean and asks Do you ask for this? [y/N]; only y or yes sends the same call again with the request (a top-up under a new idempotency key). Anywhere else (a script, CI, a coding agent), and always with --json, nothing is asked: the API’s error, exit code 1, and one more line that says what --start-now gives. An agent never gives the request for a person: it is theirs to give. An account whose auto reload is on without the request reloads nothing, and is told once a month (the event auto_reload.no_request, which glac events says in words).

Exit codes