TypeScript SDK

安装

没有任何依赖：它使用 fetch、WebSocket 和 node:crypto，Node 23.6 或更高版本可以直接运行它的 TypeScript 源码。npm 上的包名是 glac，并为不能运行 TypeScript 的运行时提供 JavaScript 和类型声明：

npm install glac

开头几行

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

客户端

new Glac({ apiKey, baseUrl, retries }) 是某个地址上的一个密钥；没有给出的从 GLAC_API_KEY 和 GLAC_API_URL 读取。它为每个产品提供一个命名空间：

平台本身的调用是客户端的方法：glac.account()、updateAccount()、usage()、billing()、updateBilling()、balance()、updateBalance()、topUp(usd)、charges()、ledger()、project() 和 events()。SDK 没有封装的 API：glac.json("GET", "/v1/webhooks")，列表用 glac.pages(path)。调用返回的对象（Sandbox、App、Drive、Volume）会保留它的客户端，它自己的方法使用这个客户端。

简写：Sandbox.run、Sandbox.create、Sandbox.get、Sandbox.getOrCreate 和 Sandbox.list 就是默认客户端上 glac.sandboxes 的调用，默认客户端在第一次使用时根据 GLAC_API_KEY 和 GLAC_API_URL 创建；{ client } 可以指定另一个客户端。其他产品都没有简写。

值为 undefined 的选项不会发送。有些选项中的 null 有特定含义：sleepAfterSeconds: null 表示永不休眠，更新中的 sleepNoticeMs: null 表示休眠前不再通知它的程序，env: { KEY: null } 删除一个键，egress: null 去掉所有网络规则。

方块

方块（API 称之为 app）是作为服务运行在自己地址上的镜像，实例数量随请求的需要而定，没有请求时一个都没有。SDK 中的 App 就是一个方块。

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);

沙箱

实时输出、文件、快照和分叉：

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();

云盘

云盘是项目的一块磁盘，不随它的沙箱消失：同一时间由一个沙箱以读写方式挂载，可以在沙箱创建时挂载，也可以在沙箱运行时挂载；沙箱没了，云盘连同其中的内容一起保留，供下一个沙箱挂载：可以在它的区域，也可以在别的区域，只要那里的机器能读取它归属区域的对象存储（见下文）。云盘在写入的同时被复制到所在区域的对象存储中，所以其他节点上的沙箱也能挂载它：会先把它搬过去。只按写入的数据计费 (usedBytes)。云盘属于控制平面 (/v1/drives)：对着一个独立运行的节点，每个调用都会抛出该节点的 404 no_such_route，节点上的磁盘是存储卷（见下文）。

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

Drive 包含 id（vol-…：云盘就是存储卷）、name、sizeBytes、usedBytes、attachedTo（沙箱、路径、模式）、region、home、status、lease（唯一写入方所在的节点、纪元和到期时间）、appId 和 key（键控实例的云盘）、parentDriveId 和 rootDriveId（分叉的云盘才有：来源云盘和这一脉的第一个云盘，来源云盘之后可能已被删除；不是分叉的云盘为 null）、managedBy（一个 ManagedBy，数据库的云盘才有；不属于任何东西时为 null），并自带 attach、detach、update({ name })、refresh() 和 delete()。

• 一个云盘同一时间只属于一个沙箱：另一个沙箱持有的云盘会被拒绝 (409 drive_attached)，删除已挂载的云盘也一样。键控实例的云盘随它的键一起删除 (409 key_drive)。
• 数据库的云盘 (drive.managedBy) 只能由数据库的实例以读写方式挂载，重命名、恢复和删除都要通过数据库进行：在这里调用这些操作，或以读写方式挂载它，都会被拒绝 (409 managed_by_database)。项目可以为它创建快照和分叉，任何人都可以以只读方式挂载它的快照。
• 另一个节点持有的云盘，会先被搬到沙箱所在的节点；对象存储中还没有它的最新状态时 (503 copy_behind)，或无法把它搬过去时 (503 drive_not_brought)，调用为 retryable：客户端会按 retries 的设置重试，之后抛出异常，你稍后再请求一次即可。
• 跨区域 (slice D9)。云盘的归属区域 (home) 是保存其副本的对象存储所在的区域：也就是创建它的区域。另一个区域的沙箱也能挂载它，前提是那个区域的机器能读取其归属区域的存储（不能时返回 409 not_on_one_machine）：云盘被释放为一个版本，在那里被接管，客户机读取时从归属区域的存储读出，客户机写入的数据则进入它现在所在区域的存储 (region)。云盘在那里待满一小时后，归属区域会跟过去，用 glac.drives.moveHome(drive) (drive.moveHome()) 则立即迁移：它的机器把归属区域存储中剩下的内容复制到自己区域的存储中，那里什么都不剩时，home 就变成新区域；drive.homeMove 说明迁移进行到哪一步（asked_at、asked_by、copied_objects、copied_bytes、objects_left、error）。保留的版本都不再需要旧归属区域的副本后（一天后），这份副本会被删除。云盘的归属区域最多每六小时迁移一次 (409 home_moved_recently)；归属区域就是当前所在区域的云盘返回 409 home_here。
• 套餐的限制：免费版最多 3 个云盘，单个最大 10 GiB，合计 15 GiB；付费版最多 500 个，单个最大 1 TiB (403 drive_limit_reached)。
• glac.usage({ drive })、kind: "drive" 和 groupBy: "drive" 报告云盘保存了多少、写入了多少、冷读了多少，glac.usage({ snapshot: "dsnap-…" }) 报告一个快照单独保留了多少。drive.created、drive.deleted、drive.attached 和 drive.detached 事件携带 EventDrive 或 EventDriveAttached，drive.snapshot.created 和 drive.snapshot.deleted 携带 EventDriveSnapshot。

快照、分叉与恢复。云盘的快照是它在对象存储中的一个版本：不复制任何数据。运行中的沙箱正在写入的云盘，会在写入被暂停片刻时创建快照：带 fsConsistent: true 时，由沙箱的代理程序冻结它的文件系统（consistency 为 "frozen"；代理程序做不到时返回 409 not_frozen：这时请不带它创建），否则暂停它的机器（"paused"，云盘处于相当于断电时的状态，文件系统的日志就是为此准备的）；没有运行中的沙箱持有的云盘按原样创建快照 ("at_rest")。暂停最多十秒，之后调用会被拒绝，返回 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

• 快照不随云盘消失：云盘删除后，仍可以按云盘的 id 列出、读取、分叉它的快照，或以只读方式挂载。快照按它单独保留的数据 (exclusiveBytes) 计费，按小时计，价格与云盘的数据相同（每 GB·月 $0.02），在云盘也删除之后一直计费，直到快照本身被删除。
• 分叉和任何云盘一样，按它的 usedBytes，即完整的逻辑内容计费：从 10 GB 快照分叉出的云盘按 10 GB 的云盘计费。
• 恢复会在云盘最新的版本之后写入一个新版本，内容与快照相同；中间的版本只要有快照或分叉保留着就仍然存在，所以先恢复到较旧的快照、再恢复到较新的快照也可以。云盘现在的内容如果没有快照保留就会消失：请先创建一个快照。沙箱以读写方式持有的云盘不能恢复 (409 drive_attached)：先卸载它。
• 只读挂载：在云盘所在区域的任意机器上，任意多个沙箱都可以挂载，无论云盘被谁持有，云盘删除后也可以。数据块在客户机读取时从对象存储取来，不收费；它们在用量中计在挂载它的沙箱名下（glac.usage({ sandbox })，drive_cold_read_bytes）；读取它的机器上已有的数据也不收费。客户机不能写入它，挂载了快照的沙箱也不能迁到别的机器上。沙箱会把它列在 volumes 中，带有 view_of。
• glac.drives.create 的 durability 为 standard 或 strict，后者要等对象存储收到 fsync 之前的每一次写入，客户机的 fsync 才返回；云盘的 durability 会说明它，一经设定不再改变（写入有多持久）。
• 不向对象存储复制任何数据的节点没有快照、分叉和恢复 (409 not_copied)。应用的版本只能以读写方式挂载云盘：快照的只读挂载只供沙箱使用。

glac.volumes 对应 API 的 /v1/volumes，即云盘底层的磁盘，为过渡期而保留：只有它才有的，是独立运行的节点（节点上的磁盘就是存储卷），以及共享存储卷，即可由多个沙箱同时挂载的文件系统。沙箱或应用以 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 }] });

存储卷的备份。备份是存储卷（云盘也是存储卷）在某一时刻的副本，保存在对象存储中，直到过期：可以由调用创建，可以按存储卷的规则每天创建，也会在服务的新版本替换其实例之前创建。与云盘的快照不同，它是一份独立的副本，仅凭它就能创建存储卷，而且不随存储卷消失；存储卷的备份只保存自上一个备份以来变化的内容，多个备份都需要的数据块只计费一次，计在最早的备份上。在存储收到全部数据之前为 making，之后为 ready，从那时起按存储中保存的数据量 (storedBytes)、以休眠沙箱所保存内容的价格计费（备份）。备份属于控制平面。

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 })（或 vol.backup()）立即创建一个备份，保留 expiresInDays 天（1 到 365），或按存储卷的规则（未设置时为 30 天）；glac.volumes.backups(volume) 列出一个存储卷的备份，最新的在前（已删除的存储卷按 id 指定）。不向对象存储复制任何数据的节点没有备份 (409 not_copied)。
• glac.backups.list({ volume }) 列出项目的备份，最新的在前，包括已删除存储卷的备份；get(backup)、delete(backup)（之后不再为它计费；从它创建的存储卷仍然保留），以及 restore(backup, { name })，即从一个就绪的备份创建新存储卷，等同于 glac.volumes.create({ fromBackup, name })（创建期间返回 409 backup_not_ready，失败后返回 409 backup_unusable）。Backup 包含 id (bak-…)、volumeId、status（making、ready、failed）、reason（manual、daily、before_version）、storedBytes（计费依据）、ownBytes（删除它能省下的量）、sharedBytes、volumeName（当时存储卷的名称）、consistency（frozen、crash）、frozenMs（存储卷的写入方为复制等待了多久；没有冻结时为 null）、sizeBytes（存储卷当时的数据量）、volumeSizeBytes（它最多能容纳的量，也就是从备份创建的存储卷的容量）、shared、region、failure、createdAt、readyAt（从此开始计费）、expiresAt，以及 refresh()、restore({ name })、delete()。
• 从备份创建的存储卷，大小和类型与备份所来自的存储卷相同（与 fromBackup 一起时不给出 sizeBytes 和 shared），位于备份所在的区域。它的 status 在完整拿到备份之前为 restoring，之后为 ready，在此之前不能挂载；fromBackup 指明来源备份。如果被分配到的机器无法恢复它，控制平面会在该区域的另一台机器上再创建一次：这时 info.restore_attempt 为 2，info.first_failure 说明第一次为什么失败。如果这一次也失败，它就是 failed (info.failure)，只能删除。
• glac.usage({ backup })、kind: "backup" 和 groupBy: "backup" 报告备份保存了多少，计在状态计量项上 (state_gb_hours)；glac.billing() 的 meters.state.backups_gb_hours 说明该计量项中有多少来自备份。

域名

项目的域名是一个指向应用（和它的默认地址一样）或沙箱某个端口的名称。域名属于控制平面。

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

浏览器

尚未开放。浏览器还没有向账户开放：下面是开放之前 SDK 目前的样子。

会话是一个托管的 Chromium，由 Playwright、Puppeteer 或任何其他 Chrome DevTools Protocol (CDP) 客户端从外部驱动。有客户端连接时它保持运行，最后一个客户端离开 sleep_after_seconds 秒后进入休眠，页面会保留。CDP 客户端只需要它的 cdpUrl：凭据就在地址的主机名中，所以会话的 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 }) 创建一个处于运行状态的会话（kind：默认为 chromium-headless；chromium 有屏幕；lightpanda 是没有布局引擎的浏览器）；如果用已有会话的名称创建，会返回那个会话：它会被唤醒，页面都还在。profile: { name, save, version } 在返回会话之前加载一个配置文件（见下文）。还有 get(idOrName)、list({ status, kind, name })（status：awake、asleep、unavailable 或 failed）、update(session, changes)、delete(session)、sleep(session)、rotateUrl(session)；BrowserSession 自己也有同样的方法。沙箱在运行前就失败的会话不算会话：创建会被拒绝，返回 503 session_failed。

• session.status 为 awake、asleep、unavailable（它的节点无法访问）或 failed（创建得到响应之后它的沙箱失败了：比如浏览器停止且没有恢复），这时 session.error 说明原因（{ code, message }，按节点的原话；没有失败时为 null）。browser.failed 事件也会说明这一点（它的数据类型为 EventBrowserFailed）。

• session.cdpUrl 就是 chromium.connectOverCDP 和 Puppeteer 的 browserURL 接受的地址。rotateUrl() 换新地址：旧地址从此被拒绝，经由它们建立的连接会断开。

• session.connect({ chromium, timeoutMs }) 连接 Playwright：装有 playwright 或 playwright-core 时使用它们（这个包不依赖二者中的任何一个），否则使用给出的 chromium。close() 关闭那个浏览器；会话仍然保留，没有客户端连接时进入休眠。

• session.liveUrl 是在浏览器中实时观看其页面的地址（无头会话是随变化实时画出的标签页，有头会话是它的屏幕），观看者的鼠标和键盘操作会传到页面上；await session.live({ interactive: false }) 给出一个单独的地址，任何操作都传不到页面，用来给人看。观看者会让会话保持运行。两个地址都会被 rotateUrl 更换，读取它们需要密钥有 url 权限范围。

• 配置文件（它的 Cookie、Local Storage、IndexedDB、Session Storage 和偏好设置，由平台为项目保存）：create({ profile: { name: "acme-login", save: true } }) 加载一个配置文件，并在会话删除时再次保存（delete({ saveProfile: false }) 则不保存）；session.saveProfile(name?) 立即保存（浏览器会重启，已连接的客户端需要重新连接；这期间对同一配置文件的另一次保存会以 409 profile_busy 被拒绝）；session.profile 是它持有的配置文件；还有 glac.browsers.profiles.list()、get(name)、delete(name)。

• 你自己的代理，付费版可用（免费版上返回 403 proxy_not_on_plan）：create({ proxy: "http://user:password@proxy.example.com:3128" })（或 { url }）让会话到 80 和 443 端口的连接经由浏览器旁边的一个中继，从这个接受 CONNECT 的 HTTP 代理出站，浏览器本身对代理一无所知；QUIC 在那里会被拒绝，所以浏览器改用基于 TCP 的 HTTP。session.update({ proxy }) 可以在运行中的会话上更换代理，无需重启浏览器（经由原代理的连接会断开），{ proxy: null } 则去掉代理。凭据由平台保管，不会出现在任何响应中：session.proxy 为 { url, username }，session.proxyBytes 是经由代理双向传输的总量（proxySentBytes 和 proxyReceivedBytes 分别是每个方向的量）。如果代理不接受隧道，页面会通过 HTTP 得到 502 proxy_failed。参见自己的代理。

会话和任何实例一样，按它使用的方块资源计费：计算时的 CPU、运行时的内存和出站流量（价格与套餐）。session.awakeSeconds 是它已运行的时长。经过它的代理的流量和其他流量一样算作它的流量。会话属于控制平面。

数据库

数据库是托管的 Postgres：运行在云盘上的独立 PostgreSQL，没有任何请求时休眠，有连接时被唤醒，会话都会保留。它大约两秒就能创建好，带有根分支 main 和所有者 glacdb_owner（glac_superuser 的成员，不是超级用户）。所有者的密码只出现在 create 和 resetPassword 的响应中，任何地方都不保存：只有它们返回的数据库的 connectionString() 才带有密码。

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 }) 创建一个数据库并等待它第一次启动：ready，或 creating（反复 db.refresh()，直到就绪）。version：16、17 或 18（默认）；size: { vcpus, memory_bytes }，即上限（默认 1 vCPU 和 1 GiB）；storage: { size_bytes, durability }，它的云盘，strict（默认：对象存储收到提交后提交才返回）或 standard；suspend_after_seconds：保存内存、真正休眠之前保持暂停多久，暂停期间连接在一两毫秒内就能得到响应，1 到 86400（默认 300）；wake_daily_at：休眠期间每天在 UTC 的哪个时刻 ("HH:MM") 唤醒它（它的 pg_cron 任务无论如何都会在各自的时间唤醒它）。用已有数据库的名称创建时，返回那个数据库，不带密码。update(db, { suspend_after_seconds, wake_daily_at })（以及 db.update）修改这两项，所有分支一起修改；null 把其中任意一项恢复默认（分别为 300 和不唤醒）。免费版数据库的休眠设置是固定的，与 Neon 免费版缩容到零的做法相同：最后一个查询一秒后暂停（sleep_after_seconds 为 1），五分钟后休眠（suspend_after_seconds 为 300）；无论创建还是修改，其他值都会以 400 invalid_field 被拒绝。
• glac.databases.createBranch(db, name, { parent, expires_at })（以及 db.createBranch(name, { parent, expires_at })）创建一个独立分支：它的父分支（默认 main，可用 parent 指定其他分支）此刻的状态，不复制任何数据，有自己的 PostgreSQL、端点和云盘，在项目网络上的地址是 <database>-<name>；给出 expires_at 时，到时会自行删除。它的角色和密码与父分支相同：创建它的 Database 带有所有者的密码时，分支的 connectionString() 也带有。deleteBranch(db, branch)（db.deleteBranch(branch)、branch.delete()）停止它的 PostgreSQL 并删除它的云盘；不能删除 main (409 root_branch)，也不能删除有其他分支从它创建的分支 (409 has_branches)。
• glac.databases.create(name, { history_seconds })、update(db, { history_seconds })、restore(db, { at, exact }) 和 createBranch(db, name, { from: { at, exact } })（以及 db.update、db.restore、db.historySeconds、db.history）：数据库的历史（slice DB8 和 DB5）：根分支按时间最多能恢复到多久以前，或从多久以前创建分支：默认一天；付费版可设为 0（不保留）到 30 天，免费版为一天。恢复会把根分支原地带回过去：恢复到整分钟或某个版本自身的时刻时，使用云盘版本窗口中该时刻或之前最新的版本（每个有写入的 30 秒一个版本，最多保留一天）；更早的时刻、精确到秒的时刻，或带 exact: true 时的那个精确时刻（精确到毫秒），则通过 WAL 归档恢复（把 WAL 重放到那一刻：需要几秒到几分钟，调用会一直等待）。端点、连接字符串和所有者的密码都保持不变，现有连接会断开，恢复之前的状态会作为一个独立分支 main_old_<the restore's moment> 保留；如果新版本在五分钟内不能提供服务，恢复会被撤销 (503 database_restore_failed)。按时间创建分支时，则以那个时刻创建分支。历史中没有的时间返回 400 invalid_history，错误信息会说明版本窗口和归档分别能追溯到什么时候。精确到秒的时间（或带 exact）只能从归档恢复，否则拒绝，从不退而使用窗口中之前的版本：归档追溯不到时返回 400 invalid_history（数据库不保留归档，或时间早于最早的基础备份），归档的存储拒绝提供分段时返回 503 database_archive_unavailable（可重试）；每次拒绝都会指明窗口中该时间或之前的版本，你可以改为请求那个版本自身的时刻。存储给不出所需数据块时，返回 503 drive_unreadable（可重试），不会创建任何东西。如果对象存储中断太久，等待归档的 WAL 超过了云盘为日志预留的空间，这部分 WAL 会被放弃，以保证数据库继续运行：这就是归档中的一个缺口，记录在 db.history.gaps 中（DatabaseHistoryGap：from、to、from_lsn、to_lsn）：被放弃的 WAL 从何时开始，归档到何时为止无法恢复任何时间（缺口之后第一个基础备份完成的时间；在有基础备份之前为 null），以及缺口在日志中的起止位置。缺口内的时间只能从云盘的版本窗口恢复（整分钟，或某个版本自身的时刻）；精确到秒或精确时刻的恢复返回 400 invalid_history。缺口也会以事件的形式报告：首次发现缺口时发出 database.history_gap（数据库运行期间，每个缺口一次），缺口之后归档重新可用于恢复时发出 database.history_resumed；它们的 data 是一个 EventDatabaseGap：数据库，缺口的 from、to（前者为 null）、from_lsn 和 to_lsn，segments（放弃了多少个 16 MB 的分段），以及前者才有的 error（对象存储最后一次拒绝时返回的内容）。
• create(name, { tiering: { enabled: true } }) 和 update(db, { tiering: { enabled } }) 用来开启或关闭分层存储（slice DB18：付费版可用；每个分支的 PostgreSQL 会为此重启一次），数据库的 info.tiering 说明是否已开启，以及目前按多少计费 (tiered_bytes)。
• get(idOrName)、list({ name })、delete(db, { finalSnapshot })（除非 finalSnapshot: false，否则它的云盘会保留一个快照七天，即 db.finalSnapshot）、branches(db)（先是 main，然后是独立分支，最早的在前）、branch(db, "main")、sleep(db, "main")、wake(db, "main")（它的内存会被保存，醒来时会话都还在；连接也会唤醒它）、resetPassword(db, { role })（新密码只出现在这次响应中；从下一次登录起旧密码会被拒绝）。Database 自己也有同样的方法。
• glac.databases.roles(db)（以及 db.roles()）列出根分支中可登录的角色，直接从 PostgreSQL 读取 ({ name, owner })：它的所有者和你创建的角色 (CREATE ROLE … LOGIN)，平台自己的角色不在其中。resetRolePassword(db, role)（以及 db.resetRolePassword(role)）给其中任何一个角色设置新密码，只出现在这次响应中：一个 DatabaseRoleSecret，带有该角色的 password 和根分支上该角色的连接字符串 (connectionString())；所有者的连接字符串由 API 响应的数据库生成。独立分支保留它创建时的密码。
• db.connectionString({ password, pooled, private }) 是 node-postgres (connectionString)、psql 和 libpq 都能直接使用的字符串：API 给出公网连接字符串时用公网的，否则用项目网络上的，并带有所有者的密码（来自与之一起返回的响应），或者 password（百分号编码）。公网连接字符串中的 sslmode=require，按 node-postgres 目前的理解写作 sslmode=verify-full。
• db.defaultBranch 包含 API 给出的连接字符串（connectionUri、pooledUri、privateUri）、它的 endpoint 和 state（awake、paused、asleep）。

数据库在项目网络上按名称访问，来自它的沙箱（用 project_network 创建）和服务：这就是它的 private_uri。有边缘节点提供 PostgreSQL 服务时，也可以从任何地方通过它的公网地址访问（connection_uri，端口 5432，只支持 TLS；连接池的地址：pooled_uri）；没有边缘节点提供、或数据库没有可用来命名的区域时，它们为 null；给出时，连接字符串会使用它们。数据库的 JSON 中不包含密码。数据库属于控制平面。

托管应用

目录中的应用（比如 Rivet）以它自己的方块资源安装到项目中：它的应用、存储卷、机密和存储桶，都带有该安装的标签，只能通过这个安装修改，并按这些资源本身计费（托管应用）。安装的响应包含全部输出，包括机密输出（管理员令牌、带有令牌的端点），之后的读取只对有 admin 权限范围的密钥显示这些输出：安装对象会保留之前的响应给出、而之后的响应隐藏的每个输出。

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

托管应用属于控制平面。

机密与变量

glac.secrets.put(name, value, { allowedHosts }) 保存一个任何响应都不会返回的值，它只会发往给定的主机；应用以环境变量的形式得到它 (secrets: { DATABASE_URL: "db_url" })。glac.variables.put(name, value) 是一个共享变量，应用的 env 以 ${{ shared.NAME }} 引用它。

项目、账户与账单

glac.project() 和 glac.events()；glac.account() 和 glac.usage()，以及 updateAccount()，它可以设置账户的通知发往哪里 ({ email })，以及通知使用的语言等（{ language: "de" }：“en”、“de” 或 “fr”，或 null 表示重新跟随账单地址）；账户的 email_verified 说明它的地址是否已验证，email_undeliverable（一个 EmailUndeliverable：why、since、detail）说明发往它的邮件被退回了，这会让通知暂缓发送（通知发往哪里）；它的 keeps（一个 AccountKeeps，在控制平面后面）是密钥所属项目在云盘和存储卷上的保有量，按创建时所受限制的数字给出，每项都附带已有的量（volumes、volume_bytes、volumes_bytes，其 limit 为 null 表示不限，以及 unsized_bytes：参见提高限制）；glac.billing()、glac.balance()、glac.topUp(usd)、glac.charges() 和 glac.ledger()，以及用来修改套餐和自动充值的 updateBilling() 和 updateBalance()。账单和项目属于控制平面。

事件的数据。控制平面的每种事件，都有一个对应其数据 (event.data) 的接口，以描述中该事件的 schema 命名 (event.data as EventDatabase)。数据库的事件：EventDatabase（database.created，附带它的 region 和 PostgreSQL version；database.deleted，附带 final_snapshot_id，即保留七天的云盘快照）、EventDatabaseBranch（database.branch_created，附带它的 parent；database.branch_deleted，附带它的 reason）、EventDatabaseRestored（database.restored：时刻 at，以及 old_branch_id，即保存恢复之前状态的分支）、EventDatabaseArchive（database.archive_failing：since、连续失败的分段数 failures、archived_until，即在此期间恢复能追溯多远，以及对象存储的 error；database.archive_recovered：recovered_at）和 EventDatabaseGap。其他事件也一样：沙箱的（EventSandboxSlept、EventSandboxWoke、EventSandboxMoved、EventSandboxDeleted 等）、应用及其键的（EventApp、EventAppFailed、EventKeyCreated 等）、项目的部署和密钥、备份、域名、导出目标和云盘快照的（EventProjectDeployed、EventBackup、EventDomain、EventDestination、EventDriveSnapshot 等），以及账户的套餐、充值、退款、撤回、余额、点数、存储、出站流量上限、支出上限、冻结和欠款的（EventSubscriptionPeriod、EventTopupCollected、EventWithdrawalReceived、EventBalance、EventInDebt 等）。某类事件并非都有的字段是可选字段。

Webhook、API 密钥、支出上限、项目。glac.webhooks.create(url, { events, enabled }) 把项目的事件发到你的地址（为每次投递签名的 secret 只出现在这次响应中）；还有 get、list、update、delete。glac.keys.create({ name, scopes, expiresAt }) 创建一个 API 密钥（密钥本身 key 只出现在这次响应中）；还有 get、list、delete。glac.limits() 和 glac.updateLimits(usd) 是项目的支出上限和本月已支出的金额（null 去掉上限），sbx.limits() 和 sbx.updateLimits(usd) 则是某个沙箱自己的。glac.requestLimit(limit, wanted, why) 申请提高账户的某项可应要求提高的限制（按名称指定的上限、"volumes" 或 "volume_bytes"；后两者中的大小以字节为单位；同一项限制已有申请在等待时返回 409 limit_request_pending），glac.limitRequests({ limit, cursor }) 和 glac.limitRequest(id) 读取申请及运营方的答复（LimitRequest：status 为 pending、granted 或 refused，granted、answer）。instance.restarted、instance.upgraded、instance.reverted、instance.upgrade_failed 以及 limit_request.granted 和 .refused 事件的数据，分别是 EventInstanceRestarted、EventInstanceUpgraded、EventInstanceReverted、EventInstanceUpgradeFailed 和 EventLimitRequest。glac.updateProject({ deleteAfterIdleDays: 30 }) 设置沙箱休眠多少天后被删除（null：永不删除）。属于控制平面。Webhook 和 API 密钥需要有 admin 权限范围的密钥，设置项目的上限和 updateProject 也一样；设置沙箱的上限需要 write。

日志导出目标、审计日志、计费文件。glac.destinations 是项目中应用的日志（以及指标和请求的追踪：signals: ["logs", "traces"]）导出的地方（OpenTelemetry 端点）：create(name, { endpoint, headers, ... }) 创建时会立即用一条记录测试 (status.connected)，还有 get、list、update、delete、test（立即发送一条记录）；请求头的值是凭据，只在创建或修改导出目标时发送，不会出现在任何响应中（返回的内容只有请求头的名称）。glac.audit({ limit, cursor }) 是项目审计日志的一页，最新的在前（谁、什么方法、什么路径、什么状态）：每一次不是读取的调用（被拒绝的也算），以及运营方对应用日志的每一次读取。glac.statement("2026-09") 是某个月的对账单（不给出时为本月；也可以给出该月中的某个 Date），其中每个数据库单独一行（databases：它这个月的用量，其中历史和分层数据单列，以及按标价折合多少），glac.invoices() 是 Stripe 上的发票（附 PDF 链接），glac.notices() 是发给账户的邮件，glac.withdrawals() 是现在可以撤回的购买和已做的撤回（欧洲经济区或英国的消费者可以在 14 天内撤回一笔购买），glac.withdraw(chargeId, { name, email }) 是买方本人的撤回声明，立即受理。属于控制平面。创建、修改、测试和删除导出目标、读取审计日志以及撤回，需要有 admin 权限范围的密钥；其他调用只需要有读取权限的密钥。

立即购买 (startNow)。欧洲经济区或英国的消费者（没有已验证或正在验证的税号的账户）可以在 14 天内撤回一笔购买，所购内容只有在其本人明确要求时才会立即提供。topUp(20, { startNow: true })、updateBilling({ plan: "paid", startNow: true })（从免费版购买付费版）和 updateBalance({ autoReload: true, startNow: true })（自动充值保持开启期间的每一次自动充值）都带有这一要求，措辞与控制台在勾选框旁显示的相同（GET /v1/billing/withdrawals 中也有，见 right.start_now）：

我要求在可以撤回这笔购买的 14 天内立即提供所购内容。如果我撤回，我需要为此前已提供的部分付费。我理解，一次充值的点数全部用完后，即视为已全部提供，我将不能再撤回。

服务立即开始；在 14 天内，买方仍可撤回，并为此前已提供的部分付费；一旦全部提供（一次充值的点数全部用完），撤回权即丧失。只有在购买者本人提出这一要求时才加上它：SDK 不会自行发送它。没有它时，这类账户的购买会被拒绝：抛出一个 GlacError，即 400 start_now_required，param 为 start_now，错误信息会指明账户所在的国家并引用这一要求的原文，什么也不会买。开启了自动充值却没有这一要求的账户不会自动充值，并且每月会收到一次通知（auto_reload.no_request 事件，它的数据是 EventAutoReloadNoRequest）。

错误

非零退出码是一个结果：读取 res.exitCode 即可。API 的错误会抛出 GlacError，带有 status、type、code、param、retryable、requestId 和 message。DeployError（没能起来的版本，或失败的项目部署）和 LogsError（无法再读取的日志）也都是 GlacError。

值得了解的行为

• 休眠的沙箱。不会有调用因为沙箱在休眠而失败：它会被唤醒，调用继续进行。没有专门的唤醒调用。
• 重试。没有响应，或出现 retryable 错误时，会重试两次 (retries)，间隔从 0.2 秒开始翻倍。每个 POST 都带有 Idempotency-Key。带字节请求体的调用不会重试。
• Python SDK 有而它还没有的：cmd.wait() 的时限和客户端超时、原始输出字节，以及精确的十进制用量合计。它目前只在 Node 上运行过。