[williamloo-scale]

Stacked on #448.

A website env can record every packet its websites' server and frontend containers send and receive, as PCAP, and serve the files through its card. This is opt-in.

• Turning it on: deploy_env takes capture_traffic, and agent-env env deploy takes --capture-traffic. It works for a website env, or a multi env with a website, on a VM. Any other env, and container mode, refuse it.

• Capture: each website container gets a tcpdump service beside it.

  • tcpdump comes from the gateway image and runs in that container's network namespace (network_mode: "service:<container>").
  • It's the only service holding NET_RAW/NET_ADMIN.
  • It writes rotating classic pcap files, 10 of 20 MB each with the oldest overwritten, to a volume no website container mounts. The gateway mounts it read-only.
  • The deploy is refused if a capture isn't running once the gateway is up.

• Protocol: the new agentenv_protocol.traffic defines urn:agentenv:traffic/v1 with two ops:

  • list returns a TrafficCaptureListing, oldest file first;
  • get streams one file as application/vnd.tcpdump.pcap.

  Client helpers: list_traffic_captures, fetch_traffic_capture, serves_traffic. The gateway's constants.py mirrors the names, with a test keeping them equal.

• Access: both ops require the per-deploy control token (DeployedEnv.control_token). The gateway removes Authorization from a proxied request only when it carries that token (compared with hmac.compare_digest), so no site can read the token, and a site's own bearer auth still reaches it.

• Collection: the new collect_traffic_capture step stores each capture as a pcap FileArtifact in one FileArtifactUniverse, recorded under context.metadata["traffic_captures"][env_id]. It's best effort unless fail_task_on_error is set. Teardown also collects any capturing env the run didn't collect, before the env closes, so a capture isn't lost with its VM.

Before merging

• Not yet run on a deployed VM. The compose wiring, gateway routes, token stripping, step and teardown are covered by unit tests.

Test

Unit suite on this branch: 13,358 passed, lint clean. One GitHub-clone test from main is deselected because it hangs on the local machine on main too.

🤖 Generated with Claude Code

Confidence Score: 5/5

The documentation-only update appears safe to merge.

Summary

Adds opt-in website traffic capture, token-protected downloads through traffic/v1, and collection into file artifacts before teardown.

• Website deployments can record traffic from their server and frontend containers.
• The gateway lists and streams pcap captures through a token-protected traffic API.
• Task runs can save website traffic captures and collect missed files during teardown.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Site[Website container] -->|shared network namespace| Capture[tcpdump sidecar]
  Capture --> Volume[Rotating PCAP files]
  Volume -->|read-only mount| Gateway[Gateway traffic/v1]
  Gateway -->|control token required| Collect[Collection step or teardown]
  Collect --> Files[File artifacts and universe]
  Files --> Run[Saved run metadata]

Loading

_{Reviews (11) · Last reviewed commit: "docs(website): traffic capture records w..." · Reviewed by Greptile}