glac 调用的是和 SDK 相同的 API。它的命令和平台一样按产品分组：glac cube …、glac sandboxes …、glac drives …，项目和账户的命令在最顶层。它为三类用户而写：终端前的人、CI 中的脚本和编程智能体。因此：
- 默认情况下，它只打印你要的那一样东西（一个 id、一张表、命令自己的输出）。每个命令都接受
--json，这时它打印 API 返回的内容，错误也一样。 glac run、glac sandboxes exec和glac sandboxes shell以沙箱中命令的退出码退出。不是命令本身导致的失败，退出码为 125。- 出错时，它把 API 的
message和code打印到 stderr。 - 它从不等待没让它读取的输入，也从不删除没让它删除的东西。
安装
glac 是一个单独的文件（macOS arm64 上 1.7 MB，Linux x86_64 上 2.3 MB），启动只需约 3 毫秒。用下面的命令安装：
curl -fsSL https://glac.ai/install.sh | sh配置
glac 先读取 GLAC_API_URL 和 GLAC_API_KEY（与 SDK 读取的两个相同），再读取 glac login 写入的文件（~/.config/glac/config.json，权限 0600；$XDG_CONFIG_HOME 和 GLAC_CONFIG 可以改变它的位置）。两者都没有时，它连接 https://api.glac.ai。
glac login --api-url https://api.glac.ai --api-key - # reads the key from standard input单个沙箱的令牌 (st_…) 也可以当作密钥使用，用于那个沙箱上的 exec、cp、shell 和 url。HTTPS 使用 glac 内置的 Mozilla 根证书；SSL_CERT_FILE 可以加入你自己的证书。它不跟随重定向，所以密钥永远不会被发到别处。
命令
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每个命令组也接受单数形式（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 就是 glac cube，glac sbx 就是 glac sandboxes：glac sbx exec web ls 等同于 glac sandboxes exec web ls。glac help 按产品列出所有命令，glac help sandboxes 列出一个命令组的命令，glac help sandboxes exec 说明一个命令接受什么。选项和列名沿用 API 的名称：在那里方块叫 app。应用、沙箱、快照、云盘、存储卷和 SSH 密钥用 id 或名称指定，应用的版本用版本号或 id 指定，云盘的快照 (dsnap-…) 和备份 (bak-…) 用 id 指定。
方块
方块把镜像作为服务运行，这个服务也叫方块，API 中称为 app。glac workers …（或 glac worker …）是 glac cube … 的另一个名字。
| 命令 | 作用 |
|---|---|
glac deploy IMAGE --name api --port 8080 |
把镜像部署为应用（应用已存在时则部署一个新版本），等它就绪后打印它的地址。--no-wait 立即返回。glac cube deploy 是同一个命令。--ulimit nofile=65535、--sysctl、--tmpfs、--dns、--dns-search、--dns-option 和 --shm-size 的写法与 Docker 相同，它们是版本的运行时设置，只要给出其中任何一个，就整体替换（glac cube update api --reset runtime 会去掉它们）。 |
glac cube ls, get, update, rm |
应用；当 update 修改了构成版本的内容时，会部署一个新版本。get 会说明应用归属于哪个数据库 (managed_by)：这样的应用由数据库修改、部署和删除，对它的 update、deploy、rollback 和 rm 都会被拒绝 (managed_by_database)。 |
glac cube versions, rollback api [version] |
版本；把流量切到另一个版本（不指定版本时，切到当前版本之前最新的就绪版本）。 |
glac cube update agent --suspend-after-ms 60000 --wake-daily-at 03:30 |
停止的实例保持暂停多久（这期间它的下一个请求在一两毫秒内就能得到响应），之后才保存内存、真正休眠；以及每天在 UTC 的哪个时刻唤醒应用中休眠的键控实例和有状态服务的实例：即应用的 scale。glac deploy 也接受这两项，--reset suspend-after-ms 和 --reset wake-daily-at 会把它们恢复为默认值，glac cube get 会显示它们。 |
glac cube update agent --checkpoint 10 |
在应用的键控实例运行期间，每隔这么多秒为它们创建检查点（1 到 600；on 表示 10）；机器丢失时，实例会从检查点带着进程继续运行。--reset checkpoint 会去掉检查点，glac deploy 也接受 --checkpoint。glac cube get 显示这项设置，glac sandboxes get 显示实例的检查点进行得如何。参见检查点。 |
glac cube upgrade api user-42 [--version N] [--when now|asleep] [--keep-days N] [--no-wait], glac cube upgrades api user-42 [UPGRADE] [--wait] |
把某个键的实例原地迁到应用的另一个版本（默认是应用的当前版本，也可以用 --version 按版本号或 id 指定）：实例保留它的 id、节点、地址、令牌和它自己的云盘；它的磁盘、机器和进程换成新版本的，切换期间它的请求暂存在边缘节点。命令会等到升级结束，打印实例现在所在的版本（--no-wait 则打印升级的 id）；升级失败时以 1 退出并给出升级的错误码，实例恢复原样。upgrades 列出一个键的所有升级（每次升级的类型、从哪个版本到哪个版本、请求被暂存了多久、在哪一步失败），或显示单次升级，以及回退它需要什么、这些内容保留到什么时候；--wait 会等到它结束。--when asleep 让升级等到实例休眠时再开始，这样它的请求一个都不会被暂存；--keep-days（0 到 365，默认 7）是回退所需内容的保留天数。如果版本的服务挂载的云盘或存储卷与实例的不同，就会被拒绝 (upgrade_not_here)。glac workers upgrade 是同一个命令。 |
glac cube upgrades revert api user-42 UPGRADE [--keep-days N] [--no-wait], glac cube upgrades cancel api user-42 UPGRADE |
回退：把实例恢复到升级所保留的状态，即升级之前的磁盘、云盘和原来的版本，等待方式与升级相同（要回到的内容已不再保留时返回 rollback_gone）。cancel 取消一个正在等待的升级（等实例休眠，或在批次中排队）；已经开始的升级会被拒绝 (upgrade_started)。对已取消的升级的等待会结束，错误码为 cancelled。 |
glac cube upgrades batch api [--version N] [--from-version N]… [--key K]… [--when now|asleep] [--keep-days N] [--concurrency N] [--max-failures N] [--wait], glac cube upgrades batches api [BATCH] [--wait], glac cube upgrades stop api BATCH |
把应用的多个键批量升级到同一个版本：每个键在其实例休眠时升级（或轮到它时立即升级，--when now），默认同时 4 个，可用 --concurrency 修改（同一节点上 2 个），默认失败 5 次后停止，可用 --max-failures 修改。batch 打印批次的 id（--wait 会等到它结束并显示它，除非批次完成且没有失败，否则以 1 退出）；batches 列出所有批次，或显示一个批次及其成员；stop 取消批次中仍在等待的成员。如果应用的名称和这些词之一相同，在 glac cube upgrades 中要用 id 指定它。 |
glac cube instances ports open api user-42 5432 --from 2001:db8::/32 |
某个键的实例在它自己的公网 IPv6 地址上开放的端口，无论实例在哪里，都按应用和键指定：ls 列出；open 向给定的来源（IPv6 前缀或地址，::/0 表示所有人；5432/udp 表示 UDP）开放一个端口，并打印访问它的地址；close 关闭一个。实例在休眠和迁移后仍保留这些端口；这个键的新实例则没有。没有自己地址的实例会被拒绝 (no_ipv6)。参见键控实例。 |
glac cube logs api -f |
应用的日志，可用 --since、--until、--instance、--version、--kinds、--status、--method、--path、--request-id、--event、--stream、--contains 筛选。 |
glac cube log-usage, log-delete |
日志每天的统计；删除某个时间之前的日志行。 |
glac cube metrics api |
为应用提供服务的机器对它的统计，每分钟一行（--by-hour：每小时一行；--from、--to）：请求数、被拒绝的请求数和按状态码类别统计的请求数、p50 和 p99、运行中和已停止的实例数、唤醒次数、新建的实例数、CPU 和内存。分钟数据保留 24 小时，小时数据保留 30 天。 |
glac cube key-secrets create api, ls, get api ID, rm; glac cube keys sign |
用来签名应用的键的机密：create 打印一个，这是它唯一一次显示；ls 和 get 只显示开头几个字符和每个机密的创建时间，从不显示值。参见签名键。 |
glac compose up, config, down, ps, logs, restart |
把 Compose 文件导入项目，每个服务一个应用，连同它的云盘和网络，并等待由此产生的部署；--remove-orphans 删除文件中已经没有的服务对应的应用，--strict 拒绝会被忽略的内容，-f - 从标准输入读取文件。ps 列出服务及各自的状态，logs 把它们的日志一起打印出来（-f 持续跟随），restart 把每个服务按原样重新部署。COMPOSE_FILE 从环境变量读取，没有时从 .env 文件读取（--env-file 指定的文件，或 --project-directory 中或当前目录下的文件），与 Docker Compose 的读法相同；--build 会先构建并推送镜像。参见服务与 Compose。 |
glac deploys create api=ghcr.io/acme/api:2 web, ls, get ID [--wait] |
项目的部署 (/v1/deploys)：多个服务一起部署，按各自依赖的顺序进行，并一起切换。create 接受 SERVICE（按原样）或 SERVICE=IMAGE，以及 -f FILE（JSON：按名称列出服务，每个服务带有版本的字段，或者 {"services": {…}}）；它会等待部署完成（--no-wait 则不等），跟随取代它的部署，失败时以 1 退出并给出失败的服务。参见部署项目。 |
沙箱
| 命令 | 示例 | 作用 |
|---|---|---|
run |
glac run --image python:3.12 -- python3 -c 'print(6*7)' |
创建一个沙箱，运行一条命令并实时输出，然后删除沙箱。Ctrl-C 会同时结束两者。默认 300 秒。glac sandboxes run 是同一个命令。 |
create |
glac sandboxes create --name web --env STAGE=dev |
创建一个沙箱并打印它的 id。--image-pull-secret 用于私有镜像，--egress 用于网络规则，--drive data:/data 用于云盘（data:/snap:dsnap-… 用于它的某个快照，只读；--volume team:/team 用于存储卷），--sleep-notice-ms 和 --sleep-hold-max-ms 设定休眠前多久通知它的程序，以及程序最多能让它保持运行多久。启动时运行的服务：--start（镜像自己的启动命令）或 --start-command LINE，配合 --ready tcp:PORT、http:PORT/PATH 或 cmd:COMMAND；--hostname、--stop-signal 和 --stop-grace-ms 设定机器的名称和服务的停止方式；--project-network 让它从一开始就加入项目的私有网络；--volume team:/team:copy 把镜像在该路径下的内容放进新的存储卷。glac run 也接受这些选项。--checkpoint 10（update 也接受；off 会去掉）让它在运行期间创建检查点。 |
create --init systemd |
glac sandboxes create --name box --init systemd |
完整的系统：镜像自己的 systemd 作为 PID 1（不带 --image 时，使用平台带 systemd 和 OpenSSH 的 Ubuntu），所以软件包、用 systemctl 启动的服务、cron 和 journal 都能像在一台普通机器上一样工作，它也有自己的 machine ID，在休眠、唤醒和迁移后保持不变。不能与 --start、--start-command 或 --ready 同时使用，也不能与 --snapshot 同时使用。glac run 也接受它，glac sandboxes get 会显示 init。 |
ls |
glac sandboxes ls --status running |
列出沙箱，最新的在前；-q 只打印 id。 |
get |
glac sandboxes get web |
它的状态、它为什么在运行、它的设置和用量，以及它的磁盘今天已写入的量与当天全速份额的对比（disk_writes：其中包括检查点的副本；超出份额时，显示磁盘减速到什么时候；在不把磁盘复制到对象存储的节点上为 -）。 |
update |
glac sandboxes update web --sleep-after-seconds never |
名称、环境变量、标签、公开端口、空闲时间、休眠前的通知和保持运行的上限、到期时间、网络规则。create 和 update 上的 --suspend-after-ms（default：节点的默认值）和 --wake-daily-at HH:MM（none：不唤醒）设定它在真正休眠之前保持暂停多久，以及休眠期间每天在 UTC 的哪个时刻唤醒它；glac sandboxes get 会显示它们，以及启动命令的运行情况（start_command：它在机器中被重新启动了多少次、上一次是如何结束的）。--on-expiry delete|sleep|hold 是 --expires-at 到期时的处理方式（删除，即默认；让它休眠并保留；或者同样休眠，但保持休眠），--held-asleep yes|no 决定它休眠时请求能否唤醒它（保持休眠时，它的预览地址返回 502 sandbox_paused，调用 API 才能唤醒它）；get 会显示这两项。 |
rm |
glac sandboxes rm web |
删除一个或多个沙箱。 |
sleep |
glac sandboxes sleep web |
立即休眠。没有唤醒命令：下一个需要它的命令会唤醒它。 |
restart |
glac sandboxes restart web |
从它的磁盘重新启动它。 |
exec |
glac sandboxes exec web -- ls -la /srv |
运行一条命令并实时输出；--detach 只启动命令并打印它的 id。 |
ps, logs, kill |
glac sandboxes logs web exe-… --follow |
它的命令；一条命令的输出；向一条命令及其启动的所有进程发送信号。 |
shell |
glac sandboxes shell web |
一个终端。按 Enter，再按 ~.，就会离开并让它继续运行；--join exe-… 回到这个终端。 |
cp |
glac sandboxes cp -r ./src web:/srv/src |
双向复制文件；- 表示标准输入或标准输出。 |
url |
glac sandboxes url web 3000 |
一个端口链接。拿到链接的人都能打开这个端口。 |
tokens |
glac sandboxes tokens revoke web |
到目前为止为这个沙箱发出的所有令牌都会失效 (401 invalid_token)，包括预览链接和 Cookie 中的令牌，以及 SSH 会话持有的令牌；之后创建的令牌有效。打印它的令牌当前的代次。在沙箱后面给出一个令牌（它的 id、tok_… 或令牌本身）时，只吊销那一个令牌，直到它本应过期的时间。需要 API 密钥：用沙箱令牌调用会返回 403 needs_api_key，退出码 3。 |
snapshots |
glac sandboxes snapshots create web --name before-upgrade |
立即保存内存、进程和磁盘；还有 ls、get、rename（--none 去掉名称）、rm。glac sandboxes create --snapshot 从一个快照启动。 |
fork |
glac sandboxes fork web --count 3 |
从此刻起各自继续运行的副本。 |
restore |
glac sandboxes restore web before-upgrade |
原地回到一个快照；回到之前的状态会作为快照保留。 |
ssh-keys, ssh |
glac sandboxes ssh web --gateway ssh.glac.ai |
注册一个公钥（绝不要注册私钥）；打印某个沙箱的 ssh、scp 和 sftp 命令行。 |
ports |
glac sandboxes ports open web 8080 --from 2001:db8::/32 |
沙箱在它自己的公网 IPv6 地址（如果有）上开放的端口：ls 列出；open 向给定的来源（IPv6 前缀或地址，::/0 表示所有人；53/udp 表示 UDP）开放一个端口，并打印访问它的地址；close 关闭一个。入站默认关闭。create 和 update 上的 --inbound PORT[/udp]=FROM[,FROM…] 给出完整的列表，get 显示地址和开放的端口。参见网络。 |
命令的写法：只有一个参数时，它是交给 sh -c 的一行命令 (glac sandboxes exec web 'ls | wc -l')；有多个参数时，它们是一个程序及其参数，按原样运行。不是终端的标准输入会传给 glac sandboxes exec (tar c . | glac sbx exec web tar x -C /srv)；--no-stdin 会阻止这一点。第一次 Ctrl-C 发给命令；第二次 Ctrl-C 则离开，让命令继续运行。命令属于沙箱，不属于连接：连接断开后，glac sandboxes exec 和 glac sandboxes logs --follow 会从上次停下的地方继续。
命令的输出只保留最后 16 MiB，命令也从不等待读得慢的读取方。glac sandboxes exec 漏掉部分输出时，会说明漏了多少并以 125 退出，而不是传出有缺口的输出。大量输出请写到文件里，再用 glac sandboxes cp 复制出来。
云盘
云盘是项目的一块磁盘，不随使用它的沙箱消失：同一时间只有一个沙箱以读写方式持有它，它保存的内容会留给下一个沙箱：可以在它的区域，也可以在别的区域，只要那里的机器能读取它归属区域的对象存储（glac drives home，见下文）。云盘在写入的同时被复制到所在区域的对象存储中，所以其他节点上的沙箱也能挂载它。只按写入的数据计费。云盘属于控制平面：对着一个独立运行的节点，glac drives … 会得到节点的 404（退出码 4），并说明节点上的磁盘是存储卷。
| 命令 | 作用 |
|---|---|
glac drives create --name data --size-bytes 10GiB --region eu |
创建一个云盘并打印它的 id（vol-…：云盘就是存储卷）。大小必须是 4 KiB 块的整数倍，最小 16MiB；默认 64GiB，免费版上为 5GiB。--durability strict：只有在对象存储收到 fsync 之前的每一次写入后，客户机的 fsync 才返回（默认 standard，一经设定不再改变；参见写入有多持久）。 |
glac drives ls, get data, rename data data-2, rm data |
列出云盘，以及每个云盘写入了多少、哪个沙箱持有它；查看一个云盘，包括它唯一写入方所在的节点，分叉出的云盘还有它的来源云盘 (parent_drive_id) 和这一脉的第一个云盘 (root_drive_id)，数据库的云盘还有所属的数据库（managed_by：只有数据库的实例能以读写方式挂载它，在这里重命名、恢复或删除它都会被拒绝，managed_by_database）；改名（--no-name 去掉名称）；删除（沙箱持有它时不能删除：drive_attached；它的快照会保留并继续计费，直到快照也被删除）。 |
glac drives attach data web:/data, detach data web |
立即以读写方式把云盘挂载到正在运行的沙箱中；卸载它（上面有打开的文件时用 --force）。新沙箱用 glac sandboxes create --drive data:/data 获得云盘，应用的唯一实例用 glac deploy … --drive data:/data，键控应用的每个键的实例用 --key-drive home:/home/app:10GiB 获得各自的云盘。--snapshot dsnap-… 改为以只读方式挂载它的某个快照，glac drives detach dsnap-… web 卸载这个快照（用云盘的名称或 id 时，只卸载它的读写挂载）。 |
glac drives snapshots create data --name before-upgrade |
把云盘保存为此刻的状态，并打印快照的 id (dsnap-…)：它是云盘在对象存储中的一个版本，不复制任何数据。正在运行的沙箱持有的云盘，会在客户机的写入被暂停片刻时创建快照（最多十秒，否则返回 unavailable：请重试）：要么暂停它的机器（consistency 为 paused，云盘处于相当于断电时的状态），要么在带 --fs-consistent 时先冻结它的文件系统（frozen；沙箱的代理程序做不到时为 not_frozen）。没有运行中的沙箱持有的云盘按原样创建快照 (at_rest)。还有 ls data（最新的在前：每个快照是如何创建的、当时云盘有多少数据、它单独保留了多少、它的版本；不指定云盘时，列出项目中所有云盘的快照，--deleted true 只列出已删除云盘的快照）、get data dsnap-…、rm data dsnap-…。快照不随云盘消失：云盘删除后，仍可以通过云盘的 id 列出、读取、分叉和挂载它的快照。节点不向对象存储复制任何数据的控制平面没有快照 (not_copied)。 |
glac drives fork data --name data-try --from-snapshot dsnap-… |
一个新云盘，它的第一个版本就是快照的内容（不带 --from-snapshot 时，是源云盘此刻的内容）；打印它的 id。不复制任何数据：它可以立即挂载，数据块在被读取时从对象存储取来。受套餐的云盘数量限制 (drive_limit_reached)。 |
glac drives restore data dsnap-… |
把云盘恢复到一个快照：在它最新的版本之后新增一个版本，内容与快照相同。中间的版本只要有快照或分叉保留着就仍然存在，所以先恢复到较旧的快照、再恢复到较新的快照也可以；云盘现在的内容只有在快照保留它时才会留下，所以要想能回来，先创建一个快照。沙箱持有云盘时不能恢复 (drive_attached)：先卸载它。 |
glac drives history data 3600, glac drives versions data [--at TIME], glac drives restore data --at TIME, glac drives fork data --at TIME |
云盘的版本窗口 (slice DB8)：按时间最多能往回恢复或分叉多远，3600 到 86400 秒（不设置时没有窗口；关闭后，它保留的内容会被丢弃）。在每个有写入的 30 秒里，窗口都会得到一个版本，即云盘在某一时刻的状态；这些版本单独保留的数据和快照一样计费。按时间恢复或分叉时，取该时间点或之前最新的版本，也就是以该时间调用版本列表时给出的那个版本。glac drives create --history SECONDS 创建带版本窗口的云盘；history DRIVE off 关闭它；versions 列出这些版本（编号、时刻、如何得到、单独保留的数据量）。 |
glac drives create --cache-bytes 2GiB, glac drives cache data 512MiB, glac drives cache data all |
云盘的缓存：节点在 NVMe 上最多保存云盘的多少数据。默认全部保存（即云盘的大小）；也可以设得更小，最小到 0，超出的部分只保存在对象存储中，客户机读到时再从那里读取（最久没被读过的数据最先释放，对象存储还没有的数据从不释放）。缓存按小时、按已填充的量计费，与云盘的数据费用分开。调小缓存后，超出的部分一旦已在对象存储中就会被释放（如果运行中的沙箱挂载云盘时是全部缓存，则从那个沙箱下一次休眠或停止时开始）；调大缓存后，从那时起客户机读到的数据都会留在缓存中。API 把云盘叫作存储卷 (/v1/volumes)；各客户端通过 /v1/drives 访问它们，这个接口的响应和以前一样。glac drives get 会显示缓存设置（全部，或最多多少）以及当前缓存了多少。 |
glac drives home data |
把云盘的归属区域 (slice D9) 立即迁到它现在所在的区域，而不是等它到那里一小时之后。云盘的归属区域是保存其副本的对象存储所在的区域：也就是创建它的区域。另一个区域的沙箱也能挂载它，前提是那个区域的机器能读取其归属区域的存储（不能时返回 not_on_one_machine）；客户机读取时，数据从归属区域的存储读出，客户机写入的数据则进入它当前所在区域的存储。云盘在那里待满一小时后，归属区域会随之迁移，用这个命令则立即迁移：它的机器把归属区域存储中剩下的内容复制到自己区域的存储中。glac drives get 会显示 home，以及迁移进行到哪一步（home_move：何时、为何发起，已复制和剩余的对象，最后一次停下时的错误）。最多每六小时一次 (home_moved_recently)；归属区域已经是当前区域的云盘返回 home_here。 |
glac volumes create --name team --shared, ls, get, rm, attach team web:/team --read-only, detach |
存储卷，即云盘底层的磁盘，为过渡期而保留：共享存储卷，以及独立运行的节点上的磁盘。 |
glac backups create data --expires-in-days 7 |
立即为存储卷（云盘也可以）创建备份并打印它的 id (bak-…)：它是存储卷此刻在对象存储中的副本，只保存自上一次备份以来变化的数据块；如果有沙箱挂载着它，复制时会冻结它的文件系统（几毫秒）。在存储收到全部数据之前，它的状态是 making，之后是 ready，从那时起按存储中保存的数据量、以休眠沙箱所保存内容的价格计费，到期时删除（存储卷规则规定的天数之后，默认 30 天）。还有 ls [--volume data]（最新的在前，附带每个备份的创建原因：manual、daily、before_version，每个备份按多少计费、删除它能省多少、它与其他备份共享多少；也包括已删除存储卷的备份）、get、rm。不向对象存储复制任何数据的机器没有备份 (not_copied)，独立运行的节点也没有：备份属于控制平面。参见备份。 |
glac backups restore bak-… --name data-back |
从一个就绪的备份创建的新存储卷，等同于 glac volumes create --from-backup bak-…：大小和类型与备份所来自的存储卷相同，位于备份所在的区域；在完整拿到备份之前状态为 restoring，之后为 ready；在此之前不能挂载它。如果被分配到的机器无法恢复它，就会在另一台机器上再创建一次，glac volumes get 会说明这一点（restore_attempt 为 2，并附上第一次失败的原因）。 |
快照可以同时被任意多个沙箱以只读方式挂载，可以在云盘所在区域的任意机器上，无论云盘被谁持有，云盘删除后也可以：新沙箱用 glac sandboxes create --drive data:/snap:dsnap-…（那里的 --snapshot 是沙箱要从中继续运行的沙箱快照，所以云盘的快照要跟在 --drive 上，就像 :ro 跟在 --volume 上一样），正在运行的沙箱用 glac drives attach data web:/snap --snapshot dsnap-…。客户机不能写入它，挂载了快照的沙箱也不会被迁到别的机器上。应用的版本只能以读写方式挂载云盘。
计费：快照按它单独保留的数据 (exclusive_bytes) 计费，按小时计，价格与云盘的数据相同（每 GB·月 $0.02）。分叉出的云盘和其他云盘一样，按它的 used_bytes，即完整的逻辑内容计费：从 10 GB 快照分叉出的云盘按 10 GB 的云盘计费。沙箱通过只读挂载读取的数据不收费。glac usage --drive data 报告一个云盘保留了多少、写入了多少、冷读了多少，glac usage --snapshot dsnap-… 报告一个快照保留了多少。
域名
| 命令 | 作用 |
|---|---|
glac domains create api.example.com --app api |
为应用 (--app) 或沙箱的某个端口 (--sandbox web --port 8080) 注册自定义域名，并打印证明这个域名属于你的记录：CNAME（它同时把域名指向这里）或 TXT 记录。在 DNS 上能查到其中一条记录之前，它的状态是 pending_verification，查到后签发证书。--proxied false 让它直接提供服务（地址）。 |
glac domains ls [--app api] [--sandbox web], get, update, rm |
项目的域名；按名称或 id (dom-…) 查看一个域名，未验证时附带它的记录；把它改到另一个应用、沙箱或端口，或修改 --proxied；删除。 |
浏览器
尚未开放。浏览器还没有向账户开放：下面是开放之前命令行目前的样子。
会话是一个托管的 Chromium，由 Playwright、Puppeteer 或任何其他 Chrome DevTools Protocol (CDP) 客户端从外部驱动。有客户端连接时它保持运行，最后一个客户端离开几秒后进入休眠，页面会保留。
| 命令 | 作用 |
|---|---|
glac browsers create [--name NAME] [--headful | --kind KIND] [--region na|eu|ap] [--sleep-after S] [--connection-idle S] [--delete-after-idle S] [--metadata K=V] [--profile NAME [--save-profile]] [--proxy URL] |
创建一个处于运行状态的会话，只打印它的 CDP 地址：也就是 Playwright 的 connectOverCDP 和 Puppeteer 的 browserURL 接受的地址。凭据就在地址里。如果用已有会话的名称创建，会返回那个会话：它会被唤醒，页面都还在。--profile 在返回会话之前加载一个配置文件（它的 Cookie、Local Storage、IndexedDB）；--save-profile 在会话被删除时再次保存它。--kind lightpanda 创建一个 Lightpanda 会话：没有布局引擎（它的截图只包含页面的文字），没有实时视图，没有配置文件。--proxy http://user:password@host:port：你自己的 HTTP 代理，必须接受 CONNECT，仅限付费版：会话到 80 和 443 端口的连接经由它出站，凭据由平台保管（自己的代理）。沙箱在运行前就失败的会话不算会话：创建会被拒绝，返回 503 session_failed。 |
glac browsers get SESSION |
会话：如果失败，失败的原因（failed：浏览器停止且没有恢复，按节点的原话），它的 CDP 地址，实时观看其页面（有头会话则是屏幕）的地址，它的配置文件，它自己的代理（地址和用户名，从不包含密码）以及双向经过代理的流量，它的连接和时间设置。 |
glac browsers ls [--status S] [--kind K] [--name N] |
项目的会话，不含它们的地址（--status awake、asleep、unavailable 或 failed）。 |
glac browsers update SESSION …, sleep SESSION, rotate-url SESSION, rm [--no-save-profile] SESSION… |
修改它的时间设置、元数据或代理（--proxy URL，换成你的另一个代理；--no-proxy，不用代理：浏览器照常运行）；立即让它休眠（已打开的连接保持，并会唤醒它）；换新地址，打印新的 CDP 地址（旧地址会被拒绝，经由它们建立的连接会断开）；结束会话（用 --save-profile 创建的会话会先保存配置文件，除非带 --no-save-profile）。 |
glac browsers live SESSION [--read-only] |
打印在浏览器中实时观看其页面的地址，观看者的鼠标和键盘操作会传到页面上；--read-only 给出一个单独的地址，任何操作都传不到页面，用来给人看。观看者会让会话保持运行。 |
glac browsers save-profile SESSION [PROFILE], profiles ls, profiles rm PROFILE… |
立即保存它的配置文件，作为 PROFILE（或创建它时所用的配置文件）的最新版本，由平台为项目保存：浏览器会重启，已连接的客户端需要重新连接；项目的配置文件；删除配置文件。 |
CDP=$(glac browsers create --name agent-42)
npx @playwright/mcp --cdp-endpoint "$CDP" # or any CDP client会话和任何实例一样，按它使用的方块资源计费：计算时的 CPU、运行时的内存和出站流量（价格与套餐）。glac usage 会在会话的沙箱旁边给出它的用量。
数据库
数据库是托管的 Postgres：运行在云盘上的独立 PostgreSQL，没有任何请求时休眠，有连接时被唤醒，会话都会保留。所有者的密码只出现在 API 对创建和重置的响应中，任何地方都不保存：所以只有 create 和 reset-password 会打印带密码的连接字符串，其他命令都不会打印它。
| 命令 | 作用 |
|---|---|
glac db create NAME [--version 16|17|18] [--region na|eu|ap] [--database NAME] [--vcpus N] [--memory SIZE] [--storage SIZE] [--durability strict|standard] [--sleep-after S] [--suspend-after S] [--wake-at HH:MM] [--tiering] [--metadata K=V] |
创建一个数据库，等它第一次启动（约两秒），然后只打印带所有者密码的连接字符串：psql、psycopg 和 node-postgres 都可以直接使用它。用已有数据库的名称创建时，打印不带密码的连接字符串，并在 stderr 上说明原因。--suspend-after 是它在保存内存、真正休眠之前保持暂停的时长，暂停期间连接在一两毫秒内就能得到响应（1 到 86400 秒，默认 300）；--wake-at 是休眠期间每天在 UTC 的哪个时刻唤醒它（它的 pg_cron 任务无论如何都会在各自的时间唤醒它）。glac db get 会显示这两项，glac db update DATABASE --suspend-after SECONDS|default --wake-at HH:MM|none 可以修改它们，所有分支同时生效（default 恢复为 300，none 表示不唤醒）。在免费版上它们是固定的：--sleep-after 为 1（最后一次查询后一秒暂停），--suspend-after 为 300（五分钟后休眠），就像 Neon 的免费版会缩容到零；其他值会被拒绝。--tiering 开启分层存储（切片 DB18：仅限付费版）；glac db update DATABASE --tiering on|off 之后可以开启或关闭它（某个分支有已分层的分区时，关闭会被拒绝），glac db get 会显示它。 |
glac db ls [--name N], glac db get DATABASE |
项目的数据库（版本、状态、根分支的状态和端点）；查看一个数据库，包括不带密码的连接字符串、大小、云盘、应用和实例。 |
glac db sleep DATABASE [--branch B], glac db wake DATABASE [--branch B] |
立即让一个分支 (main) 休眠，它的内存会被保存，醒来时会话都还在（连接也会唤醒它）；立即唤醒它。 |
glac db reset-password DATABASE [--role ROLE] |
为它的所有者，或为另一个可登录的角色（--role，glac db roles 列出的角色之一）设置新密码：只打印带新密码的该角色的连接字符串。从下一次登录起，旧密码会被拒绝；已打开的连接保持。独立分支保留它创建时的密码。 |
glac db roles DATABASE |
根分支中可登录的角色，直接从 PostgreSQL 读取：它的所有者和你创建的角色 (CREATE ROLE … LOGIN)；平台自己的角色不在其中。为此会唤醒根分支。 |
glac db rm [--no-final-snapshot] DATABASE… |
删除数据库及其分支；除非带 --no-final-snapshot，每个数据库的云盘会保留一个快照七天。 |
glac db branches ls DATABASE, glac db branches get DATABASE BRANCH |
它的分支（先是 main，然后是独立分支，最早的在前），以及其中一个分支。 |
glac db branch create DATABASE BRANCH [--parent B] [--expires-at TIME], glac db branches rm DATABASE BRANCH… |
独立分支：它的父分支（默认 main，可用 --parent 指定其他分支）此刻的状态，不复制任何数据，有自己的 PostgreSQL、端点和云盘，在项目网络上的地址是 DATABASE-BRANCH；给出 --expires-at 时，到时会自行删除。create 会等它第一次启动，并按 API 给出的样子打印它的连接字符串，不带密码：它的角色和密码与父分支相同，所以所有者用数据库的密码登录。rm 停止它的 PostgreSQL 并删除它的云盘；不能删除 main（它随数据库一起删除），也不能删除有其他分支从它创建的分支。 |
glac db restore DATABASE --at TIME [--exact], glac db update DATABASE --history SECONDS, glac db branches create DATABASE BRANCH --at TIME [--exact], glac db create --history SECONDS |
数据库的历史（slice DB8 和 DB5）：根分支按时间最多能恢复到多久以前，或从多久以前创建分支：默认一天；付费版可设为 0（不保留）到 30 天，免费版为一天。恢复会把根分支原地带回过去：恢复到整分钟或某个版本自身的时刻时，使用云盘版本窗口中该时刻或之前最新的版本（每个有写入的 30 秒一个版本，最多保留一天）；更早的时刻、精确到秒的时刻，或带 --exact 时的那个精确时刻（精确到毫秒），则通过 WAL 归档恢复（把 WAL 重放到那一刻：需要几秒到几分钟）。端点、连接字符串和所有者的密码都保持不变，现有连接会断开，恢复之前的状态会作为一个独立分支 main_old_<the restore's moment> 保留；如果新版本在五分钟内不能提供服务，恢复会被撤销 (database_restore_failed)。按时间创建分支时，则以那个时刻创建分支。历史中没有的时间会被拒绝（invalid_history，并说明版本窗口和归档分别能追溯到什么时候）。精确到秒的时间（或带 --exact）只能从归档恢复，否则拒绝，从不退而使用窗口中之前的版本（invalid_history；归档的存储拒绝提供分段时为 database_archive_unavailable，可以重试），拒绝时会指明窗口中该时间或之前的版本；存储给不出所需数据块时会被拒绝（drive_unreadable，可以重试）。glac db get 会显示历史设置 (history … s: restored to a time from … on)，以及 WAL 归档中的每个缺口 (a gap in its WAL archive from … to …)：如果对象存储中断太久，为了保持数据库运行而放弃了部分 WAL，那么缺口内的时间只能从版本窗口恢复，无法精确到秒。 |
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目前，数据库在项目网络上按名称访问，来自项目的沙箱 (--project-network) 和服务；它的公网地址会随平台的公共入口一起提供，API 给出公网地址时，create 会改为打印它（--private 则无论如何都打印项目网络上的地址）。--json 打印 API 的响应：密码只出现在创建和重置的响应中。
托管应用
目录中的应用（比如 Rivet）以它自己的方块资源安装到项目中：它的应用、存储卷、机密和存储桶，都带有该安装的标签，只能通过这个安装修改，并按这些资源本身计费（托管应用）。
| 命令 | 作用 |
|---|---|
glac catalogue ls |
目录中的应用，每个都是最新版本：发布者（verified：由平台打包）、许可证和简介。 |
glac catalogue get APP [--version V] |
查看一个应用：它的版本、发布者、许可证和输出；它的参数，每个参数按点分名称列出，附带类型、默认值和取值范围；以及按它的计算器默认值，一个月在方块各计量项上的费用。 |
glac install APP [--name NAME] [--version V] [--region na|eu|ap] [--set KEY=VALUE]… [--parameters JSON] [--requires NAME=INSTALLATION]… [--no-wait] (glac installations create) |
安装它，等它就绪，在 stderr 上报告进展，然后打印它及其输出（它的地址，以及访问它要用的信息：机密输出只出现在安装的响应中）。--set 设置一个参数，值能按 JSON 解析时按 JSON 处理（2、true、null），否则按文本处理，点分名称表示对象中的一个字段 (--set size.vcpus=2)；--parameters 用一个 JSON 对象给出所有参数（-：标准输入），--set 覆盖其上。安装失败时命令以 1 结束。 |
glac installations ls [--app APP], glac installations get INSTALLATION |
项目中的安装（应用、版本、状态、区域）；查看一个安装，包括它的应用、存储卷、存储桶和输出，密钥无权管理项目时，机密输出显示为 (hidden)。 |
glac installations update INSTALLATION [--version V] [--set KEY=VALUE]… [--parameters JSON] [--no-wait] |
换一个版本，或以合并补丁的方式修改参数（--set KEY=null 把参数恢复为默认值），等待方式与安装相同。 |
glac installations rm INSTALLATION… |
删除安装及构成它的一切，并打印每次删除的响应（deleted，或在剩余部分删除期间显示 deleting）。 |
glac catalogue get rivet
glac install rivet --set disk_gib=20 --set size.vcpus=2项目：机密、共享变量、事件和审计日志
| 命令 | 作用 |
|---|---|
glac project [--delete-after-idle-days 30|never] |
密钥所属的项目：id、名称、归属区域、私有地址段，以及沙箱休眠多少天后被删除（带上选项时先设置这一项）。 |
glac webhooks create https://example.com/hook --events sandbox.created,app.deployed |
把项目的事件签名后发送到你的地址，并打印 Webhook 及其机密（whsec_…，仅此一次显示）；ls（每个 Webhook 最近一次投递的情况）、get、update（--url、--events、--enabled）、rm。需要有 admin 权限范围的密钥。 |
glac keys create --name ci --scopes read,exec |
创建一个项目的 API 密钥并打印它，仅此一次显示（--expires-at 设置会过期的密钥；默认拥有除 admin 以外的所有权限范围）；ls（开头几个字符、权限范围和最近一次使用，从不显示密钥本身）、get、rm。需要有 admin 权限范围的密钥。 |
glac limits [--sandbox web] [--set 50|none] |
项目的支出上限（或某个沙箱自己的支出上限）、本自然月已支出多少，以及是否因达到上限而被冻结；--set 先设置上限，单位是每月美元（设置项目的上限需要有 admin 权限范围的密钥）。 |
glac limits request vcpus 64 --why "a nightly batch of builds", glac limits requests [REQUEST] |
申请提高账户的某项可应要求提高的限制：按名称指定一个上限（instances、vcpus、memory_bytes、sleeping、app_instances、creates_per_minute、creates_per_hour_per_project、app_creates_per_hour），或 volumes 和 volume_bytes（一个大小：2TiB），给出高于当前值的数字，并说明用途。运营方批准或拒绝申请，并通过邮件和事件通知账户。requests 列出申请及其答复，或显示其中一个（需要有 admin 权限范围的密钥）。 |
glac destinations create NAME --endpoint URL --headers FILE|- |
项目中应用的日志导出到哪里（基于 HTTP 的 OTLP；加 --signals logs,metrics 时也导出它们的指标，traces 也在其中时导出它们请求的 span，追踪数据发往别处时用 --traces-endpoint URL：追踪），创建后立即用一条记录测试；ls、get、update、test（立即发送一条记录；不被接收时以 1 退出）、rm。请求头的值从文件、标准输入（每行一个 Name: value）或不回显的终端 (--header NAME) 读取，从不从命令行读取，也没有任何命令会打印它。创建、修改、测试和删除导出目标需要有 admin 权限范围的密钥。参见导出到 OpenTelemetry。 |
glac variables put NAME VALUE, ls, rm |
项目的共享变量。 |
glac secrets put NAME [file] --allowed-host HOST |
保存一个机密，从文件、标准输入 (-) 读取，或在不回显的终端上询问；从不从命令行读取。没有任何命令会显示机密的值。 |
glac secrets hosts NAME [host…], ls, rm |
机密可以发往哪里；列出；删除。 |
glac events --type topup.failed |
项目的事件，最新的在前，每个事件用几个词概括（browser.failed：会话、它的类型和其沙箱的失败代码；database.history_gap：数据库、被放弃的 WAL 从何时开始、在日志中的位置、多少个分段，以及对象存储返回了什么；database.history_resumed：从何时之后归档又可以用于恢复；数据库的创建（附区域和版本）或删除（附保留下来的云盘快照）；分支从父分支创建或被删除，以及原因；根分支恢复到某一时刻，以及之前的状态保存在哪里；WAL 未能归档、从何时开始、对象存储返回了什么、在此期间恢复能追溯多远，以及归档恢复正常；其他事件说明它们涉及什么：沙箱、应用、云盘、备份及其存储卷、导出目标、部署、键及其实例、扣款、撤回）。 |
glac audit --limit 50 |
项目审计日志的一页，最新的在前：每一次不是读取的调用（被拒绝的也算），包括时间、调用者（按名称标识的密钥、沙箱的令牌、控制台的用户、平台、运营方）、方法、路径、状态和来源；以及运营方对应用日志的每一次读取。需要有 admin 权限范围的密钥。 |
账户、用量与计费
| 命令 | 作用 |
|---|---|
glac usage --from 7d --group-by day,metadata.team |
按小时账目统计的用量：CPU 秒、内存 GiB·秒、出站流量、请求和存储的数据，按你要求的方式分组（--group-by backup 为存储卷的每个备份各给出一行和一列）；--kind backup 只保留存储卷备份所保存的量，--backup bak-… 只保留单个备份所保存的量。在沙箱内运行 glac usage --here 读取它自己的计量，不需要密钥。 |
glac account |
账户：本月的出站流量、它的限制 (caps)、密钥所属项目在存储卷和云盘上的保有量，按创建时所受限制的数字给出（keeps：已有多少、最多多少，单个最大多大，全部合计最大多大，不指定大小时创建的大小），通知发往哪里及其语言、欠款、账单地址和税号。出现 email_verified 这一行表示地址还没有验证，出现 email_undeliverable 表示发往它的邮件被退回或被标记为垃圾邮件：无论哪种情况，它的通知都会暂缓发送。 |
glac account email ops@example.com |
账户的通知发往哪里。尚未验证的地址会收到一封带链接的邮件，在链接被打开之前，通知会暂缓发送；再设置一次（即使是同一个地址）会发出新的链接，或在邮件被退回后让邮件重新发往它。none 会去掉地址。参见通知发往哪里。 |
glac account language de |
账户通知使用的语言：en、de 或 fr；auto 重新跟随账单地址。撤回的回执和购买的确认用这种语言撰写；其他所有通知都是英文。 |
glac billing |
套餐，每个计量项的包含额度、已用量和剩余量，余额，本月至今的情况，自动充值及其本月还能扣多少，银行卡，信任等级。 |
glac billing topup 20 |
用已绑定的卡购买 $20 的点数；--start-now 表示买方要求立即获得它们（见下文）。 |
glac billing plan paid |
订阅付费版；free 在已付费的月份结束时终止订阅。接受 --start-now。 |
glac billing auto-reload on --below 5 --reload 20 |
自动充值；glac billing spend-limit 50 限制它每月最多能扣多少。on 接受 --start-now。 |
glac billing ledger, charges |
余额的账目；银行卡的扣款记录。 |
glac billing statement [2026-10] |
一个自然月 (UTC) 的对账单，不指定月份时为本月：每个计量项一行、套餐包含了多少、各行合计多少，本月的各个时段及费用，由哪些点数支付，每个项目用了多少，每个数据库单独一行（它的用量按标价折合多少，其中历史和分层数据单列），以及账户在月底保有的内容。 |
glac billing invoices, notices, withdrawals, withdraw CHARGE --name NAME [--email EMAIL] |
Stripe 上的发票及其 PDF、发给账户的邮件、可以撤回的购买和已做的撤回，以及买方本人的撤回声明，立即受理。欧洲经济区或英国的消费者可以在 14 天内撤回一笔购买：款项会退还，充值剩余的点数会被收回（并关闭自动充值），套餐的当期和订阅在那时结束，回执发往 EMAIL 或账户的地址。撤回需要有 admin 权限范围的密钥。 |
修改计费设置、机密、域名和密钥需要有 admin 权限范围的密钥。
立即购买 (--start-now)。欧洲经济区或英国的消费者（没有已验证或正在验证的税号的账户）可以在 14 天内撤回一笔购买，所购内容只有在其本人明确要求时才会立即提供。glac billing topup、glac billing plan（需要购买的套餐：从免费版升级，或升到更高的套餐）和 glac billing auto-reload on（自动充值保持开启期间的每一次自动充值）上的 --start-now 就带有这一要求，措辞与控制台在勾选框旁显示的相同（GET /v1/billing/withdrawals 中也有，见 right.start_now）：
我要求在可以撤回这笔购买的 14 天内立即提供所购内容。如果我撤回，我需要为此前已提供的部分付费。我理解，一次充值的点数全部用完后，即视为已全部提供，我将不能再撤回。
服务立即开始；在 14 天内，买方仍可撤回，并为此前已提供的部分付费；一旦全部提供（一次充值的点数全部用完），撤回权即丧失。只有在购买者本人提出这一要求时才加上它：glac 不会自行发送它。没有它时，这类账户的购买会得到 API 的 400 start_now_required，什么也不会买。这时，如果标准输入和标准错误都是终端，glac 会显示这段措辞及其含义，并询问 Do you ask for this? [y/N]；只有回答 y 或 yes 才会带着这一要求再次发送同一个调用（充值会使用新的幂等键）。在其他任何地方（脚本、CI、编程智能体），以及只要带了 --json，都不会询问：返回 API 的错误、退出码 1，外加一行说明 --start-now 的作用。智能体绝不能替人提出这一要求：这只能由本人提出。开启了自动充值却没有这一要求的账户不会自动充值，并且每月会收到一次通知（auto_reload.no_request 事件，glac events 会用文字说明它）。
退出码
| 退出码 | 含义 |
|---|---|
| 0 | 成功 |
| 1 | 失败：API 拒绝了请求（冲突、错误的请求、没有买方要求的购买：start_now_required），本地文件无法读写，或部署的版本没有起来 |
| 2 | 命令行有误 |
| 3 | 不允许：没有密钥、密钥错误，或密钥或用户没有相应权限 |
| 4 | 不存在 |
| 5 | 无法连接 API，或 API 此刻不可用 |
| 6 | 账户欠费：在付清之前，它只能查看账单、付款，以及列出和删除它存储的内容 |
| 125 | 在 run、exec、shell 中：不是命令本身导致的失败（上面的 1、3、4、5、6，或输出没有全部读到） |
| 其他 | 在 run、exec、shell 中：命令自己的退出码 |