Nabhag8848 · Nov 4, 2026 · Nov 3, 2026 · Nov 3, 2026 · Nov 3, 2026 · Nov 3, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -59,7 +59,8 @@ than regenerating parallel structs. Portable error payloads (`ErrorInfo` /
 classification are handwritten per language.
 
 - Keep portable create and client-config rules in `.proto` (Protovalidate); keep
-  YAML as a human inventory aligned with those annotations.
+  YAML as a human inventory aligned with those annotations. Invent handwritten
+  `ExecOptions` process gates under `ExecOptions` in `specs/validation.yaml`.
 - Document SDK orchestration that remains handwritten.
 - Compare references with the pinned SDK version. Resolve conflicting docs
   explicitly rather than guessing semantics.
@@ -73,9 +74,9 @@ classification are handwritten per language.
 
 For every public feature, update its language's runnable example and guide.
 Use small, independent provider-specific projects under
-`examples/<language>/<provider>/` in `filesystem/`, `configuration/`,
-`lifecycle/`, or `errors/`. Each example demonstrates one operation with its
-own configuration and no provider selector or CLI flags.
+`examples/<language>/<provider>/` in `filesystem/`, `process/`,
+`configuration/`, `lifecycle/`, or `errors/`. Each example demonstrates one
+operation with its own configuration and no provider selector or CLI flags.
 
 Keep examples aligned with the implemented API. Label test doubles and local
 verification limits clearly. Verify changed examples before handoff and update

diff --git a/README.md b/README.md
@@ -43,6 +43,14 @@ await using client = new Client({
 
 const sandbox = await client.create();
 console.log(sandbox.id);
+
+const result = await sandbox.process.run({ argv: ["echo", "hello from kit"] });
+console.log(result.exitCode, new TextDecoder().decode(result.stdout));
+
+await sandbox.filesystem.writeFile(
+  "/tmp/note.txt",
+  new TextEncoder().encode("hello\n"),
+);
 ```
 
 Use `await client.close()` in a `finally` block when `await using` is not
@@ -90,6 +98,18 @@ func main() {
 		panic(err)
 	}
 	fmt.Println(instance.ID())
+
+	result, err := instance.Process().Run(context.Background(), &sandbox.ExecOptions{
+		Argv: []string{"echo", "hello from kit"},
+	})
+	if err != nil {
+		panic(err)
+	}
+	fmt.Println(result.GetExitCode(), string(result.GetStdout()))
+
+	if err := instance.Filesystem().WriteFile(context.Background(), "/tmp/note.txt", []byte("hello\n"), nil); err != nil {
+		panic(err)
+	}
 }
 ```
 
@@ -133,9 +153,10 @@ Modal needs a token pair and an existing app:
 [TypeScript](examples/typescript/modal/configuration/create-modal-sandbox/README.md) ·
 [Go](examples/go/modal/configuration/create-modal-sandbox/README.md).
 
-Creation examples provision real sandboxes. Filesystem and lifecycle examples
+Creation examples provision real sandboxes. Filesystem, process, and lifecycle examples
 use the ID in `.env` (stop / terminate / archive / delete can destroy that
-resource; filesystem examples use the path you set). Error-handling examples
+resource; filesystem examples use the path you set; process examples run one
+command). Error-handling examples
 fail locally and create nothing. Skip copying `.env.example` if you already
 have a configured `.env`.
 
@@ -240,7 +261,7 @@ More detail: [responses and errors](docs/responses-and-errors.md).
 Guides: [configuration](docs/configuration.md) ·
 [creation](docs/sandbox-creation.md) ·
 [lifecycle](docs/sandbox-lifecycle.md) ·
-[filesystem](docs/filesystem.md).
+[filesystem](docs/filesystem.md), and [process](docs/process.md).
 
 ## Documentation
 
@@ -252,20 +273,21 @@ npm install
 npm run dev
 ```
 
-Open http://localhost:3000. Each page covers one part of the client. Code samples switch between TypeScript and Go. GitHub Actions publishes the same site to https://sandbox-kit.github.io/kit/.
+Open http://localhost:3000. Docs are organized as Quickstart, Concepts, Providers, Guides, and Examples. Code samples switch between TypeScript and Go. GitHub Actions publishes the same site to https://sandbox-kit.github.io/kit/.
 
 These pages are the behavior reference for the same API:
 
-| Guide                                                                                                          | Covers                            |
-| -------------------------------------------------------------------------------------------------------------- | --------------------------------- |
-| [Client configuration](docs/configuration.md)                                                                  | Auth, scope, defaults, deadlines  |
-| [Sandbox creation](docs/sandbox-creation.md)                                                                   | Fields, units, policies           |
-| [Sandbox lifecycle](docs/sandbox-lifecycle.md)                                                                 | Get, attach, capabilities         |
-| [Filesystem](docs/filesystem.md)                                                                               | Read, write, copy, list, stat, mkdir, remove |
-| [Providers](docs/providers.md)                                                                                 | Daytona and Modal                 |
-| [Responses and errors](docs/responses-and-errors.md)                                                           | Error details and provider causes |
-| [TS Daytona](sdks/typescript/providers/daytona/README.md) / [Modal](sdks/typescript/providers/modal/README.md) | TypeScript provider notes         |
-| [Go Daytona](sdks/go/providers/daytona/README.md) / [Modal](sdks/go/providers/modal/README.md)                 | Go provider notes                 |
+| Guide                                                                                                          | Covers                                        |
+| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
+| [Client configuration](docs/configuration.md)                                                                  | Auth, scope, defaults, deadlines              |
+| [Sandbox creation](docs/sandbox-creation.md)                                                                   | Fields, units, policies                       |
+| [Sandbox lifecycle](docs/sandbox-lifecycle.md)                                                                 | Get, attach, capabilities                     |
+| [Filesystem](docs/filesystem.md)                                                                               | Read, write, copy, list, stat, mkdir, remove  |
+| [Process](docs/process.md)                                                                                     | Run a command and wait for exit code + output |
+| [Providers](docs/providers.md)                                                                                 | Daytona and Modal                             |
+| [Responses and errors](docs/responses-and-errors.md)                                                           | Error details and provider causes             |
+| [TS Daytona](sdks/typescript/providers/daytona/README.md) / [Modal](sdks/typescript/providers/modal/README.md) | TypeScript provider notes                     |
+| [Go Daytona](sdks/go/providers/daytona/README.md) / [Modal](sdks/go/providers/modal/README.md)                 | Go provider notes                             |
 
 ## License
 

diff --git a/docs/api-declarations.md b/docs/api-declarations.md
@@ -8,26 +8,26 @@ facades; see [protobuf SDK boundary](protobuf-sdk-boundary.md).
 YAML does not declare a parallel public API surface. Remaining specs inventory
 provider rules, validation, and contracts:
 
-| Spec                                          | Role                                            |
-| --------------------------------------------- | ----------------------------------------------- |
-| `specs/providers/*.yaml`                      | Provider mapping/check inventories and bindings |
-| `specs/validation.yaml` / `specs/client.yaml` | Portable create/config validation inventories   |
-| `specs/contracts.yaml`                        | Portable metadata/error contract limits         |
+| Spec                                          | Role                                                                                                          |
+| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `specs/providers/*.yaml`                      | Provider mapping/check inventories and bindings                                                               |
+| `specs/validation.yaml` / `specs/client.yaml` | Create/config Protovalidate inventories; `validation.yaml` also lists handwritten `ExecOptions` process gates |
+| `specs/contracts.yaml`                        | Portable metadata/error contract limits                                                                       |
 
 Error payloads (`ErrorInfo` / `ErrorKind`) live in protobuf. Wrappers and
 provider classification are handwritten per language.
 
 ## Handwritten runtime
 
-- `Client` / `Sandbox` facades, lifecycle dispatch, and `Filesystem`
+- `Client` / `Sandbox` facades, lifecycle dispatch, `Filesystem`, and `Process`
 - TypeScript public create/config input types and materialization to wire
 - Provider selection, native SDK initialization, and cleanup
 - Error wrappers, cause chaining, and provider-native error classification
 - Metadata clone helpers
 - Protovalidate evaluation for shared create/config rules (`secure_endpoint` is
   handwritten)
 - Provider checks, field mappings, and config assembly
-- Path validation and provider filesystem bindings
+- Path validation and provider filesystem / process bindings
 - Provider orchestration that the mapping inventory cannot express
 
 See [Protobuf SDK boundary](protobuf-sdk-boundary.md) and

diff --git a/docs/code-generation.md b/docs/code-generation.md
@@ -57,13 +57,13 @@ the SDK.
 
 ## Inputs
 
-| Input                             | Defines                                                                            |
-| --------------------------------- | ---------------------------------------------------------------------------------- |
-| `proto/kit/sandbox/v1/`           | Public portable types (config, create, lifecycle options, filesystem options, metadata, errors) |
-| `specs/validation.yaml`           | Portable create-validation inventory (mirrors Protovalidate options in proto)      |
-| `specs/client.yaml`               | Config validation inventory (mirrors Protovalidate; `secure_endpoint` handwritten) |
-| `specs/contracts.yaml`            | Metadata/error contract limits                                                     |
-| `specs/providers/<provider>.yaml` | Provider capability, check, mapping, and error-classification inventories          |
+| Input                             | Defines                                                                                                     |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `proto/kit/sandbox/v1/`           | Public portable types (config, create, lifecycle options, filesystem and process options, metadata, errors) |
+| `specs/validation.yaml`           | Create Protovalidate inventory, plus handwritten `ExecOptions` process gates                                |
+| `specs/client.yaml`               | Config validation inventory (mirrors Protovalidate; `secure_endpoint` handwritten)                          |
+| `specs/contracts.yaml`            | Metadata/error contract limits                                                                              |
+| `specs/providers/<provider>.yaml` | Provider capability, check, mapping, and error-classification inventories                                   |
 
 Specs use `version: 1`. Strict loading rejects unknown YAML keys, extra documents,
 and unsupported versions. Shared fields use protobuf names; SDK symbols belong
@@ -141,6 +141,9 @@ Shared create and client-config validation is declared as Protovalidate options
 on `proto/` messages and evaluated in each SDK (`ValidateCreateOptions` /
 `ValidateConfig`). Keep `specs/validation.yaml` and `specs/client.yaml` aligned
 with those annotations. The `secure_endpoint` config check is handwritten.
+`ExecOptions` process rules (argv XOR shell, blank shell, absolute working
+directory, whole-second provider timeouts) are handwritten in `Process.Run` and
+provider adapters; inventory them under `ExecOptions` in `validation.yaml`.
 Both languages preserve explicit zero/false and supply no defaults.
 
 ## Provider checks
@@ -251,18 +254,20 @@ Backend state capture and metadata cloning are handwritten in the SDK runtime
 
 SDK orchestration that the inventory cannot express stays in handwritten
 provider integration files (Go `sandbox.go`, `creation.go`, `filesystem.go`,
+`process.go`,
 and, where the provider observes native state, `lifecycle.go` and
 `metadata.go`; TypeScript provider-named `.ts` plus `mappings.ts` files):
-lookup sequences, source selection, readiness, filesystem bindings, and
-remaining provider semantics. Handwritten `provider_mappings` /
+lookup sequences, source selection, readiness, filesystem and process bindings,
+and remaining provider semantics. Handwritten `provider_mappings` /
 `provider_config` own field conversions and native client configuration;
 handwritten `provider_checks` enforces create checks; handwritten `errors`
 classifies native provider errors.
 
-Lifecycle and filesystem option and result types come from protobuf contracts.
-Handle methods, typed provider dispatch, lifecycle capability discovery,
-filesystem backend methods, and close coordination remain handwritten runtime
-code on `Client`, `Sandbox` / `Filesystem`, and provider `Backend` adapters.
+Lifecycle, filesystem, and process option and result types come from protobuf
+contracts. Handle methods, typed provider dispatch, lifecycle capability
+discovery, filesystem and process backend methods, and close coordination
+remain handwritten runtime code on `Client`, `Sandbox` / `Filesystem` /
+`Process`, and provider `Backend` adapters.
 
 See [tooling](../tooling/README.md), [naming](naming.md), and
 [reference verification](provider-verification.md).
diff --git a/docs/filesystem.md b/docs/filesystem.md
@@ -15,8 +15,10 @@ Modal `Attach`, then call `Filesystem` / `sandbox.filesystem`.
 | Read metadata for one path    | `Stat`          | `stat`          |
 | Delete a file or directory    | `Remove`        | `remove`        |
 
-Calls on one handle run one at a time, including lifecycle calls. A second
-handle for the same sandbox does not wait.
+Calls on one handle run one at a time, including lifecycle and process. A
+second handle for the same sandbox does not wait. Abort or deadline rejects the
+TypeScript `await` (and ends the Go wait), but the handle stays busy until that
+provider call settles so the next call does not overlap it.
 
 ## Paths