You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
As an API or SDK client, I want one canonical way to identify a sandbox, so that the same reference works across lifecycle, logs, policy, exec, forwarding, services, and provider operations.
Problem Statement
Gateway RPCs currently identify sandboxes using several combinations of sandbox name, internal ID, workspace, and nested request fields. Equivalent operations do not consistently accept the same identity shape, and some comments and implementations disagree about whether a field is a name or ID.
Impact / Why This Matters
Clients must retain multiple identifiers and learn per-RPC conventions. SDKs duplicate translation logic, authorization can be applied after different lookup paths, and renaming or changing workspace scope becomes difficult. Every new sandbox operation risks introducing another reference shape.
Proposed Design
Define one canonical public sandbox reference message with the supported user-facing identity and workspace scope. Use it consistently in every user-facing RPC that targets an existing sandbox. Supervisor/internal callback APIs may retain an internal ID-only reference when explicitly classified as internal.
The contract must define canonical lookup behavior, error behavior, authorization order, and whether stable internal IDs are exposed to ordinary clients.
Acceptance Criteria
Every user-facing RPC that targets a sandbox uses the canonical reference type or documents a justified exception.
Name, internal ID, and workspace semantics are unambiguous.
The same reference can be reused across get, delete, watch, logs, exec, forwarding, services, policy, and provider attachment.
Authorization and not-found behavior are consistent across lookup paths.
Internal supervisor callbacks remain clearly separated from the public reference contract.
CLI, TUI, Rust, Python, TypeScript, and Go SDKs use the shared model.
Existing fields are migrated with reserved names/tags and documented examples.
Alternatives Considered
Continue using per-RPC name and workspace fields. This minimizes immediate churn but permanently exposes inconsistent lookup rules. Expose only internal sandbox IDs. This simplifies lookup but makes the public API less aligned with workspace-scoped user-facing names and forces clients to perform an extra discovery step.
Agent Investigation
The audit found multiple sandbox-addressing shapes across the gateway service. Request-shape changes should be coordinated with the CreateSandbox and workload/template cleanup in #2680.
User Story
As an API or SDK client, I want one canonical way to identify a sandbox, so that the same reference works across lifecycle, logs, policy, exec, forwarding, services, and provider operations.
Problem Statement
Gateway RPCs currently identify sandboxes using several combinations of sandbox name, internal ID, workspace, and nested request fields. Equivalent operations do not consistently accept the same identity shape, and some comments and implementations disagree about whether a field is a name or ID.
Impact / Why This Matters
Clients must retain multiple identifiers and learn per-RPC conventions. SDKs duplicate translation logic, authorization can be applied after different lookup paths, and renaming or changing workspace scope becomes difficult. Every new sandbox operation risks introducing another reference shape.
Proposed Design
Define one canonical public sandbox reference message with the supported user-facing identity and workspace scope. Use it consistently in every user-facing RPC that targets an existing sandbox. Supervisor/internal callback APIs may retain an internal ID-only reference when explicitly classified as internal.
The contract must define canonical lookup behavior, error behavior, authorization order, and whether stable internal IDs are exposed to ordinary clients.
Acceptance Criteria
Alternatives Considered
Continue using per-RPC name and workspace fields. This minimizes immediate churn but permanently exposes inconsistent lookup rules. Expose only internal sandbox IDs. This simplifies lookup but makes the public API less aligned with workspace-scoped user-facing names and forces clients to perform an extra discovery step.
Agent Investigation
The audit found multiple sandbox-addressing shapes across the gateway service. Request-shape changes should be coordinated with the CreateSandbox and workload/template cleanup in #2680.
Related: #2565, #2680. Source audit: https://gist.github.com/mrunalp/e80942c1544a0225ee588796a41ab30b.