Bare OS agent — Markdown workspace

This tree follows the agent Markdown workspace convention: “soul” files under workspace/ define personality, rules, and memory. /bin/agent loads them into the LLM system prompt on each session (after seeding from /share/agent-workspace/ on the system drive if ~/.agent/workspace/SOUL.md is missing).

Layout (personal Hyperdrive)

Path	Role
`~/.agent/workspace/`	Agent brain — git-trackable, portable across peers
`~/.agent/workspace/skills/`	Modular skills — one folder per skill, each with `SKILL.md` (optional YAML frontmatter)
`~/.agent/workspace/memory/`	Daily append logs `YYYY-MM-DD.md` (optional)
`~/.agent/skills/`	Optional global skills (lower precedence than `workspace/skills/` when names collide)
`~/.agent/config.json`	Backend (`qvac` / `rest`), model, API URL/key (REST), and reasoning/process visibility controls
`~/.agent/skill-loader.js`	Host stub for `discoverSkills` / `loadSkill` (in-image agent uses bundled discovery + `read_skill` tool)
`~/.agent/loader.js`	Stub / hook for host-side experimentation (not used by `/bin/agent` bundle)
`~/.agent/index.js`	Stub factory reference (in-image agent uses built-in loader)

Skills

Add a directory under ~/.agent/workspace/skills/<skill-id>/ with a SKILL.md file.
Use YAML frontmatter for name, description, version, etc. The compact system prompt lists id, name, and a short description only.
During a session, the model loads the full document with the read_skill tool (do not paste huge skills into the user channel unless asked).
Shared skills can live under ~/.agent/skills/; keep workspace/skills/ for machine-local or repo-specific behavior.

Seeded examples in this repo (under skills/): p2p-os-status, bare-os-kernel-proc, bare-os-super-developer, agent-ops, holesail (managed state.json, seed/key, stock bare-www-* / bare-ssh-*), and hdms (Hyperdrive mounts and invite/pair). Provider-specific skill xai-compat is only seeded when provider is configured as xai.

After agent --config / --setup (or changing owner_name / agent_label via edit_agent_config), IDENTITY.md and USER.md are regenerated from config.json so the workspace matches the operator and agent label.

Inference backends

Default backend is QVAC (QuantumVerse Automatic Computer) — local in-process LLM via the booter ctx.bareOsQvac* bridge (@qvac/sdk). Weights download on first use after you pick a profile in agent --config.

Models are stored for durability on HDMS label models (guest path /mnt/models/) and materialize into a host cache for llama.cpp load:

Host cache: $BARE_OS_HOST_DATA/qvac/models (default ~/.bare-os/qvac/models)
Runtime config: $BARE_OS_HOST_DATA/qvac/qvac.config.json (QVAC_CONFIG_PATH, absolute cacheDirectory)

First load downloads via the QVAC registry into the host cache, then mirrors into HDMS. If HDMS already has the GGUF, Bare OS materializes it to the host cache before load. If auto-create fails, run hdms create models after unlock.

backend — qvac (default) or rest
qvac_profile — lite / recommended / strong / tool-tiny
qvac_model — registry id (e.g. QWEN3_1_7B_INST_Q4)
qvac_ctx_size — optional context window override (profile defaults: lite/tool-tiny 4096, recommended/strong 8192; max 32768)
qvac_device — gpu (default) or cpu (bypass Vulkan; slower)
qvac_main_gpu — auto (default: pick highest-VRAM Vulkan GPU, else CPU), dedicated, integrated, or device index (0, 1, …)
qvac_gpu_layers — optional layer offload count (0 = CPU weights)

Set BARE_OS_SKIP_QVAC=1 on the host (or pack with --skip-qvac) to stub QVAC natives; then choose REST in config.

REST (OpenAI-compatible) remains fully supported:

rest_base_url, rest_api_key, model, provider (groq / xai / …)
groq profile defaults to https://api.groq.com/openai/v1
xai profile defaults to https://api.x.ai/v1

Reasoning/process visibility is configurable in config.json:

show_reasoning — master toggle
reasoning_mode — off / summary / trace
reasoning_max_chars — bounded reasoning output
reasoning_include_tools — include tool traces in process stream

Max-autonomy bridge policy switches are also in config.json:

allow_bridge_mutations — master mutation gate
allow_host_notifications — notification route gate
allow_host_actions — host action route gate
emergency_stop_mutations — kill switch for mutating bridge tools

Autonomous coding runner controls in config.json:

autonomous_mode_enabled — master toggle for autonomous loop mode
autonomous_max_runtime_ms — runtime timebox for autonomous sessions
autonomous_completion_required_checks — quality gates that must pass before done
autonomous_allow_paths — allowed write/shell scope paths (* for unrestricted by path policy)
autonomous_deny_ops — hard denylist of tool operations blocked during autonomous runs
autonomous_active, autonomous_stop_requested, autonomous_status, autonomous_last_error — run state/status fields managed by tools/runtime

Editing

Change files under ~/.agent/workspace/ on your personal drive.
Restart agent or start a new session so the system message reloads.
Keep SOUL.md / AGENTS.md stable within a session if you follow the drift guard in AGENTS.md.

Defaults in this repository

Source templates: packages/bare-os-coreutils/share/agent-workspace/ — copied to kernel/share/agent-workspace/ during npm run build -w bare-os-coreutils for seeding into new homes.

Compatibility

File names and load order match common agent Markdown layouts so templates can be dropped into workspace/ with minimal edits.

6.1 KiB Raw Blame History