From 1af4ca3694f825abc35cb9fd2c8e304c8232bbe2 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Wed, 14 Oct 2026 04:00:26 +0000
Subject: [PATCH] docs(website): sync dev docs from
 6e69360d0e1536d891f4abfbb60c1d90e50188c9

---
 fern/.docs-snapshots.yml                            |  6 +++---
 .../how-it-works/gateways/configuration.mdx         |  6 ++++++
 fern/pages-dev/how-it-works/sandboxes/overview.mdx  | 13 +++++++++++++
 fern/pages-dev/observability/ocsf-json-export.mdx   |  6 +++++-
 4 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/fern/.docs-snapshots.yml b/fern/.docs-snapshots.yml
index 2ed5f09f7..73223e753 100644
--- a/fern/.docs-snapshots.yml
+++ b/fern/.docs-snapshots.yml
@@ -1,8 +1,8 @@
 snapshots:
   dev:
-    source-ref: 39b13d120bed73b2f4eb8bf3e9c717212ceb48b2
-    source-sha: 39b13d120bed73b2f4eb8bf3e9c717212ceb48b2
-    version: 0.1.5.dev8
+    source-ref: 6e69360d0e1536d891f4abfbb60c1d90e50188c9
+    source-sha: 6e69360d0e1536d891f4abfbb60c1d90e50188c9
+    version: 0.1.5.dev9
   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 e63401203..30a75f7f6 100644
--- a/fern/pages-dev/how-it-works/gateways/configuration.mdx
+++ b/fern/pages-dev/how-it-works/gateways/configuration.mdx
@@ -981,6 +981,12 @@ administrator or belong to the Windows Performance Log Users group. Workload
 commands and working directories remain sandbox-scoped and must be supplied in
 the `mxc` driver configuration when creating a sandbox.
 
+`OPENSHELL_OCSF_JSON=1` enables the gateway's JSONL audit
+sink independently of the selected compute driver. Set `OPENSHELL_OCSF_LOG_DIR`
+to override the default `%PROGRAMDATA%\OpenShell\logs` directory on Windows
+or `$XDG_STATE_HOME/openshell/logs` on Unix. Prefer the gateway's configured
+`ocsf_log` output for retention controls and loss metrics.
+
 The driver records executable identity in process audit events and omits raw
 command arguments because they can contain credentials or personal data. See
 [OCSF JSON Export](/observability/ocsf-json-export) for durable Windows audit
diff --git a/fern/pages-dev/how-it-works/sandboxes/overview.mdx b/fern/pages-dev/how-it-works/sandboxes/overview.mdx
index c3f6f86dc..f10cccb56 100644
--- a/fern/pages-dev/how-it-works/sandboxes/overview.mdx
+++ b/fern/pages-dev/how-it-works/sandboxes/overview.mdx
@@ -33,6 +33,9 @@ attaching:
 openshell sandbox create --name worker --detach -- ./worker
 ```
 
+Drivers that do not support foreground attachment reject the request before
+provisioning. Use `--detach` with those drivers.
+
 Use `--restart-policy on-failure` to replace the runtime after a nonzero main
 process exit, or `--restart-policy always` to replace it after every exit:
 
@@ -393,6 +396,16 @@ openshell sandbox create --env API_KEY=sk-test --env DEBUG=1 -- my-agent
 
 Variables set with `--env` are available to all processes in the sandbox, including the initial command, interactive shells, and exec commands.
 
+Use `--env-from KEY[=ENVVAR]` when the value should come from the CLI process environment instead of appearing in the CLI process arguments. If `ENVVAR` is omitted, OpenShell reads `KEY`:
+
+```shell
+export SESSION_TOKEN="..."
+openshell sandbox create --env-from SESSION_TOKEN -- my-agent
+openshell sandbox create --env-from AGENT_TOKEN=SESSION_TOKEN -- my-agent
+```
+
+`--env-from` changes only how the CLI receives the value. The resulting variable is still available to processes in the sandbox, just like `--env`.
+
 When an `--env` key looks like a credential — a known provider variable, or a name whose underscore-separated segments include a credential word such as `TOKEN`, `SECRET`, `PASSWORD`, `CREDENTIAL`, `API_KEY`, `ACCESS_KEY`, or `SECRET_KEY` (for example `DB_TOKEN` or `MY_ACCESS_KEY`) — `sandbox create` prints a non-blocking warning. Matching is on whole segments, so unrelated names like `TOKENIZERS_PARALLELISM` or `PASSWORDLESS_LOGIN` do not warn. The agent inside the sandbox can read plain environment values directly, so to hide a secret from the agent, attach it through a [profile-backed provider](/how-it-works/providers/profiles) with `--provider` instead. Suppress the warning with `--no-credential-warnings`. Detection uses the key name only; values are never inspected or printed.
 
 You can also set per-command environment variables with `sandbox exec`:
diff --git a/fern/pages-dev/observability/ocsf-json-export.mdx b/fern/pages-dev/observability/ocsf-json-export.mdx
index 7e19d9d81..61738d08c 100644
--- a/fern/pages-dev/observability/ocsf-json-export.mdx
+++ b/fern/pages-dev/observability/ocsf-json-export.mdx
@@ -63,9 +63,13 @@ $env:OPENSHELL_OCSF_LOG_DIR = "D:\OpenShell\audit"
 openshell-gateway --drivers mxc --config gateway.toml
 ```
 
-The sink is available only when Windows selects the MXC driver. It rotates
+This environment-configured sink is available on all platforms independently of
+the selected compute driver. On Unix hosts its default directory is
+`$XDG_STATE_HOME/openshell/logs` (or `$HOME/.local/state/openshell/logs`). It rotates
 daily and retains the three most recent files. Diagnostic `--log-level` values
 do not suppress records in this explicitly enabled audit sink.
+Prefer the `gateway.toml` output above for configured retention and loss metrics;
+enabling both sinks writes to both independently.
 
 ## Output Location