From 5f455ecc670fbd0aaa3492ad698f0bc3a5c3cb7a Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 16 Oct 2026 09:00:00 +0000 Subject: [PATCH] docs(website): sync dev docs from a4c848adbddd0b4732fd70ddcf8a563a5b1e9317 --- fern/.docs-snapshots.yml | 6 ++-- .../how-it-works/gateways/configuration.mdx | 5 ++++ .../how-it-works/sandboxes/overview.mdx | 12 ++++---- .../how-it-works/sandboxes/runtimes.mdx | 30 +++++++++++++++++++ 4 files changed, 43 insertions(+), 10 deletions(-) diff --git a/fern/.docs-snapshots.yml b/fern/.docs-snapshots.yml index 3324ebb4e..1fe16654b 100644 --- a/fern/.docs-snapshots.yml +++ b/fern/.docs-snapshots.yml @@ -1,8 +1,8 @@ snapshots: dev: - source-ref: b2069a267c7c8c7cb9a8b652792167dab886cd83 - source-sha: b2069a267c7c8c7cb9a8b652792167dab886cd83 - version: 0.1.5.dev47 + source-ref: a4c848adbddd0b4732fd70ddcf8a563a5b1e9317 + source-sha: a4c848adbddd0b4732fd70ddcf8a563a5b1e9317 + version: 0.1.5.dev49 latest: source-ref: 5a7728c304b5528e954e9ae900cf21f84e1a12b1 source-sha: 5a7728c304b5528e954e9ae900cf21f84e1a12b1 diff --git a/fern/pages-dev/how-it-works/gateways/configuration.mdx b/fern/pages-dev/how-it-works/gateways/configuration.mdx index fdcc90833..aab1204eb 100644 --- a/fern/pages-dev/how-it-works/gateways/configuration.mdx +++ b/fern/pages-dev/how-it-works/gateways/configuration.mdx @@ -1406,6 +1406,11 @@ overlay_disk_mib = 4096 # the exposure; host-only sockets are never exposed automatically. # provider_spiffe_workload_api_tcp_endpoint = "tcp:192.0.2.10:8081" # provider_spiffe_allow_guest_tcp = true +# Unsafe operator override. Host bind mounts expose gateway-host paths inside +# VM sandboxes and can negate OpenShell isolation and filesystem controls. +# Requires allow_driver_config = true and +# [openshell.drivers.vm.resource_admission] enabled = false; libkrun only. +# enable_bind_mounts = false # Where the gateway stages rootfs tar archives for `--from ./rootfs.tar`. # Defaults to /rootfs-tar-staging. The gateway creates one # request-scoped subdirectory per staging slot and removes it after use. diff --git a/fern/pages-dev/how-it-works/sandboxes/overview.mdx b/fern/pages-dev/how-it-works/sandboxes/overview.mdx index 45938d22e..bebf52598 100644 --- a/fern/pages-dev/how-it-works/sandboxes/overview.mdx +++ b/fern/pages-dev/how-it-works/sandboxes/overview.mdx @@ -539,13 +539,11 @@ console.log(sandbox.serviceUrls['']) ```go sandbox, err := client.Sandboxes().Create( - ctx, "default", "app-server", spec, nil, - v1.CreateOptions{ServiceExposures: []v1.ServiceExposure{ - { - TargetPort: 4500, - AuthorizationMode: v1.ServiceAuthorizationModeBearerPassthrough, - }, - }}, + ctx, "default", "app-server", spec, + v1.WithServiceExposures(v1.ServiceExposure{ + TargetPort: 4500, + AuthorizationMode: v1.ServiceAuthorizationModeBearerPassthrough, + }), ) fmt.Println(sandbox.ServiceURLs[""]) ``` diff --git a/fern/pages-dev/how-it-works/sandboxes/runtimes.mdx b/fern/pages-dev/how-it-works/sandboxes/runtimes.mdx index 1dd5f920b..89ec2c8d4 100644 --- a/fern/pages-dev/how-it-works/sandboxes/runtimes.mdx +++ b/fern/pages-dev/how-it-works/sandboxes/runtimes.mdx @@ -238,6 +238,36 @@ VM sandboxes have no network interface. All traffic flows through the OpenShell If the gateway is briefly unavailable while a VM starts, its supervisor retries the session connection. The sandbox stays in provisioning until the gateway accepts the session. +### MicroVM Mounts + +The VM driver shares gateway-host directories into the guest with virtiofs. Each entry in `mounts` takes `source` (absolute host directory), `target`, optional `read_only` (default `true`), and optional `type`, which must be `bind` so Docker and Podman bind entries work unchanged: + +```shell +openshell sandbox create \ + --driver-config-json '{"vm":{"mounts":[{"type":"bind","source":"/srv/datasets","target":"/sandbox/datasets"}]}}' \ + -- claude +``` + +A sandbox takes at most 32 mounts on an arm64 gateway host and three on an x86_64 host. Single-file sources, sources that are symbolic links, `selinux_label`, and other mount types are not supported. VM mounts work only with the libkrun backend, so GPU sandboxes cannot use them. + + +VM bind mounts expose host files to sandbox workloads. Additionally, libkrun does not confine a compromised guest kernel to the configured source directory; it may access other host files permitted by the gateway user's permissions. VM mounts require the same opt-in as [Docker bind mounts](#docker-mounts): + +```toml +[openshell.drivers.vm] +allow_driver_config = true +enable_bind_mounts = true + +[openshell.drivers.vm.resource_admission] +enabled = false +``` + + + +Targets cannot replace the workspace root, OpenShell paths, or VM-internal paths such as `/tmp`, `/proc`, `/dev`, and `/srv`, and cannot be nested inside one another. The guest refuses a target that passes through a symlink in the image. + +On Linux with a non-root gateway, the sandbox can create files in a read-write mount only when its UID and GID match the gateway user's. Set `sandbox_uid` and `sandbox_gid` under `[openshell.drivers.vm]` to match. Otherwise the sandbox cannot create files, and its access to existing files follows the host permission bits for its numeric UID and GID. + ## Kubernetes Driver The Kubernetes driver runs sandboxes as pods in a sandbox namespace. It requires the [Agent Sandbox](https://github.com/kubernetes-sigs/agent-sandbox) controller. Install the gateway with the Helm chart; see [Kubernetes setup](/kubernetes/setup).