Workspace Model

Workspaces live under the runtime sandbox root. In desktop mode that root comes from the local sandbox host data directory. In standalone runtime deployments it defaults to /holaboss.

sandbox-root/
• state/

  • runtime-config.jsonModel providers
  • runtime.dbSessions · turns · integrations
• workspace/<id>/

  • AGENTS.mdRoot prompt
  • workspace.yamlAgent · skills · apps
  • skills/SKILL.md per skill
  • apps/app.runtime.yaml per app
  • .holaboss/Runtime-managed state
• memory/

  • workspace/<id>/knowledge · runtime
  • preference/User preferences
  • identity/User identity

The workspace model is split deliberately: human-authored policy, runtime contracts, execution truth, and durable memory do not live in the same place.

Directory layout

<sandbox-root>/
  state/
    runtime-config.json
    runtime.db

  workspace/
    .holaboss/
      workspace-mcp-sidecar-state.json
      <server>.workspace-mcp-sidecar.stdout.log
      <server>.workspace-mcp-sidecar.stderr.log

    <workspace-id>/
      .git/
      AGENTS.md
      workspace.yaml
      ONBOARD.md
      skills/
        <skill-id>/
          SKILL.md
      apps/
        <app-id>/
          app.runtime.yaml
      .holaboss/
        workspace_id
        harness-session-state.json
        input-attachments/<batch-id>/*
        pi-agent/auth.json
        pi-agent/models.json
        pi-sessions/...

  memory/
    MEMORY.md
    workspace/
      <workspace-id>/
        MEMORY.md
        runtime/
          latest-turn.md
          session-state/
          session-memory/
          recent-turns/
          blockers/
          permission-blockers/
        knowledge/
          facts/
          procedures/
          blockers/
          reference/
    preference/
      MEMORY.md
      *.md
    identity/
      MEMORY.md
      *.md

What each part means

workspace.yaml

workspace.yaml is the root runtime plan for the workspace. It describes the active agent, skill ordering, MCP registry, and the apps installed into the workspace.

.git/

Each new workspace is initialized as a local git repository after its scaffold or template is materialized. That repository is intended for agent-owned local version control checkpoints rather than remote sync.

AGENTS.md

AGENTS.md is the human-authored instruction surface. Put standing workspace policy here instead of trying to encode it in runtime state.

skills/

Workspace skills live under skills/. The runtime loads them from the workspace directory, and each skill directory must contain a SKILL.md file.

apps/

Workspace-local apps live under apps/<app-id>/. Each app must provide app.runtime.yaml, which is the runtime contract for lifecycle and integration behavior.

.holaboss/

<workspace-id>/.holaboss/ stores runtime-managed workspace state such as the identity marker, persisted harness session mapping, staged input attachments, and Pi harness state.

workspace/.holaboss/ is separate from the per-workspace .holaboss/ directory. It stores shared workspace-root state for MCP sidecars and their logs.

state/runtime.db

state/runtime.db is the durable runtime registry for workspaces, sessions, bindings, queue state, turn results, compaction boundaries, request snapshots, and durable memory catalog metadata. It also stores integration connections (authenticated external accounts) and integration bindings (the mapping from workspace/app targets to specific connections). The workspace_id file exists mainly as an on-disk identity marker for workspace discovery and migration.

memory/

memory/ is sandbox-global, not part of a single workspace directory. It holds the markdown memory surfaces used by the runtime memory service.

What belongs where

Use these rules of thumb:

Information type	Best home
Standing workspace policy	AGENTS.md
Workspace plan and app inventory	workspace.yaml
App lifecycle and port/runtime contract	apps/<app-id>/app.runtime.yaml
App integration requirements	apps/<app-id>/app.runtime.yaml → integrations
Integration connections and bindings	state/runtime.db
Execution truth and session continuity	state/runtime.db
Durable workspace memory	memory/workspace/<workspace-id>/knowledge/
Durable user preferences	memory/preference/
Durable user identity	memory/identity/
Latest-turn or resume-only context	memory/workspace/<workspace-id>/runtime/

If a piece of information only matters for the next resume, keep it in runtime continuity. If it should be recalled later, keep it in durable memory. If it is a standing rule for the workspace, keep it in AGENTS.md.

What the runtime compiles per run

The workspace tree is only the authored input. For each run, the runtime compiles a reduced execution package from:

• workspace.yaml
• AGENTS.md
• installed app manifests
• workspace-local skills

Before the harness starts, the runtime then:

1. projects the visible and callable capability surface for that run
2. assembles prompt sections and prompt layers
3. computes a prompt_cache_profile
4. persists a sanitized request snapshot for replay and debugging
5. passes a reduced execution package to the harness with the selected model target, composed prompt, capability manifest, and workspace checksum

That split is why the filesystem contract and the runtime continuity contract need to stay separate. The workspace holds authored intent; the runtime compiles per-run execution state from it.

App manifests

app.runtime.yaml is the app-level runtime contract. It tells the runtime how to:

• install or set up the app
• start and stop it
• discover its MCP server
• check its health
• resolve app-specific ports
• resolve integration requirements (which external services the app needs access to)

The runtime does not care what framework the app uses internally. It only needs the declared contract. See the app.runtime.yaml reference for the full field guide including integration declarations.