链接、令牌与 SSH

端口链接

GET /v1/sandboxes/{id}/url?port=3000 (glac sandboxes url web 3000) 给出指向该端口的链接：https://<port>-<sandbox id>-<signature>.glac.run/。SDK 自己就能签名链接，不需要发请求 (sbx.url(3000))。

• 链接就是凭据。拿到链接的人就能打开这个端口，而且从一个端口的链接推算不出另一个端口的链接。不需要事先注册任何东西，打开链接的人会唤醒沙箱。
• 换新链接。POST /v1/sandboxes/{id}/url-secret 更换机密，所有旧链接随即失效。
• 公开端口。public_ports 中的端口 (--public-port 8080) 还有一个不带签名的短链接 https://<port>-<sandbox id>.glac.run/，任何人都可以打开。
• 自定义域名可以指向沙箱的某个端口：POST /v1/domains 带上 {domain, sandbox, port}，和应用一样（地址）。
• 直连。链接经过平台前面的代理到达沙箱；把同样的第一部分放到 direct.glac.run 下就能绕过代理，用于更大的上传、更长的响应，以及代理无法承载的协议（地址）。

经由链接的请求算作一个请求，响应算作出站流量。链接在 glac.run 下提供，与我们自己的网站分开。在 glac.run 进入公共后缀列表 (Public Suffix List) 之前，某个域名下的页面可以为整个 glac.run 设置 Cookie，其他客户的页面可以读到它：不要信任作用于整个域的 Cookie。

单个沙箱的令牌

令牌在一段时间内只能打开一个沙箱，别的都不行。把它交给应该能访问这个沙箱、但不能访问整个项目的浏览器、用户或程序。

curl -X POST https://api.glac.ai/v1/sandboxes/web/tokens \
  -H "Authorization: Bearer $GLAC_API_KEY" -H 'Content-Type: application/json' \
  -d '{"scopes": ["exec", "files"], "expires_in_seconds": 3600}'

token = sbx.token(scopes=["url", "tty"], expires_in_seconds=600)

• 权限范围：url（端口链接）、exec（命令）、files、tty（终端）。默认为 url。
• 有效期：默认一小时，最多 30 天。
• 用法：Authorization: Bearer st_…，代替密钥。GET 请求也可以把它放在 ?sandbox_token= 中，供无法给 EventSource 和 WebSocket 设置请求头的浏览器使用。在链接上，地址中带着令牌前来的浏览器会被重定向到不带令牌的地址，令牌则保存在脚本读不到的 Cookie 中。
• 用命令行：GLAC_API_KEY=st_… glac sandboxes exec web ls，对那个沙箱上的 exec、cp、shell 和 url 都有效。
• 令牌一直有效，直到过期，或直到沙箱的令牌被吊销：POST /v1/sandboxes/{id}/tokens/revoke（glac sandboxes tokens revoke web，Python 中为 sbx.revoke_tokens()）会拒绝此前为该沙箱签发的所有令牌，之后申请的令牌照常有效。
• 单独吊销一个令牌：同一个调用带上 {"token": "st_…"}，或带上 {"token_id": "tok_…"}（令牌附带的 id），只拒绝这一个令牌，不影响其他令牌，在重启、休眠和迁移后依然有效，直到它本应过期的时间：glac sandboxes tokens revoke web tok_…，Python 中为 sbx.revoke_token(token)，MCP 服务器中为带 token 的 sandbox_revoke_tokens。一个沙箱最多保留 1,000 个这样的令牌（超出时返回 409 too_many_revoked_tokens）：吊销所有令牌可以腾出空间。

SSH

注册一个公钥 (POST /v1/ssh-keys)，之后任何 SSH 客户端都能通过 SSH 网关进入项目的沙箱：

glac sandboxes ssh-keys add ~/.ssh/id_ed25519.pub --name laptop
glac sandboxes ssh web --gateway ssh.glac.ai     # prints the ssh, scp and sftp command lines
ssh web@ssh.glac.ai                              # a shell in the sandbox web
ssh web@ssh.glac.ai 'make test'                  # one command; its exit code is ssh's

• 用户名就是沙箱，用 id 或名称；<user>+<sandbox> 以沙箱中的另一个用户身份运行。
• 一个密钥可以打开项目中的所有沙箱，或者只打开指定的那个 (--sandbox web)，直到 --expires-at。只会读取公钥部分；包含私钥的文件会被拒绝。
• glac sandboxes ssh-keys rm 会在半分钟内结束该密钥的会话。
• 沙箱所在的机器重启时（比如发布新版本），会话不会断：沙箱带着里面运行的东西休眠度过这段时间，会话等机器恢复后从上次停下的地方继续。命令打印的内容不会丢失，也不会重复显示，这期间你输入的内容会在机器恢复后送进去。机器一分钟内没有恢复时，会话结束，并说明原因。
• 沙箱迁到另一台机器，或它的机器被撤下时，它的会话会收到原因并结束，ssh 以 255 退出；经由已撤下机器的新会话会被拒绝，并附上原因。重新连接即可：迁移之后，会话会到达沙箱现在所在的地方，进程都在。
• 注册和删除密钥需要有 admin 权限范围的 API 密钥：能注册 SSH 密钥的密钥可以进入项目中的所有沙箱。