Skip to content

docs(sandboxes): document file.parser and deniedDomains in kits spec #25030

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dvdksn wants to merge 4 commits into
base: main
Choose a base branch
from
+79 −8
Open

docs(sandboxes): document file.parser and deniedDomains in kits spec #25030

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
69f9aae
docs(sandboxes): document file.parser for kit credential sources
dvdksn May 12, 2026
3cfcefc
docs(sandboxes): document deniedDomains in kit network spec reference
dvdksn May 12, 2026
0e229d9
docs(sandboxes): restructure file.parser section
dvdksn May 12, 2026
a22ca66
docs(sandboxes): correct file.parser fallback semantics
dvdksn May 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 79 additions & 8 deletions content/manuals/ai/sandboxes/customize/kits.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -430,17 +430,87 @@
| -------------------------- | ------------------------------------------------------------- |
| `sources` | Map of service identifier to credential source. |
| `sources.<id>.env` | Environment variables to read on the host, in priority order. |
| `sources.<id>.file.path` | Path on host. `~` expands to home. |
| `sources.<id>.file.parser` | How to extract the value (for example, `"json:apiKey"`). |
| `sources.<id>.file.path` | Path on host. `~` expands to home directory. |
| `sources.<id>.file.parser` | How to extract the credential value from the file. |
| `sources.<id>.priority` | `env-first` (default) or `file-first`. |

Service identifiers link credentials to [network rules](#network).

#### file.parser

`file.parser` tells the proxy how to extract a credential from the file at `file.path`.
Omit it for plain-text files; set it to `json:<dot.path>` to extract a field from a JSON file.

| Value | Behavior |
| ----------------- | ------------------------------------------------------------------------------------ |
| omitted or empty | Reads the entire file as the credential. Leading and trailing whitespace is trimmed. |
| `json:<dot.path>` | Parses the file as JSON and returns the value at the dot-separated path. |
| any other value | Rejected — `unsupported parser: <value>`. |

For `json:` paths, segments are separated by `.` (for example, `json:credentials.github.token`).
Only object keys can be navigated — arrays are not supported and there is no `[0]`-style indexing.
Keys that contain a literal `.` cannot be referenced. The resolved value must be a string, number,
or boolean; numbers and booleans are converted to strings. Objects, arrays, and null are rejected.

Check failure on line 453 in content/manuals/ai/sandboxes/customize/kits.md

View workflow job for this annotation

GitHub Actions / validate (vale) 

[vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'boolean'?

Raw Output:
{"message": "[Vale.Spelling] Did you really mean 'boolean'?", "location": {"path": "content/manuals/ai/sandboxes/customize/kits.md", "range": {"start": {"line": 453, "column": 4}}}, "severity": "ERROR"}

When a source has both `env` and `file` defined, `priority` controls which is tried first. The
preferred source is used when it exists — the environment variable is set, or the file is
present on disk. If it doesn't, the other source is used instead. The choice is made once at
discovery time, so parser errors (missing JSON field, wrong value type, invalid JSON) surface
as errors rather than triggering a fallback.

Plain-text token file:

```yaml
credentials:
sources:
openai:
file:
path: "~/.openai/token"
```

Nested JSON field, with an environment variable as fallback:

```yaml
credentials:
sources:
github:
env:
- GH_TOKEN
file:
path: "~/.config/myapp/creds.json"
parser: "json:credentials.github.token"
priority: file-first
```

Given `~/.config/myapp/creds.json`:

```json
{
"credentials": {
"github": { "token": "ghp_xyz", "expires": "2026-12-31" }
}
}
```

The proxy resolves the credential to `ghp_xyz`, falling back to `GH_TOKEN` if the file is
missing. If the file exists but the JSON path doesn't resolve, the request fails with the
parser error below instead of falling back.

Check warning on line 497 in content/manuals/ai/sandboxes/customize/kits.md

View workflow job for this annotation

GitHub Actions / validate (vale) 

[vale] reported by reviewdog 🐶
[Docker.RecommendedWords] Consider using 'following' instead of 'below'

Raw Output:
{"message": "[Docker.RecommendedWords] Consider using 'following' instead of 'below'", "location": {"path": "content/manuals/ai/sandboxes/customize/kits.md", "range": {"start": {"line": 497, "column": 14}}}, "severity": "INFO"}
Copy link
Copy Markdown

@docker-agent docker-agent May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MEDIUM] Use "following" instead of "below"

The style guide's word list explicitly requires "following" in place of "below" when referring to content that appears later on the page.

Suggested fix:

the request fails with the following parser error instead of falling back.


Common errors when using `json:` parsers:

| Error message | Cause |
| --------------------------------------------- | ------------------------------------------------------------------- |
| `field 'X' not found in JSON` | The path doesn't exist in the file. |
| `cannot navigate to field 'X': not an object` | A path segment hit a string, array, or scalar instead of an object. |
| `field 'X' is not a string value` | The resolved value is an object, array, or null. |
| `failed to parse JSON: ...` | The file is not valid JSON. |

### Network

```yaml
network:
allowedDomains: [<domain>, ...]
deniedDomains: [<domain>, ...]
serviceDomains:
<domain>: <service-id>
serviceAuth:
Expand All @@ -449,12 +519,13 @@
valueFormat: <format>
```

| Field | Description |
| ------------------------- | ---------------------------------------------------------------- |
| `allowedDomains` | Domains the sandbox can reach. Wildcards supported. |
| `serviceDomains` | Map of domain to service identifier from `credentials.sources`. |
| `serviceAuth.headerName` | HTTP header the proxy sets (for example, `Authorization`). |
| `serviceAuth.valueFormat` | Format string for the header value (for example, `"Bearer %s"`). |
| Field | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `allowedDomains` | Domains the sandbox can reach. Wildcards supported. |
| `deniedDomains` | Domains the sandbox is blocked from reaching. Deny rules take precedence over allow rules, including those from other composed kits. |
| `serviceDomains` | Map of domain to service identifier from `credentials.sources`. |
| `serviceAuth.headerName` | HTTP header the proxy sets (for example, `Authorization`). |
| `serviceAuth.valueFormat` | Format string for the header value (for example, `"Bearer %s"`). |

### Environment

Expand Down
Loading