@@ -70,7 +70,9 @@ The simplest way to get a sandbox running:
 openshell sandbox create
 ```
 
-This creates a sandbox with defaults and drops you into an interactive shell.
+This creates a sandbox whose canonical main process is `/bin/bash -l` and
+attaches your terminal to that retained process. Add `--detach` to return after
+the sandbox becomes ready without attaching.
 
 When supplying `--name`, use a portable DNS-1123 label: at most 63 lowercase alphanumeric or `-` characters, beginning and ending with an alphanumeric character. The Kubernetes driver rejects uppercase letters, underscores, dots, and other names that cannot become Kubernetes resource labels.
 
@@ -234,9 +236,14 @@ Key flags:
 - `--upload <PATH>[:<DEST>]`: Upload local files into the container working directory or an explicit destination
 - `--no-git-ignore`: Disable `.gitignore` filtering for uploads
 - `--no-keep`: Delete the sandbox after the initial command or shell exits
+- `--detach`: Start the canonical main process without attaching
 - `--forward [BIND_ADDRESS:]PORT`: Forward a local port and keep the sandbox alive
 - `--editor vscode|cursor`: Open a remote editor after creation and keep the sandbox alive
 
+Do not combine `--upload` with a trailing main command. Uploads currently finish
+after the canonical process starts; create a scratch sandbox and use
+`sandbox exec`, or build the files into the image.
+
 ### List and inspect sandboxes
 
 ```bash
@@ -254,7 +261,10 @@ openshell sandbox connect my-sandbox
 openshell sandbox connect my-sandbox --editor vscode
 ```
 
-Opens an interactive SSH shell. To configure VS Code Remote-SSH:
+Attaches to the sandbox's existing canonical main process. Disconnecting leaves
+that process running; reconnecting targets the same generation and replays
+recent output. Use `sandbox exec --tty -- /bin/bash -l` for a new shell. To
+configure VS Code Remote-SSH:
 
 ```bash
 openshell sandbox ssh-config my-sandbox >> ~/.ssh/config
@@ -287,7 +297,9 @@ openshell sandbox exec --name my-sandbox --workdir /workspace -- ls -la
 openshell sandbox exec --name my-sandbox --env MODE=test -- cargo test
 ```
 
-`sandbox exec` streams output and exits with the remote command's exit code. Use `sandbox connect` for an interactive shell.
+`sandbox exec` starts an independent sibling process, streams output, and exits
+with the remote command's exit code. Use `sandbox connect` to attach to the
+canonical main process.
 Use `--env` only for non-secret values. Attach credentials to the sandbox with a
 provider instead of passing API keys, tokens, or other secrets to `sandbox exec`.
 
 
@@ -13,6 +13,8 @@ Each runtime receives a sandbox spec from the gateway and is responsible for:
 - Injecting sandbox identity and gateway callback configuration.
 - Supplying TLS or secret material for supervisor callbacks.
 - Providing the supervisor binary or image in the workload.
+- Forwarding the exact canonical main-process argv, environment, working
+  directory, and terminal mode without shell reconstruction.
 - Reporting lifecycle and platform events back to the gateway.
 - Cleaning up runtime-owned resources.
 
 
@@ -15,11 +15,17 @@ workloads.
 - Resolve provider credentials and inference bundles for sandbox supervisors.
 - Coordinate supervisor relay sessions for connect, exec, file sync, and
   service forwarding.
+- Persist the canonical main-process generation and terminal result. Any main
+  process exit transitions the sandbox to `Error`, including exit code zero.
 
 The gateway does not enforce agent network policy at request time. That happens
 inside each sandbox, where the supervisor and proxy can observe local process
 identity.
 
+The live supervisor session is the readiness authority for its main-process
+generation. Short-lived exit-report sessions never replace that session or
+mark the sandbox ready, and the gateway rejects stale generation results.
+
 ## Protocol and Auth
 
 The gateway listens on one service port and multiplexes gRPC and HTTP traffic.
 
@@ -29,10 +29,11 @@ only when the set is already empty; any other outcome fails the spawn.
    gateway, depending on mode.
 3. It prepares filesystem access, process restrictions, network namespace
    routing, trust stores, provider credential resolution, and inference routes.
-4. It starts the policy proxy and local SSH server.
-5. It opens a supervisor session back to the gateway for connect, exec, file
+4. It launches the persisted canonical main-process argv and retains its PTY
+   or pipes in the main-session multiplexer.
+5. It starts the policy proxy and local SSH server.
+6. It opens a supervisor session back to the gateway for connect, exec, file
    sync, config polling, and log push.
-6. It launches the agent command as the resolved restricted identity.
 
 ## Isolation Layers
 
@@ -359,8 +360,10 @@ The supervisor runs an SSH server on a Unix socket inside the sandbox. The
 gateway reaches it through the outbound supervisor relay, not by dialing the
 sandbox workload directly. The relay supports:
 
-- Interactive shell sessions.
-- Command execution.
+- Attachment to the canonical main process through the `openshell-main` SSH
+  subsystem. The supervisor owns its retained PTY or pipes, a 1 MiB replay
+  buffer, and a single stdin lease across client disconnects.
+- Independent shell and command execution sessions.
 - Tar-based file sync.
 - Port forwarding where supported by the CLI/TUI surface.
 
@@ -436,3 +439,7 @@ engine with a gateway policy revision.
   re-evaluate.
 - If the supervisor relay drops, the sandbox can keep running, but connect and
   exec operations fail until the supervisor registers again.
+- If the canonical main process exits, including with code 0, the supervisor
+  reports its result before shutdown. The gateway persists `MainProcessExited`
+  and makes the sandbox terminal `Error`; runtime restart policies must not
+  replace the process generation.
@@ -1351,7 +1351,12 @@ enum SandboxCommands {
         /// working directory.
         /// `.gitignore` rules are applied by default; use `--no-git-ignore` to
         /// upload everything.
-        #[arg(long, value_hint = ValueHint::AnyPath, help_heading = "UPLOAD FLAGS")]
+        #[arg(
+            long,
+            value_hint = ValueHint::AnyPath,
+            help_heading = "UPLOAD FLAGS",
+            conflicts_with = "command"
+        )]
         upload: Vec<String>,
 
         /// Disable `.gitignore` filtering for `--upload`.
@@ -1421,6 +1426,10 @@ enum SandboxCommands {
         #[arg(long, overrides_with = "tty")]
         no_tty: bool,
 
+        /// Start the canonical main process without attaching to it.
+        #[arg(long, conflicts_with_all = ["editor", "no_keep"])]
+        detach: bool,
+
         /// Auto-create missing providers from local credentials.
         ///
         /// Without this flag, an interactive prompt asks per-provider;
@@ -2980,6 +2989,7 @@ async fn run_async() -> Result<()> {
                     forward,
                     tty,
                     no_tty,
+                    detach,
                     auto_providers,
                     no_auto_providers,
                     labels,
@@ -3075,6 +3085,7 @@ async fn run_async() -> Result<()> {
                             environment: env_map,
                             approval_mode: &approval_mode,
                             output: output.as_str(),
+                            detach,
                         },
                         &cli.workspace,
                         &tls,
@@ -5128,6 +5139,55 @@ mod tests {
         }
     }
 
+    #[test]
+    fn sandbox_create_detach_parses_with_main_command() {
+        let cli = Cli::try_parse_from([
+            "openshell",
+            "sandbox",
+            "create",
+            "--detach",
+            "--",
+            "worker",
+            "--serve",
+        ])
+        .expect("sandbox create --detach should parse");
+
+        match cli.command {
+            Some(Commands::Sandbox {
+                command:
+                    Some(SandboxCommands::Create {
+                        detach, command, ..
+                    }),
+                ..
+            }) => {
+                assert!(detach);
+                assert_eq!(command, ["worker", "--serve"]);
+            }
+            other => panic!("expected SandboxCommands::Create, got: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn sandbox_create_detach_rejects_ephemeral_sandbox() {
+        let result =
+            Cli::try_parse_from(["openshell", "sandbox", "create", "--detach", "--no-keep"]);
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn sandbox_create_rejects_upload_with_main_command() {
+        let result = Cli::try_parse_from([
+            "openshell",
+            "sandbox",
+            "create",
+            "--upload",
+            ".",
+            "--",
+            "./run-uploaded-app",
+        ]);
+        assert!(result.is_err());
+    }
+
     /// `sandbox create` defaults `--approval-mode` to `"manual"`. The CLI
     /// always sends an explicit value so the wire form is human-readable
     /// (the gateway treats `""` as `"manual"` too, but the CLI's job is to
 
@@ -383,6 +383,7 @@ pub struct SandboxCreateConfig<'a> {
     pub environment: HashMap<String, String>,
     pub approval_mode: &'a str,
     pub output: &'a str,
+    pub detach: bool,
 }
 
 impl Default for SandboxCreateConfig<'_> {
@@ -407,6 +408,7 @@ impl Default for SandboxCreateConfig<'_> {
             environment: HashMap::new(),
             approval_mode: "manual",
             output: "table",
+            detach: false,
         }
     }
 }
@@ -439,13 +441,19 @@ pub async fn sandbox_create(
         environment,
         approval_mode,
         output,
+        detach,
     } = config;
 
     if editor.is_some() && !command.is_empty() {
         return Err(miette::miette!(
             "--editor cannot be used with a trailing command; use `openshell sandbox connect <name> --editor ...` after the sandbox is ready"
         ));
     }
+    if !uploads.is_empty() && !command.is_empty() {
+        return Err(miette::miette!(
+            "--upload cannot be combined with a trailing main command yet because uploads complete after the canonical process starts"
+        ));
+    }
 
     // Check port availability *before* creating the sandbox so we don't
     // leave an orphaned sandbox behind when the forward would fail.
@@ -521,13 +529,25 @@ pub async fn sandbox_create(
 
     let resource_requirements = gpu_requirements.map(|gpu| ResourceRequirements { gpu: Some(gpu) });
 
+    let main_terminal = tty_override
+        .unwrap_or_else(|| std::io::stdin().is_terminal() && std::io::stdout().is_terminal());
+    let main_command = if command.is_empty() {
+        vec!["/bin/bash".to_string(), "-l".to_string()]
+    } else {
+        command.to_vec()
+    };
     let request = CreateSandboxRequest {
         spec: Some(SandboxSpec {
             resource_requirements,
             environment,
             policy,
             providers: configured_providers,
             template,
+            main_process: Some(openshell_core::proto::MainProcessSpec {
+                command: main_command,
+                terminal: main_terminal,
+                ..Default::default()
+            }),
             ..SandboxSpec::default()
         }),
         name: name.unwrap_or_default().to_string(),
@@ -939,53 +959,23 @@ pub async fn sandbox_create(
                 return Ok(());
             }
 
-            if command.is_empty() {
-                let connect_result = if persist {
-                    sandbox_connect(&effective_server, &sandbox_name, &effective_tls, workspace)
-                        .await
-                } else {
-                    crate::ssh::sandbox_connect_without_exec(
-                        &effective_server,
-                        &sandbox_name,
-                        &effective_tls,
-                        workspace,
-                    )
-                    .await
-                };
-
-                return finalize_sandbox_create_session(
-                    &effective_server,
-                    &sandbox_name,
-                    persist,
-                    connect_result,
-                    workspace,
-                    &effective_tls,
-                    gateway_name,
-                )
-                .await;
+            // Persistent non-interactive creates detach implicitly. An
+            // explicitly ephemeral (`--no-keep`) create must still attach so
+            // it can observe the canonical process and delete the sandbox when
+            // that session ends.
+            if detach
+                || (persist
+                    && (!std::io::stdin().is_terminal() || !std::io::stdout().is_terminal()))
+            {
+                return Ok(());
             }
 
-            // Resolve TTY mode: explicit --tty / --no-tty wins, otherwise
-            // auto-detect from the local terminal.
-            let tty = tty_override.unwrap_or_else(|| {
-                std::io::stdin().is_terminal() && std::io::stdout().is_terminal()
-            });
-            let exec_result = if persist {
-                sandbox_exec(
-                    &effective_server,
-                    &sandbox_name,
-                    command,
-                    tty,
-                    &effective_tls,
-                    workspace,
-                )
-                .await
+            let connect_result = if persist {
+                sandbox_connect(&effective_server, &sandbox_name, &effective_tls, workspace).await
             } else {
-                crate::ssh::sandbox_exec_without_exec(
+                crate::ssh::sandbox_connect_without_exec(
                     &effective_server,
                     &sandbox_name,
-                    command,
-                    tty,
                     &effective_tls,
                     workspace,
                 )
@@ -996,15 +986,17 @@ pub async fn sandbox_create(
                 &effective_server,
                 &sandbox_name,
                 persist,
-                exec_result,
+                connect_result,
                 workspace,
                 &effective_tls,
                 gateway_name,
             )
             .await
         }
         SandboxPhase::Error => {
-            if last_error_reason.is_empty() {
+            drop(stream);
+            drop(client);
+            let create_result = if last_error_reason.is_empty() {
                 Err(miette::miette!(
                     "sandbox entered error phase while provisioning"
                 ))
@@ -1013,7 +1005,17 @@ pub async fn sandbox_create(
                     "sandbox entered error phase while provisioning: {}",
                     last_error_reason
                 ))
-            }
+            };
+            finalize_sandbox_create_session(
+                &effective_server,
+                &sandbox_name,
+                persist,
+                create_result,
+                workspace,
+                &effective_tls,
+                gateway_name,
+            )
+            .await
         }
         _ => Err(miette::miette!(
             "sandbox provisioning stream ended before reaching terminal phase"