会话

尚未开放。浏览器还没有向账户开放。本页按目前正在构建的样子介绍它，开放前可能还会变化。

调用

创建、修改、让会话休眠和结束会话需要有 write 权限范围的密钥；读取会话需要 read。会话的地址是凭据，没有 url 权限范围的密钥读到的 cdp_url 和 live_url 为 null。

创建会话

每个字段都可以省略：

POST /v1/browsers
{"name": "agent-42", "region": "eu", "sleep_after_seconds": 30}

返回的是会话 (201)，带 Location: /v1/browsers/<id>。创建请求接受 Idempotency-Key，以同一个键再次发送的请求返回与第一次相同的结果。

创建可能因为超出套餐允许账户同时运行的数量而被拒绝（403 plan_cap_reached，param 为 instances、vcpus 或 memory_bytes），也可能因为此刻没有机器能容纳它而被拒绝（503 no_capacity，retryable）。没有为该类型提供镜像的控制平面不会创建这种会话（503 not_served_here，param 为 kind）。浏览器无法启动的会话（拿不到镜像，或浏览器没有起来）不算会话：创建会被拒绝（503 session_failed，retryable），message 中带有机器给出的信息和错误码，会话不会留下任何东西。

会话包含什么

同一个名称，同一个会话

用项目中已有会话的名称创建，返回的就是那个会话 (200)，它会被原样唤醒，页面也保持原样：智能体每一轮都请求 agent-42，拿回的都是同一个浏览器。和任何唤醒一样，这次唤醒受套餐允许账户同时运行的数量限制。同时用同一个名称发起两次创建，只会创建一个会话，两次请求都返回它。

项目中普通沙箱已经在用的名称会被拒绝 (409 name_taken)：沙箱不会变成会话。另一种类型的会话的名称也会被拒绝；profiles 同样会被拒绝 (400 invalid_name)，因为它是配置文件的地址。

运行与休眠

只要有客户端连接着它的浏览器（或 chromium 会话的屏幕），会话就保持运行，无论页面在做什么；页面自己的定时器和网络活动不会让它保持运行。最后一个连接关闭（以及最后一个请求结束）sleep_after_seconds 秒后，它连同内存和磁盘一起进入休眠：醒来时，标签页和页面都还在。在 connection_idle_seconds 秒内两个方向都没有任何数据的连接会被关闭，所以没有关闭连接就离开的客户端不会让会话一直运行。

• POST /v1/browsers/{id}/sleep 立即让它休眠。已打开的连接保持打开，连接上的下一条消息会唤醒会话。
• 连接它的地址就会唤醒它。
• PATCH /v1/browsers/{id} 可以修改 sleep_after_seconds、connection_idle_seconds、delete_after_idle_seconds、metadata（整体替换）和 proxy；null 把时间恢复为默认值，delete_after_idle_seconds: null 让它永久保留，proxy: null 去掉代理。

新地址

POST /v1/browsers/{id}/rotate-url 为会话的地址换一个新的机密。之前给出的所有地址从此都会被拒绝 (401 invalid_link)，经由它们建立的连接（包括 CDP 客户端的连接）会在调用返回之前断开。返回的是带有新 cdp_url 的会话。地址被不该看到的人看到时，就这样做。

自己的代理

在付费版上，会话可以把网页流量经由你自己的 HTTP 代理发出：创建会话时给它 proxy，或者之后再修改。

POST /v1/browsers
{"name": "agent-42", "proxy": {"url": "http://user:password@proxy.example.com:3128"}}

• 哪些流量经过它：会话到 80 和 443 端口的 TCP 连接，也就是浏览器加载页面所用的连接。在运行浏览器的机器上，浏览器旁边有一个中继，它读取每个连接的去向（TLS 握手中的服务器名称，HTTP 请求的 Host），然后请你的代理建立一条通往那里的隧道（CONNECT name:port，你的凭据放在 Proxy-Authorization: Basic 请求头中）。网站看到的是你的代理的地址，域名在代理处解析。隧道里的内容不会被读取或修改：TLS 仍然在浏览器和网站之间进行。
• QUIC 会被拒绝：到 443 端口的 UDP 流量（任何 HTTP 代理都不承载它）不会离开会话，所以浏览器会经由代理、通过 TCP 使用 HTTP。到其他任何端口的连接照常出站，就像没有代理一样。
• 浏览器并不知情：浏览器的设置里没有任何代理，也不会为此重启任何东西，会话内部也没有任何东西持有凭据（没有文件、环境变量或进程）。凭据由运行会话的机器保管，API 的任何返回中都没有它们：proxy 只显示地址和用户名。
• 代理必须是接受到 80 和 443 端口的 CONNECT 的 HTTP 代理（Squid 只放行到 443 端口的 CONNECT，除非你也允许 80 端口），位于互联网上的某个主机名或地址：只支持 http://，用户名和密码中含有 URL 不接受的字符（@、:、/）时，要写成 %XX。通过 TLS 访问的代理 (https://)、SOCKS，以及沙箱无法访问的地址（私有地址段、链路本地地址、环回地址）都会被拒绝，返回 400 invalid_proxy（param 为 proxy.url）；错误信息从不复述这个 URL。
• 修改代理：用 PATCH /v1/browsers/{id} 设置另一个 proxy，或设为 null 不用代理，从下一个连接起生效：浏览器和页面照常继续，之前经过代理的连接会被断开，浏览器会打开新的连接，按会话现在的设置出站。
• 代理不建立隧道时（连不上代理，或代理对 CONNECT 的响应不是 2xx，比如凭据不被接受时的 407）：通过 HTTP 加载的页面会得到 502 proxy_failed，错误信息会说明代理的地址和它的响应，但从不包含凭据；通过 HTTPS 加载的页面会在 TLS 握手时失败。会话所在的机器会把这件事记入日志，不含凭据。
• 费用：经过代理的流量按两个方向计数 (usage.proxy_bytes)，和其他流量一样算作会话的流量：发往你的代理的流量属于出站流量，按沙箱的价格计费。
• 不能与请求规则同时使用：如果会话的网络规则会读取它的请求（inject、http），它就不能使用代理，返回 400 invalid_proxy；按地址、按端口和按名称的规则，对经过代理的流量和其他流量同样有效。
• 代理只属于会话：普通沙箱不接受代理 (400 unknown_field)。

会话的网络

会话和沙箱一样访问互联网，但从不访问 25、465 和 587 端口（邮件）以及矿池监听的端口（3333、4444、5555、7777、14444、45700）：它的机器会在一切规则之前拒绝这些连接。会话的网络规则用 PATCH /v1/sandboxes/{id} 的 egress 修改，无论规则怎么写，这些端口都保持关闭。