feat(api): return BYOC cluster domain from volume endpoints

[djeebus]

When a team is connected to a custom (BYOC) cluster, the volume create and get endpoints now include the cluster's domain in the VolumeAndToken response. SDKs use this domain as the destination for volume content requests instead of the default api.<E2B_DOMAIN> host. Teams on the default cluster get no domain and keep their configured default.

[cursor]

PR Summary

Medium Risk
Changes volume-content JWT audience and BYOC routing; misconfigured clusters or domain/aud mismatch would break content auth, and any consumer that still expects aud as cluster ID would fail validation.

Overview
BYOC teams can route volume content traffic to their cluster edge: volume create and get still manage metadata in the control plane, but responses now include an optional domain (from the team’s cluster SandboxDomain) so SDKs hit api.<domain> instead of the default api.<E2B_DOMAIN>. Default-cluster teams keep omitting domain and unchanged client defaults.

Volume content JWTs now use aud = https://api.<domain> (BYOC domain or deployment DOMAIN_NAME), aligned with the belt volume-content API origin, replacing the previous cluster-ID audience. Create resolves the domain before orchestrator work and returns 503 when a BYOC team’s cluster is missing from the pool; get does the same before signing. Architecture docs describe the SDK → belt content path and token/domain behavior.

^{Reviewed by Cursor Bugbot for commit 02f41af. Bugbot is set up for automated code reviews on this repo. Configure here.}

[codecov]

Codecov Report

❌ Patch coverage is 35.41667% with 31 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
packages/api/internal/clusters/mock.go	0.00%	11 Missing ⚠️
packages/api/internal/handlers/volume_create.go	0.00%	11 Missing ⚠️
packages/api/internal/handlers/volume_get.go	0.00%	9 Missing ⚠️

📢 Thoughts on this report? Let us know!

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bf93ab7dd3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Reject BYOC clusters that have no volume domain

When a team is assigned to a cluster whose sandbox_proxy_domain is null—which remains valid under AdminClusterCreateRequest in spec/openapi-dashboard.yml:422-424—this returns (nil, nil), so omitempty removes domain and the SDK falls back to the default control-plane host. Volume-content requests are then routed to the wrong cluster; return a configuration error here or make the domain mandatory for BYOC clusters.

AGENTS.md reference: AGENTS.md:L22-L26

Useful? React with 👍 / 👎.

[djeebus]

This is acceptable, it's deep into undefined behavior. If there's no client proxy domain, the whole cluster doesn't work, so this is the least of that cluster's problem.

[chatgpt-codex-connector]

Document the BYOC volume-content route

This contract redirects SDK volume-content traffic from the configured control-plane API host to the BYOC cluster domain, but docs/ARCHITECTURE.md:33-46 still models SDK traffic only through the main load balancer and API and contains no volume-content path. Add this cross-service routing flow to the architecture document as required for routing and topology changes.

AGENTS.md reference: AGENTS.md:L7-L9

Useful? React with 👍 / 👎.