TypeScript SDK

Trang này chưa được dịch sang Tiếng Việt: đây là bản tiếng Anh.

Install

No dependencies: it uses fetch, WebSocket and node:crypto, and Node 23.6 or later runs its TypeScript sources directly. The package is glac on npm, with JavaScript and type declarations for runtimes that do not run TypeScript:

npm install glac

First lines

import { Glac, Sandbox } from "glac";

const glac = new Glac();                                    // GLAC_API_KEY and GLAC_API_URL; or new Glac({ apiKey, baseUrl })

const app = await glac.cube.deploy("ghcr.io/acme/api:1.4", { name: "api", port: 8080 });   // Cube: waits until it serves
console.log(app.url);

const sbx = await glac.sandboxes.create({ image: "python:3.12" });                           // Sandbox
console.log((await sbx.run("python3 -c 'print(6*7)'")).stdout);                             // res.stdout, res.stderr, res.exitCode

const drive = await glac.drives.create({ name: "data", sizeBytes: 10 * 2 ** 30 });           // Drive: disks that outlive sandboxes

console.log((await Sandbox.run("echo hello")).stdout);      // the shorthand: a sandbox for one command, on the default client

The client

new Glac({ apiKey, baseUrl, retries }) is one key at one address; what is not given is read from GLAC_API_KEY and GLAC_API_URL. It has a namespace for each product:

The platform’s own calls are the client’s methods: glac.account(), updateAccount(), usage(), billing(), updateBilling(), balance(), updateBalance(), topUp(usd), charges(), ledger(), project() and events(). An API the SDK does not wrap: glac.json("GET", "/v1/webhooks"), and glac.pages(path) for lists. What a call returns (a Sandbox, an App, a Drive, a Volume) keeps its client, and its own methods use it.

The shorthand: Sandbox.run, Sandbox.create, Sandbox.get, Sandbox.getOrCreate and Sandbox.list are the calls of glac.sandboxes on the default client, which is made from GLAC_API_KEY and GLAC_API_URL the first time; { client } names another. No other product has one.

undefined options are not sent. null means something on some options: sleepAfterSeconds: null is never sleep, sleepNoticeMs: null in an update tells its programs nothing more before it sleeps, env: { KEY: null } deletes a key, egress: null removes all network rules.

Cube

A Cube, which the API calls an app, is an image that runs as a service at an address of its own, with as many instances as its requests need and none while there are none. The SDK’s App is one.

import { DeployError, Glac } from "glac";

const glac = new Glac();
const app = await glac.cube.deploy("ghcr.io/acme/api:1.4", { name: "api", port: 8080 });
try {
  await app.deploy({ image: "ghcr.io/acme/api:1.5" });       // a new version, waited for
} catch (e) {
  if (!(e instanceof DeployError)) throw e;                   // it did not come up: the traffic stays where it was
}
for await (const line of app.logs({ follow: true })) if (line.kind === "output") console.log(line.text);

Sandbox

Output as it comes, files, snapshots and forks:

const built = await sbx.run("make", { onStdout: (text) => process.stdout.write(text) });

const cmd = await sbx.exec("node server.js");                       // do not wait
for await (const piece of cmd.output()) process.stdout.write(piece.text);

await sbx.files.write("/tmp/notes.txt", "hello\n");
const before = await sbx.snapshot({ name: "before-upgrade" });      // memory, processes and disk
const [copy] = await sbx.fork();                                     // goes on from this moment
await sbx.restore(before);                                           // back to the snapshot
await copy.delete();

Drive

A Drive is a disk of the project’s that outlives its sandboxes: mounted read-write by one sandbox at a time, when the sandbox is made or while it runs, and kept, with what it holds, when the sandbox goes, for the next sandbox to mount: of its region, or of another whose machines read its home’s object store (below). It is copied into its region’s object store as it is written, so a sandbox on another node mounts it too: it is brought there first. Only what is written is billed (usedBytes). Drives are a control plane’s (/v1/drives): against a node that stands alone every call throws the node’s 404 no_such_route, and its disks are volumes (below).

const drive = await glac.drives.create({ name: "data", sizeBytes: 10 * 2 ** 30 });   // or none: 64 GiB, or 5 GiB on Free
const sbx = await glac.sandboxes.create({ drives: [{ path: "/data", drive: drive.id }] });
await sbx.files.write("/data/notes.txt", "hello\n");
await glac.drives.detach(sbx, drive);
const other = await glac.sandboxes.create();
await glac.drives.attach(other, drive, "/data");                    // the same Drive, in another sandbox

A Drive has id (a vol-…: a Drive is a volume), name, sizeBytes, usedBytes, attachedTo (the sandbox, the path, the mode), region, home, status, lease (the node of its one writer, the epoch, until when), appId and key (a keyed instance’s), parentDriveId and rootDriveId (a fork’s: the Drive it was forked from, which may be deleted since, and the first of its line; null for a Drive that is no fork), managedBy (a ManagedBy, of a database’s Drive; null for one that is none’s), and attach, detach, update({ name }), refresh() and delete() of its own.

• A Drive is one sandbox’s at a time: one that another sandbox has is refused (409 drive_attached), and so is deleting one that is attached. A keyed instance’s Drive goes with its key (409 key_drive).
• A database’s Drive (drive.managedBy) is mounted read-write by the database’s instance alone, and renamed, restored and deleted through the database: those calls here, and a read-write mount of it, are refused (409 managed_by_database). Its snapshots and forks are the project’s to take, and a snapshot of it anybody’s to mount read-only.
• One that another node holds is brought to the sandbox’s node first; while the object store does not hold it as it is yet (503 copy_behind), or it could not be brought (503 drive_not_brought), the call is retryable: the client tries again as its retries say, then throws, for you to ask again a moment later.
• Across regions (slice D9). A Drive’s home (home) is the region whose object store holds its copy: the region it was made in. A sandbox of another region mounts it too, where that region’s machines read its home’s store (409 not_on_one_machine where they do not): the Drive is let go as a version and taken over there, read from its home’s store as its guest reads it, and what its guest writes goes to the store of the region it is in now (region). Its home follows it once it has been there for an hour, or at once with glac.drives.moveHome(drive) (drive.moveHome()): its machine copies what is left in its home’s store into its own, and home is the new region once nothing is left there; drive.homeMove says how far the move is (asked_at, asked_by, copied_objects, copied_bytes, objects_left, error). Its old home’s copy goes once no version kept needs it (a day after). A Drive’s home moves once in six hours at the most (409 home_moved_recently); one whose home is the region it is in is 409 home_here.
• The plan’s limits: 3 Drives of at most 10 GiB, 15 GiB together, on Free; 500 of at most 1 TiB on Paid (403 drive_limit_reached).
• glac.usage({ drive }), kind: "drive" and groupBy: "drive" report what Drives kept, were written and read cold, and glac.usage({ snapshot: "dsnap-…" }) what a snapshot kept alone. The events drive.created, drive.deleted, drive.attached and drive.detached carry an EventDrive or an EventDriveAttached, and drive.snapshot.created and drive.snapshot.deleted an EventDriveSnapshot.

Snapshots, forks and restores. A snapshot of a Drive is a version of it in the object store: nothing is copied. A Drive a running sandbox writes is snapshotted with its writes held for a moment: with fsConsistent: true the sandbox’s agent freezes its file system (consistency "frozen"; 409 not_frozen where the agent cannot: take it without), otherwise its machine is paused ("paused", the Drive as at a power cut, which its file system’s journal is for); one no running sandbox has is taken as it is ("at_rest"). The hold lasts ten seconds at the most, then the call is refused, 503 unavailable (retryable).

const snap = await drive.snapshot({ name: "before" });                 // a version in the object store: nothing is copied
const reader = await glac.sandboxes.create({ drives: [{ path: "/before", drive: drive.id, snapshot: snap }] });   // read-only
await glac.drives.attachSnapshot(sbx, snap, "/before");                // into a running sandbox too, as many as want it
const copy = await snap.fork({ name: "data-2" });                      // a new Drive, mountable at once
await glac.drives.detach(other, drive);
await drive.restore(snap);                                             // detached first: back to the snapshot

• A snapshot outlives its Drive: it is listed, read, forked and mounted read-only after the Drive is deleted, by the Drive’s id. It is billed for what it keeps alone (exclusiveBytes), by the hour, at the Drives’ data price ($0.02 a GB-month), until it is deleted, after its Drive is too.
• A fork is billed by its usedBytes, its full logical contents, like any Drive: a fork of a 10 GB snapshot is billed as a 10 GB Drive.
• A restore writes a new version after the Drive’s newest whose content is the snapshot’s; the versions in between stay where a snapshot or a fork keeps them, so restoring to an older snapshot and then to a newer one works. What the Drive holds now that no snapshot keeps is gone: take one first. A Drive a sandbox has read-write is not restored (409 drive_attached): detach it first.
• A read-only mount: any number of sandboxes, on any machine of the Drive’s region, whatever has the Drive and after it is deleted. Its blocks come from the object store as the guest reads them, at no cost; they show under the sandbox that mounts it (glac.usage({ sandbox }), drive_cold_read_bytes); what its machine holds already costs nothing. The guest cannot write it, and a sandbox that has one cannot move to another machine. The sandbox lists it among its volumes, with view_of.
• durability of glac.drives.create is standard, or strict, whose guest’s fsync returns once the object store has every write before it; a Drive’s durability says it, for good (how durable a write is).
• A node that copies nothing to an object store has no snapshots, forks or restores (409 not_copied). An app’s version mounts a Drive read-write only: read-only snapshot mounts are a sandbox’s.

glac.volumes is the API’s /v1/volumes, the disks underneath Drives, kept for the transition: what only it has is a node that stands alone, whose disks are volumes, and shared volumes, file systems several sandboxes mount at once. A sandbox or an app mounts one as volumes: [{ path: "/data", volume: vol.id }].

const team = await glac.volumes.create({ name: "team", shared: true });   // no size is needed
const box = await glac.sandboxes.create({ volumes: [{ path: "/team", volume: team.id }] });

Backups of volumes. A backup is a copy of a volume (a Drive is one) at one instant, in the object store, kept until it expires: taken by a call, every day by the volume’s rule, or before a service’s new version replaces its instance. Unlike a snapshot of a Drive it is a copy of its own, a volume is made from it alone, and it outlives its volume; a volume’s backups keep only what changed since the one before, and a block several of them need is billed once, on the earliest. It is making until the store has all of it, then ready, and billed from then by what the store holds of it (storedBytes) at the price of what sleeping sandboxes keep (backups). Backups are a control plane’s.

const b = await glac.volumes.backup("data", { expiresInDays: 7 });        // "making", then "ready"
while ((await b.refresh()).status === "making") await new Promise((r) => setTimeout(r, 1000));
const back = await glac.backups.restore(b, { name: "data-back" });         // a new volume: "restoring", then "ready"

• glac.volumes.backup(volume, { expiresInDays }) (or vol.backup()) takes one now, kept expiresInDays (1 to 365) or as the volume’s rule says (30 days unless it was set); glac.volumes.backups(volume) lists a volume’s, newest first (a deleted volume’s by its id). A node that copies nothing to an object store has none (409 not_copied).
• glac.backups.list({ volume }) lists the project’s, newest first, those of deleted volumes among them; get(backup), delete(backup) (nothing more is billed for it; a volume made from it stays), and restore(backup, { name }), a new volume made from a ready one, the same as glac.volumes.create({ fromBackup, name }) (409 backup_not_ready while it is being made, 409 backup_unusable once it failed). A Backup has id (bak-…), volumeId, status (making, ready, failed), reason (manual, daily, before_version), storedBytes (what it is billed for), ownBytes (what deleting it would save), sharedBytes, volumeName (the volume’s name then), consistency (frozen, crash), frozenMs (how long the volume’s writers waited for the copy; null where it was not frozen), sizeBytes (what the volume held), volumeSizeBytes (the most it held: what a volume made from it holds), shared, region, failure, createdAt, readyAt (from when it is billed), expiresAt, and refresh(), restore({ name }), delete().
• A volume made from a backup has the size and kind of the volume it was taken of (sizeBytes and shared are not given with fromBackup), in the backup’s region. Its status is restoring until it holds the backup whole, then ready, and nothing attaches it before; fromBackup names the backup. Where the machine it was placed on cannot bring it back, the control plane makes it once more on another machine of the region: info.restore_attempt is 2 then, and info.first_failure says why the first try failed. If that fails too, it is failed (info.failure), and can only be deleted.
• glac.usage({ backup }), kind: "backup" and groupBy: "backup" report what backups kept, on the meter of state (state_gb_hours); meters.state.backups_gb_hours of glac.billing() says how much of that meter was backups.

Domains

A domain of the project’s is a name that leads to an app, as its default address does, or to a port of a sandbox. Domains are a control plane’s.

const name = await glac.domains.create("api.example.com", { app: "api" });

Browser

Not open yet. Browser is not open to accounts yet: what follows is the SDK 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, sleep_after_seconds after the last one leaves. Its cdpUrl is all a CDP client needs: the credential is in the address’s host name, so it stays out of the session’s JSON.

await using session = await glac.browsers.create({ name: "agent-42" });   // closed and deleted at the end of the block
const browser = await session.connect();                                  // Playwright, where it is installed
const page = browser.contexts()[0].pages()[0];
await page.goto("https://example.com");

• glac.browsers.create({ kind, name, region, sleep_after_seconds, connection_idle_seconds, delete_after_idle_seconds, metadata, profile, proxy }) makes one, awake (kind: chromium-headless, the default, chromium, on a screen, or lightpanda, a browser without a layout engine); the name of one there is answers that one, woken, with its pages. profile: { name, save, version } loads a profile before the session is answered (below). get(idOrName), list({ status, kind, name }) (status: awake, asleep, unavailable or failed), update(session, changes), delete(session), sleep(session), rotateUrl(session); a BrowserSession has the same of its own. One whose sandbox fails before it runs is no session: its create is refused, 503 session_failed.

• session.status is awake, asleep, unavailable (its node cannot be reached) or failed (its sandbox failed after its create was answered: its browser stopped and did not come back, say), and then session.error says why ({ code, message }, as its node says it; null unless it failed). The event browser.failed says so too (its data typed EventBrowserFailed).

• session.cdpUrl is what chromium.connectOverCDP and Puppeteer’s browserURL take. rotateUrl() gives new addresses: the old ones are refused from then on, and the connections they let in end.

• session.connect({ chromium, timeoutMs }) connects Playwright: playwright or playwright-core where one is installed (neither is this package’s dependency), or the chromium given. close() closes that browser; the session stays, and sleeps once no client is connected.

• session.liveUrl is where its page is watched live in a browser (a headless session’s tab drawn as it changes, a headful one’s screen), the viewer’s mouse and keyboard reaching the page; await session.live({ interactive: false }) gives an address of its own where nothing reaches the page, to show people. A viewer keeps the session awake. Both are rotated by rotateUrl and need the key’s url scope.

• Profiles (its cookies, Local Storage, IndexedDB, Session Storage and preferences, kept by the platform for the project): create({ profile: { name: "acme-login", save: true } }) loads one and saves it again when the session is deleted (delete({ saveProfile: false }) does not); session.saveProfile(name?) saves it now (the browser restarts, and a connected client reconnects; another save of the profile meanwhile is refused 409 profile_busy); session.profile is the one it holds; glac.browsers.profiles.list(), get(name), delete(name).

• Your own proxy, on Paid (403 proxy_not_on_plan on Free): create({ proxy: "http://user:password@proxy.example.com:3128" }) (or { url }) has the session’s connections to ports 80 and 443 go out through that HTTP proxy, which takes CONNECT, by a relay beside the browser, which is told nothing of it; QUIC is refused there, so the browser speaks HTTP over TCP. session.update({ proxy }) changes it on a running session without starting the browser again (its connections through the one before end), { proxy: null } takes it away. The credentials are kept by the platform and are in no answer: session.proxy is { url, username }, and session.proxyBytes what went through it, both ways (proxySentBytes and proxyReceivedBytes, each way). A page whose proxy takes no tunnel is answered 502 proxy_failed over HTTP. See your own proxy.

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). session.awakeSeconds is how long it has been awake. What went through its proxy is its traffic as any. Sessions are a control plane’s.

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. It is made in about two seconds, with a root branch, main, and an owner, glacdb_owner (a member of glac_superuser, no superuser). The owner’s password is in the answer of create and of resetPassword alone, and kept nowhere: connectionString() of the database one of those returned has it.

import pg from "pg";

const db = await glac.databases.create("shop");                              // ready, with the owner's password
const client = new pg.Client({ connectionString: db.connectionString() });   // from a sandbox or a service of the project
await client.connect();
await client.query("create table orders (id bigserial primary key, total numeric)");

• glac.databases.create(name, { version, region, database_name, size, storage, sleep_after_seconds, suspend_after_seconds, wake_daily_at, metadata }) makes one and waits for its first start: ready, or creating (db.refresh() until it is ready). version: 16, 17 or 18 (the default); size: { vcpus, memory_bytes }, upper bounds (1 vCPU and 1 GiB); storage: { size_bytes, durability }, its Drive, strict (the default: a commit returns once the object store has it) or standard; suspend_after_seconds: how long it stays paused, a connection answered in a millisecond or two, before its memory is saved and it sleeps for real, 1 to 86400 (300); wake_daily_at: a time of day in UTC, "HH:MM", at which it is woken every day while it rests (its pg_cron jobs wake it at their own times anyway). The name of one there is answers that one, without its password. update(db, { suspend_after_seconds, wake_daily_at }) (and db.update) changes these two, every branch’s at once; null takes either back (to 300, and to none). On a Free plan a database’s rest is fixed, as Neon’s Free scales to zero: paused a second after its last query (sleep_after_seconds 1) and asleep five minutes later (suspend_after_seconds 300); another value is refused 400 invalid_field, on a create and on a change.
• glac.databases.createBranch(db, name, { parent, expires_at }) (and db.createBranch(name, { parent, expires_at })) makes a branch of its own: its parent (main unless parent names another) as it is now, nothing copied, with a PostgreSQL, an endpoint and a Drive of its own, at <database>-<name> on the project’s network, deleted by itself at expires_at where one is given. Its roles and passwords are its parent’s: the branch’s connectionString() has the owner’s password where the Database it was made from has it. deleteBranch(db, branch) (db.deleteBranch(branch), branch.delete()) stops its PostgreSQL and deletes its Drive; not main (409 root_branch), nor a branch others were made of (409 has_branches).
• glac.databases.create(name, { history_seconds }), update(db, { history_seconds }), restore(db, { at, exact }) and createBranch(db, name, { from: { at, exact } }) (and db.update, db.restore, db.historySeconds, db.history): its history (slices DB8 and DB5): how far back its root branch can be restored, or branched from, by a time: a day unless given; 0 (none) to 30 days on Paid, a day on Free. A restore takes the root branch back in place: to a whole minute or a version’s own moment, the newest version of its Drive’s window at or before it (one every 30 seconds in which it was written, a day of it at the most); further back, to the second, or with exact: true, the moment itself, to the millisecond, by its WAL archive (its WAL replayed to it: seconds to minutes, the call waits). Its endpoint, its connection strings and its owner’s password stay what they were, its connections drop, and its state before is kept as a branch of its own, main_old_<the restore's moment>; one whose new version does not serve within five minutes is undone (503 database_restore_failed). A branch of a time is made of that moment instead. A time its history does not have is 400 invalid_history, its message saying from when the window and the archive reach. A time to the second (or exact) is the archive’s or refused, never the window’s version before it: 400 invalid_history where the archive does not reach it (a database that keeps none, or a time before its oldest base), 503 database_archive_unavailable (retryable) while the archive’s store refuses its segments; each refusal names the window’s version at or before the time, whose own moment can be asked for instead. One whose blocks the store does not give is refused 503 drive_unreadable (retryable), nothing made. An outage of the object store long enough that more of its WAL waited than its Drive keeps for the log gives that WAL up, so that the database stays up: a gap of its archive, in db.history.gaps (DatabaseHistoryGap: from, to, from_lsn, to_lsn): when the WAL given up began, until when the archive restores no time (the end of the first base taken after it; null until there is one), and where in the log it begins and ends. A time in a gap is restored only from its Drive’s window (a whole minute, or a version’s own moment); to the second, or exact, it is 400 invalid_history. The gap is said as events too: database.history_gap when it is first found (once a gap, while the database is awake), and database.history_resumed when the archive restores again after it; their data is an EventDatabaseGap: the database, the gap’s from, to (null of the first), from_lsn and to_lsn, segments (how many segments of 16 MB were given up) and, of the first, error (what the object store’s last refusal said).
• create(name, { tiering: { enabled: true } }) and update(db, { tiering: { enabled } }) turn its tiered storage on or off (slice DB18: on Paid; each branch’s PostgreSQL restarts once for it), and a database’s info.tiering says whether it is on and what it bills by now (tiered_bytes).
• get(idOrName), list({ name }), delete(db, { finalSnapshot }) (a snapshot of its Drive is kept seven days, db.finalSnapshot, unless finalSnapshot: false), branches(db) (main first, then its own, the oldest first), branch(db, "main"), sleep(db, "main"), wake(db, "main") (its memory saved, its sessions there when it wakes; a connection wakes it too), resetPassword(db, { role }) (a new password in this answer alone; the old one is refused from the next login on). A Database has the same of its own.
• glac.databases.roles(db) (and db.roles()) lists the roles of its root branch that log in, read from PostgreSQL itself ({ name, owner }): its owner and the roles you made (CREATE ROLE … LOGIN), the platform’s not among them. resetRolePassword(db, role) (and db.resetRolePassword(role)) gives any of them a new password, in this answer alone: a DatabaseRoleSecret with the role’s password and the root branch’s connection strings of that role (connectionString()); the owner’s is made of the database the API answers. A branch of its own keeps the password it was made with.
• db.connectionString({ password, pooled, private }) is a string node-postgres (connectionString), psql and libpq take as it is: the public one where the API gives one, else the one on the project’s network, with the owner’s password of the answer it came with, or password (percent-encoded). A public one’s sslmode=require is said as node-postgres takes it today, sslmode=verify-full.
• db.defaultBranch has the connection strings as the API gives them (connectionUri, pooledUri, privateUri), its endpoint and its state (awake, paused, asleep).

A database is reached on the project’s network, from its sandboxes (made with project_network) and its services, at its name: that is its private_uri. Where an edge serves PostgreSQL it is reached from anywhere at its public address too (connection_uri, port 5432, TLS alone; the pooler’s: pooled_uri); they are null where none does, or where the database has no region to be named under, and the connection string takes them where they are given. A database’s JSON leaves the password out. Databases are a control plane’s.

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). An install’s answer has every output, the secret ones too (an admin token, an endpoint with it in), and a read shows those to a key with the admin scope alone: an installation object keeps each output an earlier answer gave that a later one hides.

const rivet = await glac.catalogue.get("rivet");           // its parameters, and a month of it in Cube's meters
console.log(rivet.calculator?.month);
const engine = await glac.installations.create("rivet", { parameters: { disk_gib: 20 } });   // waits until it is ready
console.log(engine.outputs.endpoint);                      // RIVET_ENDPOINT, its token in it

Managed Applications are a control plane’s.

Secrets and variables

glac.secrets.put(name, value, { allowedHosts }) keeps a value that no answer gives back, and that goes only to the hosts it was given; an app is given one as an environment variable (secrets: { DATABASE_URL: "db_url" }). glac.variables.put(name, value) is a shared variable that an app’s env refers to as ${{ shared.NAME }}.

The project, the account and the bill

glac.project() and glac.events(); glac.account() and glac.usage(), and updateAccount(), which sets where the account’s notices go ({ email }) and the language they are written in among the rest ({ language: "de" }: “en”, “de” or “fr”, or null to follow the billing address again); an account’s email_verified says whether its address is verified, and email_undeliverable (an EmailUndeliverable: why, since, detail) that mail to it bounced, which hold its notices back (where notices go); its keeps (an AccountKeeps, behind a control plane) is what the key’s project keeps of Drives and volumes, by the numbers a create is held to, each with what it has (volumes, volume_bytes, volumes_bytes, whose limit is null for no limit, and unsized_bytes: see raising limits); glac.billing(), glac.balance(), glac.topUp(usd), glac.charges() and glac.ledger(), and updateBilling() and updateBalance() to change the plan and auto reload. The bill and the project are the control plane’s.

The data of an event. Every type of event the control plane has has an interface of its data (event.data), named after the description’s schema of it (event.data as EventDatabase). A database’s: EventDatabase (database.created, with its region and PostgreSQL version; database.deleted, with final_snapshot_id, the snapshot of its Drive kept seven days), EventDatabaseBranch (database.branch_created, with its parent; database.branch_deleted, with its reason), EventDatabaseRestored (database.restored: the moment at, and old_branch_id, the branch the state before is kept as), EventDatabaseArchive (database.archive_failing: since, how many segments in a row failures, archived_until, how far a restore reaches meanwhile, and the object store’s error; database.archive_recovered: recovered_at) and EventDatabaseGap. The others likewise: a sandbox’s (EventSandboxSlept, EventSandboxWoke, EventSandboxMoved, EventSandboxDeleted, …), an app’s and its keys’ (EventApp, EventAppFailed, EventKeyCreated, …), the project’s deploys and key, backups, domains, destinations and Drives’ snapshots (EventProjectDeployed, EventBackup, EventDomain, EventDestination, EventDriveSnapshot, …), and the account’s plan, top-ups, refunds, withdrawals, balance, Credits, storage, egress cap, spend limits, hold and debts (EventSubscriptionPeriod, EventTopupCollected, EventWithdrawalReceived, EventBalance, EventInDebt, …). A field that not every event of a type has is optional.

Webhooks, API keys, spend limits, the project. glac.webhooks.create(url, { events, enabled }) sends the project’s events to an address of yours (the secret that signs each delivery is in that answer alone); get, list, update, delete. glac.keys.create({ name, scopes, expiresAt }) makes an API key (the key itself, key, is in that answer alone); get, list, delete. glac.limits() and glac.updateLimits(usd) are the project’s spend limit and what was spent this month (null takes the limit away), and sbx.limits() and sbx.updateLimits(usd) a sandbox’s own. glac.requestLimit(limit, wanted, why) asks for one of the account’s limits raised on request (a cap by its name, "volumes" or "volume_bytes"; bytes of the two in bytes; 409 limit_request_pending while one of the same limit waits), and glac.limitRequests({ limit, cursor }) and glac.limitRequest(id) read them with the operator’s answers (LimitRequest: status pending, granted or refused, granted, answer). The data of instance.restarted, instance.upgraded, instance.reverted, instance.upgrade_failed and limit_request.granted and .refused events are EventInstanceRestarted, EventInstanceUpgraded, EventInstanceReverted, EventInstanceUpgradeFailed and EventLimitRequest. glac.updateProject({ deleteAfterIdleDays: 30 }) sets after how many days asleep its sandboxes are deleted (null: never). A control plane’s. Webhooks and API keys need a key with the admin scope, and so do setting the project’s limit and updateProject; setting a sandbox’s limit needs write.

Log destinations, the audit log, the billing documents. glac.destinations is where the logs (and the metrics and the requests’ traces: signals: ["logs", "traces"]) of the project’s apps are exported (OpenTelemetry endpoints): create(name, { endpoint, headers, ... }), which tries it at once with one record (status.connected), get, list, update, delete, test (one record now); a header’s value is a credential, sent when a destination is made or changed and in no answer (what is returned has the headers’ names alone). glac.audit({ limit, cursor }) is a page of the project’s audit log, the newest first (who, what method, what path, what status): every call that was no reading, a refused one too, and every reading of an app’s log by an operator. glac.statement("2026-09") is a month’s statement (this month’s unless given; a Date in the month too) with each database’s own line in it (databases: what it used in the month, its history and its tiered data apart, and what that comes to at the list prices), glac.invoices() the invoices at Stripe (with the PDF’s link), glac.notices() the mail the account was sent, glac.withdrawals() what it may withdraw from now and the withdrawals it made (a consumer in the EEA or the UK may withdraw from a purchase within 14 days), and glac.withdraw(chargeId, { name, email }) the buyer’s own statement of withdrawal, received at once. A control plane’s. Making, changing, testing and deleting a destination, reading the audit log and withdrawing need a key with the admin scope; the rest, one that may read.

Buying at once (startNow). 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. topUp(20, { startNow: true }), updateBilling({ plan: "paid", startNow: true }) (Paid, bought from Free) and updateBalance({ autoReload: true, startNow: true }) (for every auto reload while auto reload stays on) carry 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: the SDK never sends it unless it is given. Without it, such an account is refused: a GlacError of 400 start_now_required, param start_now, in words that name its country and quote the request, and nothing is bought. An account whose auto reload is on without the request reloads nothing, and is told once a month (the event auto_reload.no_request, whose data is EventAutoReloadNoRequest).

Errors

A non-zero exit code is a result: read res.exitCode. An error of the API throws GlacError, with status, type, code, param, retryable, requestId and message. DeployError (a version that did not come up, or a project’s deploy that failed) and LogsError (a log that could no longer be read) are GlacErrors too.

Behaviour worth knowing

• Sleeping sandboxes. No call fails because a sandbox sleeps: it is woken and the call goes on. There is no wake call.
• Retries. No answer, or a retryable error, is retried twice (retries), from 0.2 s doubling. Every POST carries an Idempotency-Key. Calls with a byte body are not retried.
• What it does not have yet that the Python SDK has: a time limit on cmd.wait() and a client timeout, raw output bytes, and exact decimal usage sums. It has been run on Node only.