Configuration Reference

GSV configuration is a SQLite-backed key/value store owned by the Kernel Durable Object. Keys are slash-separated strings and explicit overrides are stored as strings. System-wide configuration lives under config/; per-user overrides live under users/{uid}/.

The same store is exposed through:

• /sys/config/* for system configuration.
• /sys/users/{uid}/* for user-scoped configuration.
• sys.config.get and sys.config.set for syscall clients.

Code defaults are overlaid at read time. An explicit SQLite value wins; deleting that explicit value reveals the code default again. Prefix reads include both explicit values and matching defaults, with explicit values overriding default entries of the same key.

Access Model

Root (uid 0) can read and write all configuration. Non-root users can read their own users/{uid}/* keys and non-sensitive config/* keys. Sensitive system keys are hidden from non-root reads, including prefix listings.

Sensitive final path segments include api_key, secret, token, password, access_token, refresh_token, and client_secret. Suffixes such as _api_key, _secret, _token, and _password are also treated as sensitive.

sys.config.set lets non-root users write only their own users/{uid}/ai/* keys. System writes under /sys/config/* require root.

Reading and Writing

Inside a GSV shell, use the filesystem view:

cat /sys/config/ai/provider
cat /sys/users/1000/ai/model
printf '%s\n' openai > /sys/users/1000/ai/provider

From an API or WebSocket client, use syscalls:

{ "key": "config/ai" }

{ "key": "users/1000/ai/model", "value": "gpt-4.1-mini" }

Reading a prefix returns every readable key below that prefix. Reading an exact key returns that key's value or fails if access is denied.

AI Model Config

Most AI runtime keys resolve per-user values first, then fall back to system defaults. System-only operational keys are marked with none in the user override column.

System Key	User Override	Default	Description
config/ai/provider	users/{uid}/ai/provider	workers-ai	Provider adapter.
config/ai/model	users/{uid}/ai/model	@cf/nvidia/nemotron-3-120b-a12b	Provider model identifier.
config/ai/api_key	users/{uid}/ai/api_key	empty	Provider credential. Sensitive.
config/ai/reasoning	users/{uid}/ai/reasoning	off	Reasoning mode hint.
config/ai/max_tokens	users/{uid}/ai/max_tokens	8192	Maximum output tokens.
config/ai/max_context_bytes	users/{uid}/ai/max_context_bytes	32768	Prompt context budget before messages.
config/ai/generation/timeout_ms	users/{uid}/ai/generation/timeout_ms	180000	Maximum time to wait for a single model generation before releasing the run with an error.
config/ai/generation/streaming	none	auto	Generation transport mode. auto streams when supported; off forces final-output only.
config/ai/transcription/model	users/{uid}/ai/transcription/model	@cf/openai/whisper-large-v3-turbo	Model used by ai.transcription.create and process media transcription.
config/ai/transcription/max_bytes	users/{uid}/ai/transcription/max_bytes	26214400	Maximum audio payload size accepted for transcription.
config/ai/speech/model	users/{uid}/ai/speech/model	@cf/deepgram/aura-2-en	Model used by ai.speech.create.
config/ai/speech/speaker	users/{uid}/ai/speech/speaker	luna	Default text-to-speech speaker or voice.
config/ai/speech/encoding	users/{uid}/ai/speech/encoding	mp3	Default speech audio encoding.
config/ai/speech/max_chars	users/{uid}/ai/speech/max_chars	4000	Maximum normalized text length accepted for speech synthesis.
config/ai/speech/timeout_ms	users/{uid}/ai/speech/timeout_ms	30000	Per-utterance speech synthesis timeout.

System and Account Context

All agent runs load shared system context first:

config/ai/context.d/*.md

The run-as account then contributes its home context:

~/context.d/*.md

The owning human's ~/context.d/*.md files are also layered in as owner context when a process runs as one of that human's agents. Files are sorted lexically, empty files are skipped, and Markdown content is concatenated into the corresponding context section.

Use numeric prefixes to make ordering explicit:

config/ai/context.d/00-gsv.md
config/ai/context.d/10-runtime.md
~/context.d/00-role.md

System and account context support runtime template variables such as identity.uid, identity.username, identity.home, identity.cwd, devices, and mcpServers.

Tool Approval Policy

Each account can have a JSON policy at:

users/{uid}/ai/tools/approval

Policy shape:

{
  "default": "auto",
  "rules": [
    { "match": "shell.exec", "when": { "anyTag": ["destructive", "privileged"] }, "action": "ask" },
    { "match": "sys.mcp.call", "action": "ask" },
    { "match": "fs.delete", "action": "deny" },
    { "match": "fs.*", "when": { "target": "device" }, "action": "ask" }
  ]
}

Actions are auto, ask, or deny. match accepts an exact syscall name or a domain wildcard such as fs.*. when can filter by anyTag, allTags, argEquals, argPrefix, or target (gsv or device). Invalid or missing JSON falls back to the runtime default policy.

Runtime Config Keys

Key	Default	Description
config/server/name	gsv	Server name used by hostname-style tools and package metadata.
config/server/timezone	UTC	Runtime timezone value.
config/server/version	0.1.0	Server version value.
config/shell/timeout_ms	30000	Default native shell timeout.
config/shell/network_enabled	true	Enables network tools in native shell execution.
config/shell/max_output_bytes	524288	Maximum captured shell output.
config/process/init_label	init ({username})	Default init process label template.
config/process/max_per_user	0	Maximum processes per user. 0 means unlimited.

Package Config

Package-related config is also stored in the same key/value store:

Key Pattern	Description
users/{uid}/pkg/remotes/{name}	User package catalog remotes managed by pkg.remote.*.
config/pkg/public-repos/{owner}/{repo}	Public package repo allowlist managed by pkg.public.*.

Practical Notes

All values are strings. Callers parse booleans and numbers at the point of use. Prefer user-scoped AI overrides for per-user model settings, and reserve system keys for defaults that should apply across the GSV instance.