### App Setup and Start Example

Source: https://www.holaos.ai/docs/build/apps

Example commands to set up and start a local App using curl.

```APIDOC
### 5. Start through the runtime

terminal
```
# Run lifecycle.setup
curl -X POST http://127.0.0.1:5160/api/v1/apps/my_app/setup

# Run lifecycle.start
curl -X POST http://127.0.0.1:5160/api/v1/apps/my_app/start

# Poll build status
curl http://127.0.0.1:5160/api/v1/apps/my_app/build-status

# See the resolved port map
curl http://127.0.0.1:5160/api/v1/apps/ports
```
```

--------------------------------

### App Install and Setup Diagnostics

Source: https://www.holaos.ai/docs/contribute/runtime/apis

APIs for managing app installations and retrieving setup logs. The install endpoint handles race conditions, and the setup log endpoint provides recent events and log tails.

```APIDOC
## App Install and Setup Diagnostics

### Description
Provides endpoints for installing app archives and retrieving setup logs for diagnostics.

### POST /api/v1/apps/install-archive

#### Description
Serializes app installs per (workspace_id, app_id). Returns a 409 conflict if an install is already in progress for the same target.

#### Method
POST

#### Endpoint
/api/v1/apps/install-archive

#### Request Body
(Request body details not explicitly provided in source, but implies workspace_id and app_id are used.)

### GET /api/v1/apps/:appId/setup-log

#### Description
Returns the latest setup log tail and recent structured events from the app's log directory.

#### Method
GET

#### Endpoint
/api/v1/apps/:appId/setup-log

#### Parameters
##### Query Parameters
- **workspace_id** (string) - Required - The ID of the workspace.

#### Response
- **log_path** (string) - Description of the log file path.
- **log_size_bytes** (integer) - Size of the log file in bytes.
- **log_tail** (string) - Bounded tail of the setup.latest.log file.
- **recent_events** (array) - Last lifecycle events from events.ndjson.

#### Request Example
```bash
curl \
  'http://127.0.0.1:5160/api/v1/apps/my_app/setup-log?workspace_id=workspace-1'
```
```

--------------------------------

### App Setup Log Retrieval

Source: https://www.holaos.ai/docs/build/apps

Command to retrieve setup diagnostics for an App if setup fails.

```APIDOC
If setup fails, pull the latest diagnostics:

terminal
```
curl 'http://127.0.0.1:5160/api/v1/apps/my_app/setup-log?workspace_id=workspace-1'
```
```

--------------------------------

### Install App Dependencies

Source: https://www.holaos.ai/docs/build/apps

Navigate to your App's directory and run `npm install` to set up the necessary project dependencies.

```bash
cd apps/my_app
npm install
```

--------------------------------

### Workspace Configuration Example

Source: https://www.holaos.ai/docs/contribute/runtime/run-compilation

Example of a workspace.yaml file defining agent, application, and MCP registry configurations.

```yaml
# workspace.yaml
template_id: social_operator
name: Social Operator
agents:
  id: workspace.general
  model: gpt-4o
applications:
  - app_id: holaposter-ts-lite
    config_path: apps/holaposter-ts-lite/app.runtime.yaml
mcp_registry:
  allowlist:
    tool_ids:
      - holaposter.create_post
  servers:
    holaposter:
      type: remote
      url: "http://localhost:3099/mcp"
      enabled: true

```

--------------------------------

### Install holaOS Desktop from Source

Source: https://www.holaos.ai/docs/getting-started/quick-start

Use these commands to clone the repository, install dependencies, and run the desktop application in development mode. Requires git, node 22+, and npm.

```bash
git clone https://github.com/holaboss-ai/holaOS.git
cd holaOS
npm run desktop:install
cp desktop/.env.example desktop/.env
npm run desktop:prepare-runtime:local
npm run desktop:dev
```

--------------------------------

### Verify Prerequisites for Manual Install

Source: https://www.holaos.ai/docs/contribute/start-developing/from-source

Check if git, node (version 22+), and npm are installed and meet the version requirements for manual installation.

```bash
git --version
node --version
npm --version
```

--------------------------------

### Install and Build Runtime Packages

Source: https://www.holaos.ai/docs/contribute/start-developing

Commands to install, build, and type-check individual runtime packages. Use these before running `npm run runtime:test` for comprehensive runtime verification.

```bash
npm run runtime:state-store:install
npm run runtime:state-store:build
npm run runtime:harness-host:install
npm run runtime:harness-host:build
npm run runtime:api-server:install
npm run runtime:api-server:build
npm run runtime:state-store:typecheck
npm run runtime:harness-host:typecheck
npm run runtime:api-server:typecheck
npm run runtime:test
```

--------------------------------

### Install and Run Holaboss Runtime on Linux

Source: https://www.holaos.ai/docs/contribute/runtime/independent-deploy

Installs the Holaboss runtime on Linux by creating directories, extracting the archive, and setting up a symbolic link. It then starts the runtime with specific environment variables for configuration.

```bash
sudo mkdir -p /opt/holaboss
sudo tar -C /opt/holaboss -xzf holaboss-runtime-linux.tar.gz
sudo ln -sf /opt/holaboss/runtime-linux/bin/sandbox-runtime /usr/local/bin/holaboss-runtime
sudo mkdir -p /var/lib/holaboss

HB_SANDBOX_ROOT=/var/lib/holaboss \
SANDBOX_AGENT_BIND_HOST=127.0.0.1 \
SANDBOX_AGENT_BIND_PORT=8080 \
SANDBOX_AGENT_HARNESS=pi \
HOLABOSS_RUNTIME_WORKFLOW_BACKEND=remote_api \
HOLABOSS_RUNTIME_DB_PATH=/var/lib/holaboss/state/runtime.db \
PROACTIVE_ENABLE_REMOTE_BRIDGE=1 \
PROACTIVE_BRIDGE_BASE_URL=https://your-bridge.example \
holaboss-runtime
```

--------------------------------

### Install and Run Holaboss Runtime on Windows

Source: https://www.holaos.ai/docs/contribute/runtime/independent-deploy

Installs the Holaboss runtime on Windows by creating a directory, extracting the zip archive, and setting environment variables. It then starts the runtime using its command-line interface.

```powershell
New-Item -ItemType Directory -Force C:\holaOS | Out-Null
Expand-Archive -Path .\holaboss-runtime-windows.zip -DestinationPath C:\holaOS -Force

$env:HB_SANDBOX_ROOT="$env:LOCALAPPDATA\holaboss"
$env:SANDBOX_AGENT_BIND_HOST="127.0.0.1"
$env:SANDBOX_AGENT_BIND_PORT="8080"
$env:SANDBOX_AGENT_HARNESS="pi"
$env:HOLABOSS_RUNTIME_WORKFLOW_BACKEND="remote_api"
$env:HOLABOSS_RUNTIME_DB_PATH="$env:LOCALAPPDATA\holaboss\state\runtime.db"
$env:PROACTIVE_ENABLE_REMOTE_BRIDGE="1"
$env:PROACTIVE_BRIDGE_BASE_URL="https://your-bridge.example"

C:\holaOS\runtime-windows\bin\sandbox-runtime.cmd
```

--------------------------------

### Curl Command for Setup Logs

Source: https://www.holaos.ai/docs/build/apps/first-app

Use this `curl` command to retrieve setup diagnostics if your app fails during the setup phase. Replace `workspace-1` with your actual workspace ID.

```bash
curl \
  'http://127.0.0.1:5160/api/v1/apps/my_app/setup-log?workspace_id=workspace-1'
```

--------------------------------

### Install Desktop Dependencies

Source: https://www.holaos.ai/docs/contribute/start-developing/from-source

Install the necessary Node.js dependencies for the desktop application after cloning the repository.

```bash
npm run desktop:install
```

--------------------------------

### Example Instruction with Quoted Skills

Source: https://www.holaos.ai/docs/concepts/agent-harness/skills-usage

Illustrates how an instruction can begin with slash-prefixed skill IDs to reference specific skills. The runtime prepares these skills before the harness host request is built.

```plaintext
/customer_lookup
/sales_policy

Review this lead and draft next-step guidance.
```

--------------------------------

### Install and Run Holaboss Runtime on macOS

Source: https://www.holaos.ai/docs/contribute/runtime/independent-deploy

Installs the Holaboss runtime on macOS by creating directories, extracting the archive, and setting up a symbolic link. It then starts the runtime with specific environment variables for configuration, using a user-specific directory for the sandbox root.

```bash
sudo mkdir -p /opt/holaboss
sudo tar -C /opt/holaboss -xzf holaboss-runtime-macos.tar.gz
sudo ln -sf /opt/holaboss/runtime-macos/bin/sandbox-runtime /usr/local/bin/holaboss-runtime
mkdir -p "$HOME/Library/Application Support/HolabossRuntime"

HB_SANDBOX_ROOT="$HOME/Library/Application Support/HolabossRuntime" \
SANDBOX_AGENT_BIND_HOST=127.0.0.1 \
SANDBOX_AGENT_BIND_PORT=8080 \
SANDBOX_AGENT_HARNESS=pi \
HOLABOSS_RUNTIME_WORKFLOW_BACKEND=remote_api \
HOLABOSS_RUNTIME_DB_PATH="$HOME/Library/Application Support/HolabossRuntime/state/runtime.db" \
PROACTIVE_ENABLE_REMOTE_BRIDGE=1 \
PROACTIVE_BRIDGE_BASE_URL=https://your-bridge.example \
holaboss-runtime
```

--------------------------------

### Runtime API Endpoints for App Management

Source: https://www.holaos.ai/docs/build/apps

A reference of common runtime API endpoints used for managing Apps, including setup, start, status polling, log retrieval, and installation.

```bash
POST /api/v1/apps/:appId/setup
POST /api/v1/apps/:appId/start
GET /api/v1/apps/:appId/build-status
GET /api/v1/apps/:appId/setup-log
GET /api/v1/apps/ports
POST /api/v1/apps/install
POST /api/v1/apps/install-archive
```

--------------------------------

### Full App Runtime YAML Example

Source: https://www.holaos.ai/docs/build/apps/app-runtime-yaml

A comprehensive example of an app.runtime.yaml file, detailing lifecycle commands, health check configurations, MCP settings, environment contracts, and integration declarations.

```yaml
app_id: "my_app"
name: "My App"
slug: "my-app"

lifecycle:
  setup: "npm install"
  start: "npm run start"
  stop: "pkill -f my-app || true"

healthchecks:
  mcp:
    path: /mcp/health
    timeout_s: 30
    interval_s: 5

mcp:
  transport: http-sse
  port: 13100
  path: /mcp/sse
  tools:
    - create_record

env_contract:
  - HOLABOSS_WORKSPACE_ID

integrations:
  - key: primary_google
    provider: google
    capability: gmail
    scopes:
      - https://www.googleapis.com/auth/gmail.modify
    required: true
    credential_source: platform
    holaboss_user_id_required: true
```

--------------------------------

### Create Local Environment File

Source: https://www.holaos.ai/docs/contribute/start-developing/from-source

Copy the example environment file to create a local configuration for the desktop application. This is required for `npm run desktop:dev` to pass preflight checks.

```bash
cp desktop/.env.example desktop/.env
```

--------------------------------

### Fetch App Setup Diagnostics

Source: https://www.holaos.ai/docs/build/apps

If an App's setup fails, retrieve detailed diagnostics using the provided `curl` command, specifying the App ID and workspace ID.

```bash
curl 'http://127.0.0.1:5160/api/v1/apps/my_app/setup-log?workspace_id=workspace-1'
```

--------------------------------

### Runtime-tool Request Metadata Example

Source: https://www.holaos.ai/docs/contribute/runtime/apis

Demonstrates how to use turn-aware headers to associate tool mutations with the current run. This is crucial for persisting outputs with stable session and input context.

```bash
curl -X POST http://127.0.0.1:5160/api/v1/capabilities/runtime-tools/reports \
  -H 'x-holaboss-workspace-id: workspace-1' \
  -H 'x-holaboss-session-id: session-main' \
  -H 'x-holaboss-input-id: input-1' \
  -H 'x-holaboss-selected-model: openai_direct/gpt-5.4' \
  -H 'content-type: application/json' \
  -d '{
    "title": "Tariff update brief",
    "filename": "tariff-update-brief",
    "summary": "Short research brief on current tariff developments.",
    "content": "# Tariff update brief\n\n- Court challenges are active.\n- Consumer impact remains debated.\n"
  }'
```

--------------------------------

### Application Runtime Configuration Example

Source: https://www.holaos.ai/docs/contribute/runtime/run-compilation

Example of an app.runtime.yaml file specifying health checks, MCP transport, and environment contracts.

```yaml
# apps/holaposter-ts-lite/app.runtime.yaml
app_id: holaposter-ts-lite
healthchecks:
  mcp:
    path: /mcp/health
    timeout_s: 60
    interval_s: 5
mcp:
  transport: http-sse
  port: 3099
  path: /mcp
env_contract:
  - HOLABOSS_USER_ID

```

--------------------------------

### Write Report Example

Source: https://www.holaos.ai/docs/contribute/runtime/apis

Example of how to use the write_report runtime tool to persist outputs with stable session and input context.

```APIDOC
## POST /api/v1/capabilities/runtime-tools/reports

### Description
This endpoint is used by runtime tools to write reports with associated metadata.

### Method
POST

### Endpoint
/api/v1/capabilities/runtime-tools/reports

### Headers
- **x-holaboss-workspace-id** (string) - Required - The ID of the workspace.
- **x-holaboss-session-id** (string) - Required - The ID of the current session.
- **x-holaboss-input-id** (string) - Required - The ID of the current input.
- **x-holaboss-selected-model** (string) - Required - The selected model used for the operation.

### Request Body
- **title** (string) - Required - The title of the report.
- **filename** (string) - Required - The filename for the report.
- **summary** (string) - Optional - A summary of the report.
- **content** (string) - Required - The content of the report.

### Request Example
```curl
curl -X POST http://127.0.0.1:5160/api/v1/capabilities/runtime-tools/reports \
  -H 'x-holaboss-workspace-id: workspace-1' \
  -H 'x-holaboss-session-id: session-main' \
  -H 'x-holaboss-input-id: input-1' \
  -H 'x-holaboss-selected-model: openai_direct/gpt-5.4' \
  -H 'content-type: application/json' \
  -d '{
    "title": "Tariff update brief",
    "filename": "tariff-update-brief",
    "summary": "Short research brief on current tariff developments.",
    "content": "# Tariff update brief\n\n- Court challenges are active.\n- Consumer impact remains debated.\n"
  }'
```

### Response
#### Success Response (200)
(No specific response schema provided in the source, but typically would indicate success or return the created report metadata.)

#### Response Example
(No example provided in the source.)
```

--------------------------------

### Workspace YAML Configuration Example

Source: https://www.holaos.ai/docs/concepts/workspace-model

Demonstrates how to configure remote MCP servers and their headers, including the use of environment variable placeholders for sensitive information.

```yaml
headers:
  CONTEXT7_API_KEY: "{env:CONTEXT7_API_KEY}"
```

```yaml
headers:
  CONTEXT7_API_KEY: "ctx7sk-..."
```

```yaml
headers:
  CONTEXT7_API_KEY: "{env:ctx7sk-...}"
```

--------------------------------

### Desktop Dev Predev Steps

Source: https://www.holaos.ai/docs/contribute/start-developing

Illustrates the sequence of commands executed by `npm run desktop:dev` before Electron starts. Includes validation, native module rebuilding, and runtime bundle refreshing.

```bash
npm run desktop:dev
# root wrapper -> npm --prefix desktop run dev
# desktop predev validates env, rebuilds native modules, and refreshes the staged runtime bundle first
```

--------------------------------

### One-line Install holaOS Desktop

Source: https://www.holaos.ai/docs/contribute/start-developing/from-source

Use this command for a fresh bootstrap on macOS, Linux, or WSL. It installs prerequisites, clones the repo, sets up the environment, and launches the desktop dev environment.

```bash
curl -fsSL https://raw.githubusercontent.com/holaboss-ai/holaOS/main/scripts/install.sh | bash -s -- --launch
```

--------------------------------

### Install Bridge SDK

Source: https://www.holaos.ai/docs/build/apps/bridge-sdk

Instructions for installing the Bridge SDK using npm. The package currently targets Node.js 20+.

```APIDOC
## Install
```
npm install @holaboss/bridge
```
```

--------------------------------

### Example runtime-config.json for Product-Backed Standalone Runtime

Source: https://www.holaos.ai/docs/contribute/runtime/independent-deploy

This JSON configuration is representative for a standalone runtime operating in a product-backed mode. It specifies default models, provider configurations, and integration details like authentication tokens and user IDs.

```json
{
  "runtime": {
    "mode": "product",
    "default_model": "openai/gpt-5.4",
    "default_provider": "holaboss_model_proxy"
  },
  "integrations": {
    "holaboss": {
      "enabled": true,
      "auth_token": "hbrt.v1.your-runtime-token",
      "user_id": "user_123",
      "sandbox_id": "sandbox_123"
    }
  },
  "providers": {
    "holaboss_model_proxy": {
      "kind": "holaboss_proxy",
      "base_url": "https://runtime.example/api/v1/model-proxy"
    }
  }
}
```

--------------------------------

### Clone holaOS Repository

Source: https://www.holaos.ai/docs/contribute/start-developing/from-source

Initial step for manual installation: clone the holaOS repository and navigate into the cloned directory.

```bash
git clone https://github.com/holaboss-ai/holaOS.git
cd holaOS
```

--------------------------------

### Install @holaboss/bridge

Source: https://www.holaos.ai/docs/build/apps/bridge-sdk

Install the Bridge SDK package using npm. The package currently targets Node.js 20+.

```bash
npm install @holaboss/bridge
```

--------------------------------

### Build App Resource Presentation

Source: https://www.holaos.ai/docs/build/apps/bridge-sdk

Use this when an output or artifact should reopen a specific app view. The helper normalizes the path to always start with '/'.

```typescript
import { buildAppResourcePresentation } from "@holaboss/bridge";

const presentation = buildAppResourcePresentation({
  view: "posts",
  path: "posts/post-123",
});
```

--------------------------------

### Integration Declaration Example

Source: https://www.holaos.ai/docs/build/apps/app-runtime-yaml

Specifies how an application integrates with external services, including the key, provider, capability, required scopes, and credential source.

```yaml
integrations:
  - key: primary_google
    provider: google
    capability: gmail
    scopes:
      - https://www.googleapis.com/auth/gmail.modify
    required: true
    credential_source: platform
    holaboss_user_id_required: true
```

--------------------------------

### Start Desktop App Development

Source: https://www.holaos.ai/docs/contribute/start-developing/from-source

Launch the holaOS Desktop application in development mode. This command includes validation, native module rebuilding, and ensures a staged runtime bundle exists.

```bash
npm run desktop:dev
```

--------------------------------

### Reinstall and Build App in Isolated Environment

Source: https://www.holaos.ai/docs/build/apps/troubleshooting

Use this command to resolve app setup failures within isolated environments or containers, often caused by overlay filesystem conflicts. Ensure node_modules are removed before reinstalling.

```bash
rm -rf node_modules && npm install --maxsockets 1 && npm run build
```

--------------------------------

### Runtime Bootstrap and Session Management

Source: https://www.holaos.ai/docs/contribute/agent-harness/internals

Files related to runtime bootstrap, session reuse, quoted skill preparation, and the order of preparation steps. Start here if changing these functionalities.

```typescript
`runtime/api-server/src/ts-runner.ts`
```

--------------------------------

### Runtime Agent Tool Configuration

Source: https://www.holaos.ai/docs/contribute/agent-harness/internals

Configuration files for prompt layers, capability policy, and response-delivery guidance. Start here if changing these aspects.

```typescript
`runtime/api-server/src/agent-runtime-config.ts` and `runtime/api-server/src/agent-runtime-prompt.ts`
```

--------------------------------

### Conventional Commit Example

Source: https://www.holaos.ai/docs/contribute/start-developing/contributing

Follow this structure for commits, including a clear subject, a blank line, and a bulleted list detailing the changes and validation steps.

```bash
feat: add reasoning effort selection across desktop and runtime

- add catalog-driven reasoning metadata to desktop model configuration
- pass thinking_value through queued inputs and the reduced harness request
- map provider-native reasoning values onto the harness runtime config
- Validation: npm run desktop:typecheck; npm run runtime:test; npm run docs:test
```

--------------------------------

### CLI Claim Inputs Example

Source: https://www.holaos.ai/docs/contribute/runtime/state-store

Shows how to use the `holaboss-state-store` CLI to claim inputs, including setting database and workspace paths, concurrency limits, and distinct session behavior. The request is base64 encoded.

```bash
REQ='{"options":{"dbPath":"/tmp/runtime.db","workspaceRoot":"/tmp/workspace"},"claimed_by":"worker-1","limit":2,"lease_seconds":60,"distinct_sessions":true}'
holaboss-state-store claim-inputs --request-base64 "$(printf '%s' "$REQ" | base64 | tr -d '\n')"
```

--------------------------------

### Skill Markdown Structure

Source: https://www.holaos.ai/docs/build/templates/first-template

Example of a Skill's markdown file, including frontmatter with name and description, and the main body outlining steps. The 'description' field is crucial for agent triggering.

```markdown
---
name: weekly-linkedin-plan
description: Use when the user wants a week's worth of LinkedIn content planned from a single launch, announcement, or research update.
---

# Steps
1. Identify the anchor event and the 3–5 angles worth posting about.
2. Draft one post per angle, staggered across the week...

```

--------------------------------

### Runtime Configuration JSON Example

Source: https://www.holaos.ai/docs/contribute/desktop/model-configuration

This JSON defines the runtime configuration for HolaOS Desktop, including default providers, models, and specific settings for background tasks, image generation, and recall embeddings. It also specifies provider details and model mappings.

```json
{
  "runtime": {
    "default_provider": "openai_direct",
    "default_model": "openai/gpt-5.4",
    "background_tasks": {
      "provider": "openai_direct",
      "model": "gpt-5.4"
    },
    "image_generation": {
      "provider": "openai_direct",
      "model": "gpt-image-1.5"
    },
    "recall_embeddings": {
      "provider": "openai_direct",
      "model": "text-embedding-3-small"
    }
  },
  "providers": {
    "openai_direct": {
      "kind": "openai_compatible",
      "base_url": "https://api.openai.com/v1",
      "api_key": "sk-your-openai-key"
    },
    "anthropic_direct": {
      "kind": "anthropic_native",
      "base_url": "https://api.anthropic.com",
      "api_key": "sk-ant-your-anthropic-key"
    },
    "openrouter_direct": {
      "kind": "openrouter",
      "base_url": "https://openrouter.ai/api/v1",
      "api_key": "sk-or-your-openrouter-key"
    },
    "gemini_direct": {
      "kind": "openai_compatible",
      "base_url": "https://generativelanguage.googleapis.com/v1beta/openai",
      "api_key": "AIza-your-gemini-api-key"
    },
    "ollama_direct": {
      "kind": "openai_compatible",
      "base_url": "http://localhost:11434/v1",
      "api_key": "ollama"
    }
  },
  "models": {
    "openai_direct/gpt-5.4": {
      "provider": "openai_direct",
      "model": "gpt-5.4"
    },
    "openai_direct/gpt-5.3-codex": {
      "provider": "openai_direct",
      "model": "gpt-5.3-codex"
    },
    "anthropic_direct/claude-sonnet-4-6": {
      "provider": "anthropic_direct",
      "model": "claude-sonnet-4-6"
    },
    "openrouter_direct/openai/gpt-5.4": {
      "provider": "openrouter_direct",
      "model": "openai/gpt-5.4"
    },
    "gemini_direct/gemini-2.5-flash": {
      "provider": "gemini_direct",
      "model": "gemini-2.5-flash"
    },
    "ollama_direct/llama3.1:8b": {
      "provider": "ollama_direct",
      "model": "llama3.1:8b"
    }
  }
}
```

--------------------------------

### Control App Lifecycle via Runtime API

Source: https://www.holaos.ai/docs/build/apps

Interact with the holaOS runtime to manage your App's lifecycle. Use `POST` requests to trigger setup and start commands, and `GET` requests to poll build status or retrieve logs.

```bash
# Run lifecycle.setup
curl -X POST http://127.0.0.1:5160/api/v1/apps/my_app/setup

# Run lifecycle.start
curl -X POST http://127.0.0.1:5160/api/v1/apps/my_app/start

# Poll build status
curl http://127.0.0.1:5160/api/v1/apps/my_app/build-status

# See the resolved port map
curl http://127.0.0.1:5160/api/v1/apps/ports
```

--------------------------------

### Prepare Published Runtime Bundle

Source: https://www.holaos.ai/docs/contribute/start-developing/from-source

Use this command to prepare the desktop application against the latest published runtime bundle, instead of the local runtime code.

```bash
npm run desktop:prepare-runtime
```

--------------------------------

### Prepare Local Runtime Bundle

Source: https://www.holaos.ai/docs/contribute/start-developing/from-source

Build the local runtime bundle for active development against the current OSS runtime code.

```bash
npm run desktop:prepare-runtime:local
```

--------------------------------

### Build Linux Runtime Bundle

Source: https://www.holaos.ai/docs/contribute/runtime/independent-deploy

Use this script to package the runtime for Linux. The output is a gzipped tarball.

```bash
bash runtime/deploy/package_linux_runtime.sh out/runtime-linux
tar -C out -czf out/holaboss-runtime-linux.tar.gz runtime-linux
```

--------------------------------

### Build macOS Runtime Bundle

Source: https://www.holaos.ai/docs/contribute/runtime/independent-deploy

Use this script to package the runtime for macOS. The output is a gzipped tarball.

```bash
bash runtime/deploy/package_macos_runtime.sh out/runtime-macos
tar -C out -czf out/holaboss-runtime-macos.tar.gz runtime-macos
```

--------------------------------

### Build Windows Runtime Bundle

Source: https://www.holaos.ai/docs/contribute/runtime/independent-deploy

Use these commands to package the runtime for Windows. The Node.js script builds the bundle, and PowerShell compresses it into a zip archive. The Node.js script must be run on a Windows host.

```javascript
node runtime/deploy/package_windows_runtime.mjs out/runtime-windows
```

```powershell
powershell -Command "Compress-Archive -Path out/runtime-windows -DestinationPath out/holaboss-runtime-windows.zip -Force"
```

--------------------------------

### Work on Runtime Packages Directly

Source: https://www.holaos.ai/docs/contribute/start-developing

Use these commands to exercise runtime packages directly from the `runtime/` directory without launching Electron. Suitable for working on specific runtime components.

```bash
npm run runtime:api-server:test
```

```bash
npm run runtime:harness-host:test
```

```bash
npm run runtime:state-store:test
```

```bash
npm run runtime:test
```

--------------------------------

### Build App Resource Presentation

Source: https://www.holaos.ai/docs/build/apps/publishing-outputs

Use `buildAppResourcePresentation` to attach a stable presentation shape to an output or artifact, enabling it to reopen a specific app resource. The helper normalizes the `path` to always start with `/`.

```typescript
import { buildAppResourcePresentation } from "@holaboss/bridge";

const presentation = buildAppResourcePresentation({
  view: "drafts",
  path: `/drafts/${draft.id}`,
});
```

--------------------------------

### Model Catalog Entry Example

Source: https://www.holaos.ai/docs/contribute/desktop/internals

Defines the structure for a model entry in the catalog, including its ID, reasoning capabilities, available thinking values, default thinking value, and supported input modalities.

```javascript
const entry = {
  model_id: "gpt-5.4",
  reasoning: true,
  thinking_values: ["none", "low", "medium", "high", "xhigh"],
  default_thinking_value: "medium",
  input_modalities: ["text", "image"],
};
```

--------------------------------

### Set Operator Surface Context

Source: https://www.holaos.ai/docs/contribute/desktop/internals

Reports non-browser operator surface context from the renderer to the main process. The runtime later reads this context via a GET request to the browser operator surface context API.

```typescript
await window.electronAPI.workspace.setOperatorSurfaceContext(
  workspaceId,
  reportedOperatorSurfaceContext,
);
```

--------------------------------

### Add New Harness Path - Runtime Adapter

Source: https://www.holaos.ai/docs/contribute/agent-harness/internals

Add a new runtime adapter under `runtime/harnesses/src/` that declares capabilities and a runner prep plan. This is the first step in adding a new harness path.

```typescript
`runtime/harnesses/src/`
```