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.

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.

5.5 KiB Raw Blame History