feat(api)!: use sandbox names as canonical references

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

Author: drew

.agents/skills/tui-development/SKILL.md

@@ -479,10 +479,10 @@ use openshell_core::proto::{
 
 ### Proto field gotchas
 
-- `DeleteSandboxRequest` uses the `name` field (not `id`):
+- `DeleteSandboxRequest` uses the canonical sandbox name and an explicit workspace:
   ```rust
   let req = openshell_core::proto::DeleteSandboxRequest {
-      name: sandbox_name,
+      sandbox: sandbox_name,
       workspace_scope: Some(workspace_selector(workspace)),
       allow_missing: true,
   };
@@ -493,11 +493,12 @@ use openshell_core::proto::{
 - `WatchSandboxRequest` has extra fields beyond what you might need — always use `..Default::default()`:
   ```rust
   let req = openshell_core::proto::WatchSandboxRequest {
-      id: sandbox_id,
+      sandbox: sandbox_name,
       follow_status: false,
       follow_logs: true,
       follow_events: false,
       log_tail_lines: 0,
+      workspace_scope: Some(workspace_selector(workspace)),
       ..Default::default()
   };
   ```
@@ -506,7 +507,7 @@ use openshell_core::proto::{
   Select one workspace with `Some(workspace_selector(name))`. List requests that
   explicitly support cross-workspace access also accept
   `Some(all_workspaces_selector())`; do not use that marker on other requests.
-- `GetSandboxLogsRequest` fields: `sandbox_id`, `lines` (u32), `since_time` (`Option<prost_types::Timestamp>`),
+- `GetSandboxLogsRequest` fields: `sandbox`, `lines` (u32), `since_time` (`Option<prost_types::Timestamp>`),
   `sources` (Vec<String>), `min_level` (String), `workspace_scope`.
 - `ListSandboxesRequest` fields: `page_size` (i32), `page_token` (String),
   `label_selector` (String), `workspace_scope`.
@@ -517,10 +518,10 @@ use openshell_core::proto::{
 - Paginated list responses return `next_page_token`. Continue with the same
   request parameters and that token until it is empty; changing filters or
   scope invalidates the token.
-- `UpdateConfigRequest` fields include `name` (String, sandbox name or empty for
-  global), `setting_key`, `setting_value`, `delete_setting` (bool), `global`
-  (bool), and `workspace_scope`. Sandbox-scoped updates require a named selector;
-  gateway-global updates must leave `workspace_scope` as `None`.
+- `UpdateConfigRequest` fields include `sandbox` (String, canonical sandbox name),
+  `setting_key`, `setting_value`, `delete_setting` (bool), `global` (bool), and
+  `workspace_scope`. Sandbox-scoped updates require `sandbox` and a named selector;
+  gateway-global updates leave `sandbox` empty and `workspace_scope` as `None`.
 - Most resource requests require an explicit named `workspace_scope`, including
   the `default` workspace. An omitted selector is not an implicit default.
 

architecture/gateway.md

@@ -110,13 +110,20 @@ cross-origin or sibling-subdomain request.
 
 Public workspace-scoped RPCs carry a typed `WorkspaceSelector`. A request must
 select one non-empty workspace explicitly; `default` is an ordinary explicit
-name, not an omitted-value fallback. Sandbox, sandbox template, provider, and
-service list RPCs also accept an all-workspaces marker after Platform Admin
-authorization. Single-workspace handlers reject that marker. Platform-global
-policy operations require the selector to be absent, while workspace policy
-operations require it. The gateway authorizes the selected scope before
-performing resource lookup so malformed, unsupported, and unauthorized scopes
-have consistent behavior across resource types.
+name, not an omitted-value fallback. Every public sandbox-scoped RPC identifies
+the sandbox with a string `sandbox` and carries its workspace selector as
+a separate request field. Canonical sandbox IDs remain internal metadata used
+at authentication, persistence, and compute-driver boundaries; public callers
+do not use them as sandbox references. The gateway resolves the name to the
+persisted sandbox record only after authorizing the selected workspace. A
+sandbox principal is instead resolved by the immutable ID in its authenticated
+identity, then checked against the requested name and workspace. Missing and
+unauthorized references use the same response within each principal class so
+the resolver does not expose an object-existence oracle. Sandbox, sandbox
+template, provider, and service list RPCs also accept an all-workspaces marker
+after Platform Admin authorization. Single-workspace handlers reject that
+marker. Platform-global policy operations require `sandbox` and
+`workspace_scope` to be absent, while sandbox policy operations require both.
 
 Docker and Podman report the local address through which their sandboxes can
 reach the gateway. When the primary listener covers that address, the gateway

crates/openshell-cli/src/commands/provider.rs

@@ -64,7 +64,7 @@ pub async fn sandbox_provider_list(
     let mut client = grpc_client(server, tls).await?;
     let response = client
         .list_sandbox_providers(ListSandboxProvidersRequest {
-            sandbox_name: name.to_string(),
+            sandbox: (name).to_string(),
             workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
         })
         .await
@@ -96,7 +96,7 @@ pub async fn sandbox_provider_attach(
     // Fetch current sandbox to get resource_version for CAS
     let sandbox = client
         .get_sandbox(GetSandboxRequest {
-            name: name.to_string(),
+            sandbox: (name).to_string(),
             workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
         })
         .await
@@ -110,10 +110,10 @@ pub async fn sandbox_provider_attach(
     let response = match client
         .attach_sandbox_provider(AttachSandboxProviderRequest {
             request_id: String::new(),
-            sandbox_name: name.to_string(),
+            sandbox: (name).to_string(),
+            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
             provider_name: provider.to_string(),
             expected_resource_version: resource_version,
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
         })
         .await
     {
@@ -153,7 +153,7 @@ pub async fn sandbox_provider_detach(
     // Fetch current sandbox to get resource_version for CAS
     let sandbox = client
         .get_sandbox(GetSandboxRequest {
-            name: name.to_string(),
+            sandbox: (name).to_string(),
             workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
         })
         .await
@@ -167,10 +167,10 @@ pub async fn sandbox_provider_detach(
     let response = match client
         .detach_sandbox_provider(DetachSandboxProviderRequest {
             request_id: String::new(),
-            sandbox_name: name.to_string(),
+            sandbox: (name).to_string(),
+            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
             provider_name: provider.to_string(),
             expected_resource_version: resource_version,
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
         })
         .await
     {

crates/openshell-cli/src/main.rs

@@ -644,7 +644,7 @@ enum Commands {
     /// Two mutually exclusive modes:
     ///
     /// **Token mode** (used internally by `sandbox connect`):
-    ///   `openshell ssh-proxy --gateway <url> --sandbox-id <id> --token <token>`
+    ///   `openshell ssh-proxy --gateway <url> --sandbox <name> --token <token>`
     ///
     /// **Name mode** (for use in `~/.ssh/config`):
     ///   `openshell ssh-proxy --gateway <name> --name <sandbox-name>`
@@ -655,9 +655,9 @@ enum Commands {
         #[arg(long, short = 'g')]
         gateway: Option<String>,
 
-        /// Sandbox id. Required in token mode.
+        /// Sandbox name. Required in token mode.
         #[arg(long)]
-        sandbox_id: Option<String>,
+        sandbox: Option<String>,
 
         /// SSH session token. Required in token mode.
         #[arg(long)]
@@ -2141,7 +2141,7 @@ enum ServiceCommands {
         page_token: String,
 
         /// List services across all workspaces (overrides --workspace).
-        #[arg(long)]
+        #[arg(long, conflicts_with = "sandbox")]
         all_workspaces: bool,
 
         /// Output format.
@@ -3785,23 +3785,24 @@ async fn run_async() -> Result<()> {
         }
         Some(Commands::SshProxy {
             gateway,
-            sandbox_id,
+            sandbox,
             token,
             server,
             gateway_name,
             name,
         }) => {
-            match (gateway, sandbox_id, token, server, gateway_name, name) {
+            match (gateway, sandbox, token, server, gateway_name, name) {
                 // Token mode (existing behavior): pre-created session credentials.
-                (Some(gw), Some(sid), Some(tok), _, gateway_name_opt, _) => {
+                (Some(gw), Some(sandbox), Some(tok), _, gateway_name_opt, _) => {
                     let mut effective_tls = match gateway_name_opt {
                         Some(ref g) => tls.with_gateway_name(g),
                         None => tls,
                     };
                     if let Some(ref g) = gateway_name_opt {
                         apply_auth(&mut effective_tls, g)?;
                     }
-                    run::sandbox_ssh_proxy(&gw, &sid, &tok, &effective_tls).await?;
+                    run::sandbox_ssh_proxy(&gw, &sandbox, &cli.workspace, &tok, &effective_tls)
+                        .await?;
                 }
                 // Name mode with --gateway-name: resolve endpoint from metadata.
                 (_, _, _, server_override, Some(g), Some(n)) => {
@@ -3827,7 +3828,7 @@ async fn run_async() -> Result<()> {
                 }
                 _ => {
                     return Err(miette::miette!(
-                        "provide either --gateway/--sandbox-id/--token or --gateway-name/--name (or --server/--name)"
+                        "provide either --gateway/--sandbox/--token or --gateway-name/--name (or --server/--name)"
                     ));
                 }
             }
@@ -4477,19 +4478,22 @@ mod tests {
             "ssh-proxy",
             "--gateway",
             "https://gw.example.com:8080/proxy/connect",
-            "--sandbox-id",
-            "sbx-123",
+            "--sandbox",
+            "my-box",
+            "--workspace",
+            "team-a",
             "--token",
             "tok-abc",
             "--gateway-name",
             "my-gateway",
         ])
         .expect("TUI proxy command flags must be accepted by the CLI");
+        assert_eq!(cli.workspace, "team-a");
 
         match cli.command {
             Some(Commands::SshProxy {
                 gateway,
-                sandbox_id,
+                sandbox,
                 token,
                 gateway_name,
                 ..
@@ -4499,7 +4503,7 @@ mod tests {
                     Some("https://gw.example.com:8080/proxy/connect"),
                     "gateway URL must land in SshProxy.gateway, not the global flag"
                 );
-                assert_eq!(sandbox_id.as_deref(), Some("sbx-123"));
+                assert_eq!(sandbox.as_deref(), Some("my-box"));
                 assert_eq!(token.as_deref(), Some("tok-abc"));
                 assert_eq!(gateway_name.as_deref(), Some("my-gateway"));
             }
@@ -6091,6 +6095,19 @@ mod tests {
         }
     }
 
+    #[test]
+    fn service_list_rejects_sandbox_with_all_workspaces() {
+        let result = Cli::try_parse_from([
+            "openshell",
+            "service",
+            "list",
+            "my-sandbox",
+            "--all-workspaces",
+        ]);
+
+        assert!(result.is_err());
+    }
+
     #[test]
     fn service_get_accepts_optional_service_name() {
         let cli = Cli::try_parse_from(["openshell", "service", "get", "my-sandbox", "api"])