Skip to content

Commit 2fef0b9

Browse files
committed
chore(driver-mxc): merge canonical main process
Signed-off-by: Shailendra Singh <shailendras@nvidia.com>
2 parents 7b43a98 + ef29680 commit 2fef0b9

69 files changed

Lines changed: 3800 additions & 821 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/openshell-cli/SKILL.md‎

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,9 @@ The simplest way to get a sandbox running:
7070
openshell sandbox create
7171
```
7272

73-
This creates a sandbox with defaults and drops you into an interactive shell.
73+
This creates a sandbox whose canonical main process is `/bin/bash -l` and
74+
attaches your terminal to that retained process. Add `--detach` to return after
75+
the sandbox becomes ready without attaching.
7476

7577
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.
7678

@@ -230,13 +232,19 @@ Key flags:
230232
- `--driver-config-json`: Pass experimental driver-specific sandbox configuration
231233
- `--label KEY=VALUE`: Add labels for later selection (repeatable)
232234
- `--env KEY=VALUE`: Set non-secret sandbox environment variables (repeatable); use `--provider` for credentials
235+
- `--tty`: Allocate a retained PTY for the canonical main process
233236
- `--approval-mode manual|auto`: Control handling of agent-authored policy proposals; `manual` is the default
234237
- `--upload <PATH>[:<DEST>]`: Upload local files into the container working directory or an explicit destination
235238
- `--no-git-ignore`: Disable `.gitignore` filtering for uploads
236239
- `--no-keep`: Delete the sandbox after the initial command or shell exits
240+
- `--detach`: Start the canonical main process without attaching
237241
- `--forward [BIND_ADDRESS:]PORT`: Forward a local port and keep the sandbox alive
238242
- `--editor vscode|cursor`: Open a remote editor after creation and keep the sandbox alive
239243

244+
Do not combine `--upload` with a trailing main command. Uploads currently finish
245+
after the canonical process starts; create a scratch sandbox and use
246+
`sandbox exec`, or build the files into the image.
247+
240248
### List and inspect sandboxes
241249

242250
```bash
@@ -254,7 +262,12 @@ openshell sandbox connect my-sandbox
254262
openshell sandbox connect my-sandbox --editor vscode
255263
```
256264

257-
Opens an interactive SSH shell. To configure VS Code Remote-SSH:
265+
Attaches to the sandbox's existing canonical main process. Disconnecting leaves
266+
that process running; reconnecting targets the same process instance and replays
267+
recent output. Use `sandbox exec --tty -- /bin/bash -l` for a new shell. Press
268+
`Ctrl-P`, then `Ctrl-Q` to disconnect without terminating main. `Ctrl-C` retains
269+
its normal terminal behavior and interrupts the foreground process. Configure
270+
VS Code Remote-SSH with:
258271

259272
```bash
260273
openshell sandbox ssh-config my-sandbox >> ~/.ssh/config
@@ -287,7 +300,9 @@ openshell sandbox exec --name my-sandbox --workdir /workspace -- ls -la
287300
openshell sandbox exec --name my-sandbox --env MODE=test -- cargo test
288301
```
289302

290-
`sandbox exec` streams output and exits with the remote command's exit code. Use `sandbox connect` for an interactive shell.
303+
`sandbox exec` starts an independent sibling process, streams output, and exits
304+
with the remote command's exit code. Use `sandbox connect` to attach to the
305+
canonical main process.
291306
Use `--env` only for non-secret values. Attach credentials to the sandbox with a
292307
provider instead of passing API keys, tokens, or other secrets to `sandbox exec`.
293308

‎.agents/skills/openshell-cli/cli-reference.md‎

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -204,13 +204,17 @@ identity provider. Requires an authenticated gateway connection.
204204

205205
### `openshell sandbox create [OPTIONS] [-- COMMAND...]`
206206

207-
Create a sandbox through the selected gateway, wait for readiness, then connect, open an editor, or execute the trailing command.
207+
Create a sandbox through the selected gateway and launch its canonical main
208+
process. By default, the CLI attaches to that retained process after the
209+
sandbox becomes ready. A trailing command defines the canonical main process;
210+
without one, the default is `/bin/bash -l` with a PTY.
208211

209212
| Flag | Description |
210213
|------|-------------|
211214
| `--name <NAME>` | Sandbox name (auto-generated if omitted) |
212215
| `--from <SOURCE>` | Community name, Dockerfile path, directory, or image reference (BYOC) |
213216
| `--no-keep` | Delete the sandbox after the initial command or shell exits |
217+
| `--detach` | Start the canonical main process without attaching |
214218
| `--editor vscode|cursor` | Launch a remote editor and keep the sandbox alive |
215219
| `--gpu [COUNT]` | Request the driver's default GPU selection or a specific count |
216220
| `--cpu <QUANTITY>` | CPU limit (for example: `500m`, `1`, `2.5`) |
@@ -227,7 +231,12 @@ Create a sandbox through the selected gateway, wait for readiness, then connect,
227231
| `--approval-mode manual|auto` | Handle agent-authored policy proposals; default: `manual` |
228232
| `--upload <PATH>[:<DEST>]` | Upload local files to the working directory or an explicit destination (repeatable) |
229233
| `--no-git-ignore` | Disable `.gitignore` filtering for `--upload` |
230-
| `[-- COMMAND...]` | Initial command (defaults to an interactive shell) |
234+
| `[-- COMMAND...]` | Canonical main command (defaults to `/bin/bash -l`) |
235+
236+
`--upload` cannot be combined with a trailing main command because uploads
237+
currently complete after the canonical process starts. Create the default
238+
scratch sandbox, upload files, then use `sandbox exec`, or build the files into
239+
the image.
231240

232241
### `openshell sandbox get [name]`
233242

@@ -277,7 +286,13 @@ Execute a command through the gRPC exec endpoint, stream its output, and exit wi
277286

278287
### `openshell sandbox connect [name]`
279288

280-
Open an interactive SSH shell. The name defaults to the last-used sandbox. `--editor vscode|cursor` launches a supported remote editor instead.
289+
Attach to the sandbox's retained canonical main process. Disconnecting leaves
290+
the process running. Reconnecting targets the same process instance and
291+
replays recent output. Use `sandbox exec --tty -- /bin/bash -l` when you need a
292+
new shell. The name defaults to the last-used sandbox.
293+
294+
`--editor vscode|cursor` launches a supported remote editor instead of
295+
attaching to the canonical main process.
281296

282297
### `openshell sandbox upload <name> <path> [dest]`
283298

‎Cargo.lock‎

Lines changed: 2 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎architecture/compute-runtimes.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,9 @@ Each runtime receives a sandbox spec from the gateway and is responsible for:
1313
- Injecting sandbox identity and gateway callback configuration.
1414
- Supplying TLS or secret material for supervisor callbacks.
1515
- Providing the supervisor binary or image in the workload.
16+
- Forwarding the exact canonical main-process argv and TTY mode without shell
17+
reconstruction. The sandbox-level environment and policy workspace apply to
18+
the main process.
1619
- Reporting lifecycle and platform events back to the gateway.
1720
- Cleaning up runtime-owned resources.
1821

@@ -30,6 +33,10 @@ Process-identity omissions are preserved across this boundary so every driver
3033
can apply its native image or runtime defaults. Driver-requested listeners are
3134
structurally validated and remain restricted to sandbox callback RPCs.
3235

36+
Canonical main-process support is part of the `ComputeDriver` contract. Every
37+
in-tree and extension driver must forward the exact specification; it is not an
38+
optional capability that drivers can omit or negotiate.
39+
3340
Drivers own runtime-specific platform event interpretation. When an event should
3441
drive client provisioning UI, the driver attaches the shared
3542
`openshell.progress.*` metadata defined in `openshell-core` instead of requiring

‎architecture/gateway.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,19 @@ workloads.
1515
- Resolve provider credentials and inference bundles for sandbox supervisors.
1616
- Coordinate supervisor relay sessions for connect, exec, file sync, and
1717
service forwarding.
18+
- Persist the canonical main-process instance ID and normalized exit code on
19+
sandbox status. Any main process exit transitions the sandbox to `Error`,
20+
including exit code zero.
1821

1922
The gateway does not enforce agent network policy at request time. That happens
2023
inside each sandbox, where the supervisor and proxy can observe local process
2124
identity.
2225

26+
The live supervisor session is the readiness authority for its main-process
27+
instance. The supervisor reports its normalized result through the
28+
sandbox-authenticated `ReportMainProcessExit` RPC, and the gateway rejects
29+
results from stale instance IDs.
30+
2331
## Protocol and Auth
2432

2533
The gateway listens on one service port and multiplexes gRPC and HTTP traffic.

‎architecture/sandbox.md‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -29,10 +29,11 @@ only when the set is already empty; any other outcome fails the spawn.
2929
gateway, depending on mode.
3030
3. It prepares filesystem access, process restrictions, network namespace
3131
routing, trust stores, provider credential resolution, and inference routes.
32-
4. It starts the policy proxy and local SSH server.
33-
5. It opens a supervisor session back to the gateway for connect, exec, file
32+
4. It launches the persisted canonical main-process argv and retains its PTY
33+
or pipes in the main-session multiplexer.
34+
5. It starts the policy proxy and local SSH server.
35+
6. It opens a supervisor session back to the gateway for connect, exec, file
3436
sync, config polling, and log push.
35-
6. It launches the agent command as the resolved restricted identity.
3637

3738
## Isolation Layers
3839

@@ -359,8 +360,10 @@ The supervisor runs an SSH server on a Unix socket inside the sandbox. The
359360
gateway reaches it through the outbound supervisor relay, not by dialing the
360361
sandbox workload directly. The relay supports:
361362

362-
- Interactive shell sessions.
363-
- Command execution.
363+
- Attachment to the canonical main process through the `openshell-main` SSH
364+
subsystem. The supervisor owns its retained PTY or pipes, a 1 MiB replay
365+
buffer, and a single stdin lease across client disconnects.
366+
- Independent shell and command execution sessions.
364367
- Tar-based file sync.
365368
- Port forwarding where supported by the CLI/TUI surface.
366369

@@ -436,3 +439,7 @@ engine with a gateway policy revision.
436439
re-evaluate.
437440
- If the supervisor relay drops, the sandbox can keep running, but connect and
438441
exec operations fail until the supervisor registers again.
442+
- If the canonical main process exits, including with code 0, the supervisor
443+
reports its normalized exit code before shutdown. The gateway persists the
444+
code on sandbox status, records `MainProcessExited`, and makes the sandbox
445+
terminal `Error`; runtime restart policies must not replace the process.

‎crates/openshell-cli/src/main.rs‎

Lines changed: 62 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1351,7 +1351,12 @@ enum SandboxCommands {
13511351
/// working directory.
13521352
/// `.gitignore` rules are applied by default; use `--no-git-ignore` to
13531353
/// upload everything.
1354-
#[arg(long, value_hint = ValueHint::AnyPath, help_heading = "UPLOAD FLAGS")]
1354+
#[arg(
1355+
long,
1356+
value_hint = ValueHint::AnyPath,
1357+
help_heading = "UPLOAD FLAGS",
1358+
conflicts_with = "command"
1359+
)]
13551360
upload: Vec<String>,
13561361

13571362
/// Disable `.gitignore` filtering for `--upload`.
@@ -1421,6 +1426,10 @@ enum SandboxCommands {
14211426
#[arg(long, overrides_with = "tty")]
14221427
no_tty: bool,
14231428

1429+
/// Start the canonical main process without attaching to it.
1430+
#[arg(long, conflicts_with_all = ["editor", "no_keep"])]
1431+
detach: bool,
1432+
14241433
/// Auto-create missing providers from local credentials.
14251434
///
14261435
/// Without this flag, an interactive prompt asks per-provider;
@@ -1594,6 +1603,7 @@ enum SandboxCommands {
15941603
/// Connect to a sandbox.
15951604
///
15961605
/// When no name is given, reconnects to the last-used sandbox.
1606+
/// Press Ctrl-P Ctrl-Q to disconnect without terminating the main process.
15971607
#[command(help_template = LEAF_HELP_TEMPLATE, next_help_heading = "FLAGS")]
15981608
Connect {
15991609
/// Sandbox name (defaults to last-used sandbox).
@@ -2980,6 +2990,7 @@ async fn run_async() -> Result<()> {
29802990
forward,
29812991
tty,
29822992
no_tty,
2993+
detach,
29832994
auto_providers,
29842995
no_auto_providers,
29852996
labels,
@@ -3075,6 +3086,7 @@ async fn run_async() -> Result<()> {
30753086
environment: env_map,
30763087
approval_mode: &approval_mode,
30773088
output: output.as_str(),
3089+
detach,
30783090
},
30793091
&cli.workspace,
30803092
&tls,
@@ -5128,6 +5140,55 @@ mod tests {
51285140
}
51295141
}
51305142

5143+
#[test]
5144+
fn sandbox_create_detach_parses_with_main_command() {
5145+
let cli = Cli::try_parse_from([
5146+
"openshell",
5147+
"sandbox",
5148+
"create",
5149+
"--detach",
5150+
"--",
5151+
"worker",
5152+
"--serve",
5153+
])
5154+
.expect("sandbox create --detach should parse");
5155+
5156+
match cli.command {
5157+
Some(Commands::Sandbox {
5158+
command:
5159+
Some(SandboxCommands::Create {
5160+
detach, command, ..
5161+
}),
5162+
..
5163+
}) => {
5164+
assert!(detach);
5165+
assert_eq!(command, ["worker", "--serve"]);
5166+
}
5167+
other => panic!("expected SandboxCommands::Create, got: {other:?}"),
5168+
}
5169+
}
5170+
5171+
#[test]
5172+
fn sandbox_create_detach_rejects_ephemeral_sandbox() {
5173+
let result =
5174+
Cli::try_parse_from(["openshell", "sandbox", "create", "--detach", "--no-keep"]);
5175+
assert!(result.is_err());
5176+
}
5177+
5178+
#[test]
5179+
fn sandbox_create_rejects_upload_with_main_command() {
5180+
let result = Cli::try_parse_from([
5181+
"openshell",
5182+
"sandbox",
5183+
"create",
5184+
"--upload",
5185+
".",
5186+
"--",
5187+
"./run-uploaded-app",
5188+
]);
5189+
assert!(result.is_err());
5190+
}
5191+
51315192
/// `sandbox create` defaults `--approval-mode` to `"manual"`. The CLI
51325193
/// always sends an explicit value so the wire form is human-readable
51335194
/// (the gateway treats `""` as `"manual"` too, but the CLI's job is to

0 commit comments

Comments
 (0)