fix(cli): use forward command for service forwarding

Author: pimlock

.agents/skills/debug-openshell-cluster/SKILL.md

@@ -128,9 +128,9 @@ helm -n openshell get values openshell | grep -E 'repository|tag|supervisorImage
 
 The gateway image and `server.supervisorImage` should use the same build tag in branch and E2E deploys. A stale supervisor image can make sandbox behavior lag behind gateway policy or proto changes.
 
-For local/external pull mode (the default local path via `mise run cluster`), local images are tagged to the configured local registry base, pushed to that registry, and pulled by k3s via the `registries.yaml` mirror endpoint. The `cluster` task rebuilds the local gateway image before tagging and pushing it, so a fresh bootstrap should not reuse stale `openshell/gateway:dev` bits from a previous source revision.
+For local/external pull mode (the default local path via `mise run cluster`), local images are tagged to the configured local registry base, pushed to that registry, and pulled by k3s via the `registries.yaml` mirror endpoint. The `cluster` task pushes prebuilt local tags (`openshell/*:dev`, falling back to `localhost:5000/openshell/*:dev` or `127.0.0.1:5000/openshell/*:dev`).
 
-Gateway image builds stage a partial Rust workspace from `deploy/docker/Dockerfile.images`. If cargo fails with a missing manifest under `/build/crates/...`, or an imported symbol exists locally but is missing in the image build, verify that every current gateway dependency crate is copied into the staged workspace there.
+Gateway image builds stage a partial Rust workspace from `deploy/docker/Dockerfile.images`. If cargo fails with a missing manifest under `/build/crates/...`, or an imported symbol exists locally but is missing in the image build, verify that every current gateway dependency crate, including `openshell-driver-docker`, `openshell-driver-kubernetes`, and `openshell-ocsf`, is copied into the staged workspace there.
 
 For plaintext local evaluation, confirm the chart has:
 

crates/openshell-cli/src/main.rs

@@ -199,7 +199,6 @@ const HELP_TEMPLATE: &str = "\
 \x1b[1mSANDBOX COMMANDS\x1b[0m
   sandbox:     Manage sandboxes
   forward:     Manage port forwarding to a sandbox
-  service:     Forward sandbox services over gRPC
   logs:        View sandbox logs
   policy:      Manage sandbox policy
   settings:    Manage sandbox and global settings
@@ -268,16 +267,11 @@ const FORWARD_EXAMPLES: &str = "\x1b[1mALIAS\x1b[0m
 \x1b[1mEXAMPLES\x1b[0m
   $ openshell forward start 8080
   $ openshell forward start 3000 my-sandbox
+  $ openshell forward service my-sandbox --target-port 8000 --local 8000
   $ openshell forward stop 8080
   $ openshell forward list
 ";
 
-const SERVICE_EXAMPLES: &str = "\x1b[1mEXAMPLES\x1b[0m
-  $ openshell service forward my-sandbox --target-port 8080
-  $ openshell service forward my-sandbox --target-port 5432 --local 15432
-  $ openshell service forward my-sandbox --target-port 3000 --local 127.0.0.1:0
-";
-
 const LOGS_EXAMPLES: &str = "\x1b[1mALIAS\x1b[0m
   lg
 
@@ -415,13 +409,6 @@ enum Commands {
         command: Option<ForwardCommands>,
     },
 
-    /// Forward sandbox services over gRPC.
-    #[command(after_help = SERVICE_EXAMPLES, help_template = SUBCOMMAND_HELP_TEMPLATE)]
-    Service {
-        #[command(subcommand)]
-        command: Option<ServiceCommands>,
-    },
-
     /// View sandbox logs.
     #[command(alias = "lg", after_help = LOGS_EXAMPLES, help_template = LEAF_HELP_TEMPLATE, next_help_heading = "FLAGS")]
     Logs {
@@ -1626,13 +1613,10 @@ enum ForwardCommands {
     /// List active port forwards.
     #[command(help_template = LEAF_HELP_TEMPLATE, next_help_heading = "FLAGS")]
     List,
-}
 
-#[derive(Subcommand, Debug)]
-enum ServiceCommands {
     /// Forward a local TCP port to a loopback service inside a sandbox over gRPC.
     #[command(help_template = LEAF_HELP_TEMPLATE, next_help_heading = "FLAGS")]
-    Forward {
+    Service {
         /// Sandbox name (defaults to last-used sandbox).
         #[arg(add = ArgValueCompleter::new(completers::complete_sandbox_names))]
         name: Option<String>,
@@ -1645,7 +1629,7 @@ enum ServiceCommands {
         #[arg(long, default_value = "127.0.0.1")]
         target_host: String,
 
-        /// Local bind address and port: [bind_address:]port. Use port 0 for dynamic assignment.
+        /// Local bind address and port: [bind_address:]port. Defaults to the target port. Use port 0 for dynamic assignment.
         #[arg(long)]
         local: Option<String>,
     },
@@ -1815,38 +1799,6 @@ async fn main() -> Result<()> {
             }
         }
 
-        Some(Commands::Service {
-            command:
-                Some(ServiceCommands::Forward {
-                    name,
-                    target_port,
-                    target_host,
-                    local,
-                }),
-        }) => {
-            let ctx = resolve_gateway(&cli.gateway, &cli.gateway_endpoint)?;
-            let mut tls = tls.with_gateway_name(&ctx.name);
-            apply_edge_auth(&mut tls, &ctx.name);
-            let name = resolve_sandbox_name(name, &ctx.name)?;
-            run::service_forward_tcp(
-                &ctx.endpoint,
-                &name,
-                local.as_deref(),
-                &target_host,
-                target_port,
-                &tls,
-            )
-            .await?;
-        }
-
-        Some(Commands::Service { command: None }) => {
-            Cli::command()
-                .find_subcommand_mut("service")
-                .expect("service subcommand exists")
-                .print_help()
-                .expect("Failed to print help");
-        }
-
         // -----------------------------------------------------------
         // Top-level forward (was `sandbox forward`)
         // -----------------------------------------------------------
@@ -1923,6 +1875,27 @@ async fn main() -> Result<()> {
                     }
                 }
             }
+            ForwardCommands::Service {
+                name,
+                target_port,
+                target_host,
+                local,
+            } => {
+                let ctx = resolve_gateway(&cli.gateway, &cli.gateway_endpoint)?;
+                let mut tls = tls.with_gateway_name(&ctx.name);
+                apply_auth(&mut tls, &ctx.name);
+                let name = resolve_sandbox_name(name, &ctx.name)?;
+                let local = local.unwrap_or_else(|| target_port.to_string());
+                run::service_forward_tcp(
+                    &ctx.endpoint,
+                    &name,
+                    Some(&local),
+                    &target_host,
+                    target_port,
+                    &tls,
+                )
+                .await?;
+            }
             ForwardCommands::Start {
                 port,
                 name,

crates/openshell-cli/src/run.rs

@@ -26,13 +26,12 @@ use openshell_bootstrap::{
 use openshell_core::proto::ProviderProfileCategory;
 use openshell_core::proto::{
     ApproveAllDraftChunksRequest, ApproveDraftChunkRequest, AttachSandboxProviderRequest,
-    ClearDraftChunksRequest, CreateProviderRequest, CreateSandboxRequest,
-    CreateSshSessionRequest, DeleteProviderProfileRequest, DeleteProviderRequest,
-    DeleteSandboxRequest, DetachSandboxProviderRequest, ExecSandboxRequest,
-    GetClusterInferenceRequest, GetDraftHistoryRequest, GetDraftPolicyRequest,
-    GetGatewayConfigRequest, GetProviderProfileRequest, GetProviderRequest,
-    GetSandboxConfigRequest, GetSandboxLogsRequest, GetSandboxPolicyStatusRequest,
-    GetSandboxRequest, HealthRequest, ImportProviderProfilesRequest,
+    ClearDraftChunksRequest, CreateProviderRequest, CreateSandboxRequest, CreateSshSessionRequest,
+    DeleteProviderProfileRequest, DeleteProviderRequest, DeleteSandboxRequest,
+    DetachSandboxProviderRequest, ExecSandboxRequest, GetClusterInferenceRequest,
+    GetDraftHistoryRequest, GetDraftPolicyRequest, GetGatewayConfigRequest,
+    GetProviderProfileRequest, GetProviderRequest, GetSandboxConfigRequest, GetSandboxLogsRequest,
+    GetSandboxPolicyStatusRequest, GetSandboxRequest, HealthRequest, ImportProviderProfilesRequest,
     LintProviderProfilesRequest, ListProviderProfilesRequest, ListProvidersRequest,
     ListSandboxPoliciesRequest, ListSandboxProvidersRequest, ListSandboxesRequest, PolicySource,
     PolicyStatus, Provider, ProviderProfile, ProviderProfileDiagnostic, ProviderProfileImportItem,

crates/openshell-server/src/grpc/sandbox.rs

@@ -20,8 +20,8 @@ use openshell_core::proto::{
     ExecSandboxRequest, ExecSandboxStderr, ExecSandboxStdout, GetSandboxRequest,
     ListSandboxProvidersRequest, ListSandboxProvidersResponse, ListSandboxesRequest,
     ListSandboxesResponse, Provider, RevokeSshSessionRequest, RevokeSshSessionResponse,
-    SandboxStreamEvent, TcpForwardFrame, TcpForwardInit, TcpRelayTarget, WatchSandboxRequest,
-    relay_open, tcp_forward_init,
+    SandboxResponse, SandboxStreamEvent, TcpForwardFrame, TcpForwardInit, TcpRelayTarget,
+    WatchSandboxRequest, relay_open, tcp_forward_init,
 };
 use openshell_core::proto::{Sandbox, SandboxPhase, SandboxTemplate, SshSession};
 use prost::Message;

docs/sandboxes/manage-sandboxes.mdx

@@ -203,7 +203,7 @@ openshell forward stop 8000 my-sandbox
 Use the gRPC service-forwarding path when you want to test the OS-88 service relay path without SSH port forwarding:
 
 ```shell
-openshell service forward my-sandbox --target-port 8000 --local 8000
+openshell forward service my-sandbox --target-port 8000 --local 8000
 ```
 
 This binds a local listener and opens one authenticated gRPC stream to the gateway for each accepted local TCP connection. The target must be a loopback TCP service inside the sandbox. Use `--local 127.0.0.1:0` to let OpenShell choose a free local port.