Concepts

This page is the shared vocabulary for holaOS. It defines the core layers, artifacts, and surfaces that show up across the desktop app, the runtime, and the workspace model.

Holaboss Desktop is the operator-facing product surface. holaOS is the environment layer underneath it. The concepts below give you the working model for how those pieces fit together, so the rest of the docs are easier to scan and reason about.

The system at a glance

Product Surface

Holaboss Desktop

Operator shell for opening workspaces, configuring models, inspecting state, and launching the runtime.

→

holaOS

Environment layer = workspace contract + runtime services + harness boundary

Workspace Contract

Workspace

workspace.yamlAGENTS.mdAppsSkillsTemplates

The authored environment surface the runtime reads and compiles per run.

Runtime Services

Runtime

API ServerMemoryState StoreContinuityApp OrchestrationCapability Projection

Owns memory, continuity, and the execution environment around the run, then prepares the reduced package the harness receives.

Execution Boundary

Harness Host→Agent Harness

The selected harness runs inside the runtime path, not beside the workspace or desktop.

The runtime compiles the workspace contract into a reduced execution package, then hands that package to the selected harness.

Each layer has a distinct job. Keeping those jobs separate makes the system easier to operate and extend.

In this model, holaOS is the environment layer: the workspace contract, the runtime services around it, and the harness boundary the runtime controls. Holaboss Desktop sits above that layer as the operator-facing product surface. A workspace is not just a folder the harness happens to open; in holaOS, it is part of the system contract itself.

Desktopoperator UI

The desktop app is where you create, inspect, and operate workspaces locally. It handles the operator experience: connecting to a runtime, opening workspaces, choosing models, and exposing the state the runtime makes visible.

Runtimeexecution layer

The runtime is the portable service layer inside `holaOS` that actually runs a workspace. It owns execution, memory and continuity services, app orchestration, capability projection, the durable state that keeps a workspace consistent over time, and the harness host that invokes the selected agent harness.

Agent Harnessselected executor

The agent harness is the actual executor the runtime hands a prepared run to. It does not define the workspace model by itself. The runtime compiles a reduced execution package and passes that package across the harness boundary to the selected harness. Today the OSS repo ships a Pi-based harness path, but the boundary is designed so other harnesses can be added later.

Workspaceunit of work

A workspace is the operating context for one workflow. It carries the authored files, installed apps, skills, and configuration that define how the workflow should behave. In the `holaOS` model, it is the primary environment artifact. Memory and continuity are resolved around the workspace by the runtime rather than collapsed into one file.

Memorydurable recall surface

Memory is the durable knowledge surface around the workspace: recalled facts, procedures, preferences, identity, and other information that should survive across runs. In `holaOS`, memory is not the same thing as the workspace root and not the same thing as short-lived run state.

Continuityruntime-owned execution truth

Continuity is the runtime-owned state that lets work resume coherently: recent turn state, request snapshots, session mappings, compaction boundaries, and other execution artifacts. It is distinct from durable memory and from human-authored workspace policy.

Templateworkspace scaffold

A template is the starting shape for a workspace. Templates define the initial files, apps, skills, and conventions that a new workspace should inherit.

Appcapability module

An app adds a focused capability to a workspace. Apps can provide UI, automation, MCP tools, background jobs, and their own state. Each app declares what integrations it needs in its `app.runtime.yaml` manifest. Think of apps as modular building blocks rather than generic plugins.

Integrationaccount connection

An integration connects a workspace to an external service like Gmail, GitHub, or Twitter. Apps declare which integrations they require; the runtime resolves those requirements for the workspace by binding connected accounts to apps. Credentials are managed by the runtime broker — apps never see raw tokens directly.

Skillinstruction pack

A skill is a reusable instruction file that teaches the agent how to perform a narrow task well. Skills live with the workspace so they can be shared, versioned, and recalled consistently.

Environment Engineeringsystems thesis

The idea that long-horizon agent systems should be defined by their environment contract: workspace structure, memory surfaces, evolve behavior, capability projection, and harness boundary. The harness still matters, but it is no longer the only thing that defines the system.

MCPtool surface

MCP is the standardized tool interface used by Holaboss apps. It lets the runtime expose capabilities in a way the agent can call reliably.

Bridge SDKapp integration layer

The Bridge SDK (`@holaboss/bridge`, installed via npm) connects apps to the Holaboss runtime and workspace. It is what lets an app publish outputs, call external services through the integration broker, and integrate cleanly with the rest of the platform.

Outputdurable result

An output is the persistent result of an agent or app action. Outputs are what users review, reuse, or publish after a run completes.

How the pieces relate

1. The desktop app opens or creates a workspace (optionally from a template).
2. The workspace provides the authored contract: instructions, apps, skills, and model settings.
3. The runtime resolves memory, continuity, capabilities, integrations, and prompt/model configuration for that run.
4. The runtime passes a reduced execution package to the selected agent harness.
5. Apps provide tools, UI, and background behavior. Apps that need external access declare integration requirements.
6. The runtime resolves those requirements by matching them to connected accounts through bindings.
7. The result is stored as outputs, continuity state, and durable memory where appropriate, so later runs can continue from the same context.

• Templateworkspace scaffold
  • Workspaceunit of work
    • AgentAI brain
      • Skillsbehavior plugins — prompt-based
      • Appscapability modules — code-based
        • MCP Toolswhat the agent can do
        • Web UIwhat the user can see
        • Integration Requirementswhat credentials it needs
          • Bindingswhich account serves which app
          • Connectionsauthenticated external accounts

Why this framing matters

The holaOS view is that the system is defined by the environment around the agent, not only by the harness that executes a single run.

That is why the docs emphasize:

• authored workspace files over hidden prompt blobs
• durable memory and continuity artifacts over transcript replay
• per-run capability projection over implicit tool visibility
• packaging and portability as part of the technical model
• the desktop as one product surface built on top of the environment

What to read next

Start here

Overview

Read the technical story first so the rest of the docs fit into the same systems model.

Core thesis

Environment Engineering

See how the environment-centric model differs from a harness-centric one.

Environment contract

Workspace Model

Understand the authored workspace surface and the runtime-owned state around it.

Developer path

Build on holaOS

Move from the systems model into the concrete path for building apps and templates.