Concepts & Glossary

Core Concepts

Workspace

A bounded, temporary working directory created on the host filesystem at /var/lib/cloud-harness/jobs/<workspaceId>/repo. A workspace hosts a clean clone of the target Git repository and is mounted exclusively into a single executor container.

Executor

The Docker container (cloud-harness-executor:local) executing repository commands on behalf of the workspace. It runs with UID/GID 10001 (harness), preserves strict hardening (--read-only, --cap-drop ALL, --security-opt no-new-privileges), operates across 3 partitioned storage zones (/tmp/cloud-harness-home RAM tmpfs, /opt/user-tools & /var/cache/harness, /workspace), has no Docker socket, lacks host mount access, and is isolated by network namespaces.

Runner

The trusted central daemon (apps/runner) responsible for Docker container lifecycle, SQLite state persistence, GitHub App token brokerage, and audit recording. It is not exposed to the public Internet.

Principal

The authenticated identity invoking MCP tools.

• In Managed OAuth mode, the principal is identified by Cloudflare Access claims (sub, email).
• In Static API Key mode, the principal is identified by the API key record created in the dashboard. Workspaces are strictly isolated between different principals. A single principal may hold several concurrent workspaces at once, up to the instance's configured MAX_ACTIVE_WORKSPACES_PER_OWNER limit (default 3, 1 restores single-workspace behaviour). Each is addressed by its own opaque workspaceId, and once more than one workspace is counted every operation except workspace_list must carry that id (or a workspace_set_active preference) to avoid a CONFLICT ambiguity error.

Idempotency Key

A unique client-generated string (8–128 characters) passed to mutating lifecycle operations such as workspace_open. If network connectivity drops, sending the same idempotency key recovers the existing workspace without repeating the clone operation.

Time-To-Live (TTL)

Every workspace enforces two hard lifetime boundaries:

1. Wall TTL (default 900s / 15 min): The maximum total duration a workspace may exist before automatic termination.
2. Idle TTL (default 300s / 5 min): The maximum period of inactivity between MCP tool calls before cleanup.

Artifact

Output files generated during workspace execution (logs, test reports, build outputs) that exceed inline MCP message bounds or need to survive container termination. Managed under /var/lib/cloud-harness/artifacts.

Sibling Git Transfer Helper

An ephemeral container spawned by the Runner to handle git_fetch, git_pull, and git_push. It mounts the workspace repository as a sibling, receives a 10-minute GitHub App installation token via stdin, talks only to github.com, and is immediately destroyed.

Context Manifest & Provenance

A bounded, vendor-neutral overview of allowlisted instruction files (AGENTS.md, CLAUDE.md, .cursor/rules/*.mdc, .aider.conf.yml), language manifests, and test declarations produced by workspace_context. Every item carries immutable provenance (source, trust, mutableBy, contentSha256, discoveredAt) stamped by the trusted Runner:

• built-in: release-packaged built-ins (trust: trusted-control-plane, mutableBy: release)
• owner: runner-managed principal catalog (trust: owner-controlled, mutableBy: owner)
• workspace: workspace-managed tools overlay (trust: untrusted-executor, mutableBy: workspace-process)
• repository: checkout files (trust: untrusted-executor, mutableBy: repository-commit)

Scoped Memories

Persistent notes stored in SQLite StateStore v5 isolated by principal_id across 3 scopes:

• owner: Principal-wide notes persistent across all workspaces.
• repository: Notes bound to (principal_id, repository_key), persistent across workspaces for the same repository.
• workspace: Notes bound to (principal_id, workspace_id), reaped when the workspace terminates. Enforces Optimistic Concurrency Control via expectedGeneration (CAS: 0 for create, positive integer for update/delete) and automatic TTL cleanup.

Declarative Lifecycle Hooks

Pre-configured automation commands declared in .cloud-harness/hooks.json for named lifecycle events (on_workspace_open, post_checkout, pre_commit, post_commit, manual). Automatic lifecycle execution requires explicit owner activation (hooks_activate) pinned to the manifest SHA-256 digest and runs exclusively inside an unprivileged executor container.

Agent Toolkits

Pre-packaged collections of agent skills (e.g. mattpocock/skills, obra/superpowers, or custom Git repositories) that can be dynamically mounted or staged into a workspace upon creation. Toolkits are resolved across 4 deterministic precedence tiers (built-in > owner > workspace > repository). The default owner scope mounts toolkits read-only at /opt/cloud-harness/owner-skills:ro, keeping git status clean.