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 advanced override (≥ profile model-card size). Defaults are automatic from model cards (Qwen3 32768, Llama tool-tiny 131072). Legacy 4k/8k values are ignored. Cap further with host env BARE_OS_QVAC_MAX_CTX if VRAM is tight.
agent --config only asks for owner name, agent label, and QVAC vs REST; model/profile/context are applied automatically.
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

The seeded SOUL.md / AGENTS.md / TOOLS.md tell the model it is a coding agent with full guest admin (denylist): unique search_replace, apply_patch, grep (output_mode), find_symbol, glob_files, todo_write, plan mode, memory / remember, skills / create_skill, web_search, git helpers, session rewind/export, and run_js_script (no Node in the guest). Project skills are also walked from .grok/skills, .agents/skills, .claude/skills, and .cursor/skills.

CLI production flags: --plan, --auto, --new, --compact, --max-turns, --model, --system FILE. Inspect (no model call): skills / todos / plan / undo / hooks / history [query] / rewind [N] / export [path] / remember TEXT / recap. Discord /agent is the same harness (shared ~/.agent).

Access policy defaults to full guest admin (access_policy: full):

allow_delete, allow_bridge_mutations, allow_host_notifications, allow_host_actions — true
command_deny — empty substring denylist for run_command
mutate_deny_prefixes — read-only base system (/bin, /etc, /boot, /lib, /usr, /share, /proc, /dev, /sys, /run)
autonomous_deny_ops — empty
emergency_stop_mutations — kill switch (default false)

Autonomous coding runner controls in config.json:

autonomous_mode_enabled — master toggle for autonomous loop mode (default true)
autonomous_max_runtime_ms — runtime timebox for autonomous sessions
autonomous_completion_required_checks — quality gates that must pass before done
autonomous_allow_paths — optional extra path scope (* default; denylist is mutate_deny_prefixes)
autonomous_deny_ops — tool-name denylist during autonomous runs (empty by default)
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.

7.3 KiB Raw Blame History