From c837b45d8a10937e311f0654129a01db8bc6a71e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 3 Oct 2026 21:16:32 +0000 Subject: [PATCH] docs(website): sync dev docs from a2429fcdcdf3b6e80f185317d3910fd8f84055f6 --- fern/.docs-snapshots.yml | 6 +-- .../how-it-works/gateways/configuration.mdx | 40 +++++++++++-------- .../how-it-works/sandboxes/overview.mdx | 2 + 3 files changed, 29 insertions(+), 19 deletions(-) diff --git a/fern/.docs-snapshots.yml b/fern/.docs-snapshots.yml index 1e361077b..7ed95c1f4 100644 --- a/fern/.docs-snapshots.yml +++ b/fern/.docs-snapshots.yml @@ -1,8 +1,8 @@ snapshots: dev: - source-ref: 4188eabaf2d41fbf94f7d793f411af21b3a4685b - source-sha: 4188eabaf2d41fbf94f7d793f411af21b3a4685b - version: 0.1.3.dev78 + source-ref: a2429fcdcdf3b6e80f185317d3910fd8f84055f6 + source-sha: a2429fcdcdf3b6e80f185317d3910fd8f84055f6 + version: 0.1.3.dev81 latest: source-ref: 6648bd0c290efbc41ba131ee9831ee45cd431f94 source-sha: 6648bd0c290efbc41ba131ee9831ee45cd431f94 diff --git a/fern/pages-dev/how-it-works/gateways/configuration.mdx b/fern/pages-dev/how-it-works/gateways/configuration.mdx index 4cfd902da..52ebbed7f 100644 --- a/fern/pages-dev/how-it-works/gateways/configuration.mdx +++ b/fern/pages-dev/how-it-works/gateways/configuration.mdx @@ -1240,22 +1240,7 @@ changing it: openshell-gateway config preflight --path ~/.config/openshell/gateway.toml ``` -Without `--path`, the command validates a nonempty `OPENSHELL_GATEWAY_CONFIG`. -Otherwise, it validates an existing XDG gateway config when one is discovered. -When neither source selects a config, preflight succeeds. An explicit missing path, -a legacy schema-v1 file, invalid TOML, a symlink, or any nonregular file fails. -Preflight merges the selected file with the current `OPENSHELL_*` environment and -applies the daemon's read-only startup checks. These checks include selector and -socket normalization, registered-driver selection and configuration, rate-limit -pairs, TLS and mTLS relationships, interceptor registrations, and supervisor -middleware registrations. When a selected file omits `compute_driver`, preflight -validates each configured table for an auto-detectable driver without running the -runtime detection probes, which can connect local sockets or launch discovery -commands. It validates complete guest TLS path sets without requiring -package-generated certificates to exist before certificate generation. It does -not construct a compute driver or connect to a transport. A failed -preflight always preserves the file; it never migrates, replaces, or rewrites -configuration. +Without `--path`, the command validates a nonempty `OPENSHELL_GATEWAY_CONFIG`. Otherwise, it validates an existing XDG gateway config when one is discovered. When neither source selects a config, preflight validates the effective daemon arguments. An explicit missing path, a legacy schema-v1 file, invalid TOML, a symlink, or any nonregular file fails. Preflight merges the selected file with the current `OPENSHELL_*` environment and applies the daemon's read-only startup checks. These checks include selector and socket normalization, registered-driver selection and configuration, rate-limit pairs, TLS and mTLS relationships, interceptor registrations, and supervisor middleware registrations. When a selected file omits `compute_driver`, preflight validates each configured table for an auto-detectable driver without running the runtime detection probes, which can connect local sockets or launch discovery commands. It validates configured driver TLS requirements, including the gateway CA, without requiring package-generated certificate files to exist before certificate generation. It does not construct a compute driver or connect to a transport. A failed preflight always preserves the file; it never migrates, replaces, or rewrites configuration. To validate the exact daemon arguments that a wrapper will pass, place them after `--` instead of using `--path`: @@ -1282,3 +1267,26 @@ $EDITOR ~/.config/openshell/gateway.toml openshell-gateway config preflight --path ~/.config/openshell/gateway.toml systemctl --user restart openshell-gateway ``` + +### Check local VM host tools + +For an explicitly selected local `vm` driver, preflight also checks a formatter (`mke2fs` or `mkfs.ext4`), `debugfs`, and `e2fsck`. Install e2fsprogs 1.43 or newer with your operating system's package manager. OpenShell does not install or manage these host dependencies. + +For example, on macOS: + +```shell +brew install e2fsprogs +openshell-gateway config preflight -- --config ~/.config/openshell/gateway.toml --compute-driver vm +``` + +Run preflight with the account, configuration, working directory, and environment intended for the gateway. A successful check in an interactive shell does not check a service with a different `PATH`. For a service whose environment uses a private installation, reproduce its configured path explicitly: + +```shell +env PATH=/opt/company/e2fsprogs/sbin:/opt/company/e2fsprogs/bin:/usr/bin:/bin /usr/local/bin/openshell-gateway config preflight -- --config ~/.config/openshell/gateway.toml --compute-driver vm +``` + +Replace the executable and configuration paths with your installation's paths, and run this command as the service account. Preflight and VM image operations search inherited `PATH` entries, then the existing e2fsprogs `sbin` and `bin` directories under `/opt/homebrew/opt/e2fsprogs` and `/usr/local/opt/e2fsprogs`. They prefer `mke2fs` and try `mkfs.ext4` only when `mke2fs` is absent. A selected file that cannot run is an error; fix that installation or the service's `PATH` before rerunning the command. + +The command reports each selected executable path and version. Each tool receives only `-V`, with a five-second deadline and an 8 KiB output limit per stream. Missing, non-executable, outdated, or failing tools return a nonzero exit status with corrective guidance and the selected tool's error. The checks create no gateway state or images and do not start a driver or VM. Version checks confirm the installation; they do not test image creation or filesystem recovery. + +Other drivers do not require these VM tools. A VM configuration table alone does not select the VM driver. When a remote driver socket is configured, preflight reports that host tool checks were not performed; run the check on that host in the driver service's environment with a local VM configuration. diff --git a/fern/pages-dev/how-it-works/sandboxes/overview.mdx b/fern/pages-dev/how-it-works/sandboxes/overview.mdx index e38f92532..b084590ee 100644 --- a/fern/pages-dev/how-it-works/sandboxes/overview.mdx +++ b/fern/pages-dev/how-it-works/sandboxes/overview.mdx @@ -763,6 +763,8 @@ The dashboard has three panels stacked vertically: Gateways, Providers (or Globa The sandbox table’s NOTES column shows `Invalid config` when policy or provider configuration blocks provisioning. Open the sandbox detail view for the full rejection reason, or run `openshell sandbox get -o json`. The note clears after the configuration is repaired; active port forwards remain listed. +Press `c` in the Sandboxes panel to create a sandbox. In the optional Command field, use quotes or backslashes to group arguments containing spaces. For example, `/bin/sh -c "echo GOOD; read x"` prints `GOOD` and waits for Enter. Invalid quoting keeps the form open without creating a sandbox. The field does not expand variables or evaluate shell operators; invoke a shell explicitly with `sh -c` when you need that behavior. + ## Port Forwarding Forward a local port to a running sandbox to access services inside it, such as a web server or database: