Platform Contract¶

A research platform can embed Heartwood as its research interaction layer without handing Heartwood its compute, identity, storage, or inference infrastructure. This contract defines that boundary: what Heartwood owns, what the platform owns, what a platform provides for each capability, and the security properties both sides must preserve. Use it to scope a platform integration, to review one, and as the list of what Heartwood asks a platform to provide.

Contract at a Glance¶

The Boundary¶

Heartwood owns the research session. The platform owns the infrastructure and the authority to use it.

flowchart TB
    Researcher(["Researcher"])
    Identity["Platform: identity and project access"]
    Proxy["Platform: authenticated proxy"]
    Gateway["Heartwood: gateway, sessions, reviewed commands, projections, audit"]
    Agent["Heartwood: OpenHands agent loop and project tools"]
    Inference["Platform: inference endpoint and authorized models"]
    Services["Platform: services for compute, data, and applications"]
    Infrastructure[("Platform: schedulers, storage, entitlements, quotas")]
    Researcher --> Identity --> Proxy --> Gateway --> Agent
    Agent -- "model requests" --> Inference
    Agent -. "reviewed tool calls" .-> Services
    Services -.-> Infrastructure
    classDef heartwood fill:#0b694d26,stroke:#2b8268
    classDef platform fill:#3f5b7426,stroke:#6f8fae
    classDef planned stroke-dasharray: 5 5
    class Gateway,Agent heartwood
    class Identity,Proxy,Inference,Services,Infrastructure platform
    class Services,Infrastructure planned

In the figures on this page, green marks what Heartwood owns, blue marks what the platform owns, and dashed outlines mark what is not yet implemented. Heartwood consumes two independent platform capabilities, inference and platform services, on top of a hosting and access baseline. Either capability can be absent or unavailable without breaking the other: a platform can supply models without services, services without models, or neither while Heartwood runs a standalone model route.

Responsibilities¶

Heartwood still authenticates requests and enforces its own policy inside an authenticated platform. Platform authentication does not replace gateway controls, and a Heartwood approval never grants platform authority.

Deployment Topologies¶

The gateway is the unit of hosting. Only who runs the gateway process, and who authenticates the person in front of it, changes between topologies; the contract below it is the same.

flowchart TB
    subgraph Hosted["Hosted per-project service"]
        direction TB
        H1["Identity provider and spawner"] -.-> H2["Gateway per researcher and project"]
    end
    subgraph Workspace["Platform workspace"]
        direction TB
        P1["Platform proxy authenticates"] --> P2["Gateway in the workspace"]
    end
    subgraph Workstation["Workstation or container"]
        direction TB
        W1["Researcher's own process"] --> W2["Gateway on loopback"]
    end
    classDef heartwood fill:#0b694d26,stroke:#2b8268
    classDef platform fill:#3f5b7426,stroke:#6f8fae
    classDef planned stroke-dasharray: 5 5
    class W2,P2,H2 heartwood
    class P1,H1 platform
    class H1,H2 planned
    style Hosted stroke-dasharray: 5 5

Hosting¶

A platform runs the published Heartwood artifact with the researcher's project as the working directory.

• Required: run the published image or native release without replacing its entrypoint, user, or bundled browser assets.
• Required: provide the project as a persistent directory; .heartwood/ session storage needs native advisory locks, so object-store and file-transfer mounts are not session stores unless qualified.
• Required: keep model weights, credentials, and deployment secrets out of image layers and the project directory.
• Required: run Heartwood-managed local model servers and checkpoint signers only where other operating-system users cannot reach their loopback ports.
• Recommended: back up the project storage and preserve it across compute recreation.
• Optional: provide Jupyter where the platform offers the notebook bridge.
• Recommended: verify the published release attestations before admitting an artifact.

See Package the Shared Application and Persist the Right Data.

Access and Identity¶

The platform authenticates the person; Heartwood authorizes the caller of its own API.

sequenceDiagram
    actor R as Researcher
    participant P as Platform proxy
    participant G as Heartwood gateway
    R->>P: Sign in with platform identity
    P->>P: Authenticate and authorize project access
    alt Launch link
        G-->>R: One-time launch link printed at startup
        R->>P: Open launch link
        P->>G: GET /launch?token=…
        G-->>R: HttpOnly, SameSite=Strict capability cookie
    else Proxy injection
        P->>G: Request with X-Heartwood-Capability
    end
    R->>P: Use Heartwood
    P->>G: Request with capability and validated route metadata
    G->>G: Validate route, capability, and origin

• Required: authenticate every user before traffic reaches the gateway, and restrict the gateway's network route to the platform proxy.
• Required: remove client-supplied forwarding and identity headers before setting the proxy's own values.
• Required: deliver the launch capability, either by letting the researcher open the one-time launch link, or by injecting X-Heartwood-Capability for callers the platform has already authenticated.
• Required: keep the capability away from the agent workspace, other users, and logs.
• Recommended: run one gateway per researcher and project; Heartwood records one launching principal per gateway and does not distinguish people who share it.

A proxy that injects the capability authenticates on the researcher's behalf, so it must inject it only for the one user who owns that gateway. A trusted identity header is an exact route marker, not a credential.

For example, a platform proxy at https://research.example.org that strips the /heartwood/project-a prefix and forwards from 10.0.0.2 starts the gateway with a secret supplied by the platform's secret manager:

HEARTWOOD_GATEWAY_CAPABILITY="$(cat /run/secrets/heartwood-capability)" \
heartwood gateway serve \
  --ingress-mode trusted-proxy \
  --host 10.0.0.5 \
  --port 8767 \
  --public-origin https://research.example.org \
  --base-path /heartwood/project-a \
  --trusted-proxy-source 10.0.0.2/32 \
  --proxy-strips-prefix

The proxy then adds X-Heartwood-Capability with the same secret to each authenticated request. See the serve options and HW-INGRESS-003.

Deployment Policy¶

A platform defines restrictions that every project on it must obey: the model and catalog endpoints a project may reach, the action-review modes it may select, the credential references it may use, and whether egress is denied by default.

• Required: define the policy per platform, deny egress by default, and list exact model and catalog endpoints.
• Required: let researchers narrow the policy for a project, never widen it.
• Recommended: offer Review Every Action as the only review mode for secret-backed or unqualified routes.
• Optional: publish approved Skill sources through the deployment-owned registry at /etc/heartwood/skill-sources.toml; only that registry can approve a Skill for controlled data.

Heartwood builds each platform's default policy in its platform adapter and evaluates model routes, review modes, and credentials against it.

Inference¶

A platform can supply the models a researcher may use, so the researcher chooses a model without entering platform-managed credentials or knowing where it runs.

• Required: an OpenAI-compatible Chat Completions endpoint with streaming and native tool calls.
• Recommended: the Responses API for models that support it; Heartwood selects Chat Completions or Responses per model from the OpenHands model capabilities and does not assume every compatible endpoint implements both.
• Required: a model list endpoint that returns only the models the authenticated identity may use.
• Recommended: report each model's context window, tool-calling support, and permitted data classes.
• Required: keep credentials platform-held, through a managed identity, a process-only variable, or a mounted file outside the project.
• Required: state which data classes each route may receive; Heartwood cannot infer eligibility from compatibility.
• Required: return distinguishable failures for rejected credentials, exhausted quota, rate limits, invalid model configuration, and temporary unavailability.
• Recommended: restrict the workspace's network egress to the approved inference endpoints.
• Optional: provide GPU or CPU compute on which Heartwood runs a Heartwood-managed model when no hosted route is available.
• Optional: for air-gapped platforms, provide an approved process to import verified model bundles.

Heartwood discovers models through a connection's catalog endpoint after checking it against the deny-by-default policy, and it never implements a second provider proxy. It currently consumes platform-managed inference through built-in connections, such as the Stanford AI API Gateway, and through compatible services that an operator configures. A route's credential boundary determines whether actions can run without review; secret-backed routes are application-scrubbed unless the platform demonstrates a platform-isolated boundary, which no current adapter claims.

A platform that describes its models should return this metadata with each entry of its model list:

Realtime Voice¶

A platform can offer realtime speech models for an optional voice interface.

• Required: create realtime sessions on the server side, so no long-lived key reaches the browser.
• Required: state whether realtime audio is covered by the route's data-use agreements; text-route eligibility does not extend to audio.
• Recommended: support a server-owned session in which Heartwood executes and approves every tool call.

Platform Services¶

Platform services let a researcher ask Heartwood to submit an analysis, request compute, attach an authorized dataset, or open a platform application through the research session. Services connect through the Model Context Protocol without a platform-specific agent loop.

Discovery and Authorization¶

• Required: expose services over MCP Streamable HTTP with a stable server identity.
• Required: describe each tool's purpose, input and output schemas, and the permission it requires; read access never implies permission to allocate resources or attach data.
• Required: annotate each tool with the MCP tool annotations readOnlyHint, destructiveHint, idempotentHint, and openWorldHint.
• Required: enforce identity, quotas, and dataset entitlements on every call, independently of Heartwood's approval.
• Required: treat a changed tool set as a new review; discovery does not authorize execution or certify a tool's advertised safety.
• Required: accept delegated or platform-held credentials that never reach model context, tool environments, or exports.

Heartwood treats annotations as hints from the server, not as authorization: a tool marked read-only still runs under Heartwood's review policy, and the platform still authorizes every call.

Operations That Change Platform State¶

A tool that allocates compute, submits work, attaches data, or starts an application is an operation. Each operation follows one lifecycle.

stateDiagram-v2
    [*] --> Proposed
    Proposed --> Denied: researcher rejects or platform refuses
    Proposed --> Submitted: researcher approves
    Submitted --> Running: platform accepts
    Submitted --> Unknown: response lost
    Unknown --> Running: status reconciled
    Unknown --> Completed: status reconciled
    Unknown --> Failed: status reconciled
    Unknown --> Cancelled: status reconciled
    Running --> Completed
    Running --> Failed
    Running --> Cancelled: cancellation observed
    Denied --> [*]
    Completed --> [*]
    Failed --> [*]
    Cancelled --> [*]

sequenceDiagram
    participant A as Agent
    participant G as Heartwood gateway
    actor R as Researcher
    participant S as Platform service
    A->>G: Propose operation
    G->>S: Prepare with operation identifier
    S-->>G: Proposal: limits, duration, cost, data scope, destination
    G->>R: Show proposal for review
    R->>G: Approve
    G->>S: Submit with the same operation identifier
    S->>S: Authorize identity, quota, and entitlements
    S-->>G: Accepted, with operation reference
    loop Until a terminal state
        G->>S: Status by operation identifier
        S-->>G: Running, completed, failed, or cancelled
    end
    G->>A: Result with evidence references

• Required: before approval, return a proposal with the resource limits, expected duration, estimated cost when available, data scope, and destination.
• Required: accept a caller-supplied operation identifier and treat a repeated submission with the same identifier as the same operation.
• Required: report status by operation identifier, so an uncertain outcome is reconciled rather than retried.
• Required: report cancellation as the observed platform result, without promising rollback of completed work.
• Required: return a reference that joins the platform's audit record to Heartwood's session audit without copying data payloads.

Capability Families¶

A platform offers any subset of these families; each is discovered, never assumed.

Heartwood requires none of these standards; the contract is the MCP behavior above, and wrapping an existing standard avoids inventing a new vocabulary. An application opened for the researcher is a hand-off to a person, not an agent action that changes data. A researcher's identity behind delegated calls should come from OpenID Connect.

Controlled Data¶

A platform that admits controlled or regulated data owns that decision and the controls around it.

• Required: decide data eligibility for every model route, dataset, and interface under the platform's agreements.
• Required: provide read-only input snapshots, enforced egress denial, and ephemeral, encrypted execution storage for controlled work.
• Required: keep outputs in quarantine until an authorized data steward approves an exact release manifest.
• Required: report these controls as typed evidence, so Heartwood can refuse to start when a required control is missing.

Heartwood is not a controlled-data boundary on its own; see Security and Controlled Data.

Agent Isolation¶

Every guarantee above assumes agent tools cannot change the controls that govern them.

• Required: keep platform credentials, service tokens, and signer material out of the environment and file system that agent tools can reach.
• Recommended: run agent tools under an identity that can read and write project files but not .heartwood/, the gateway process, credentials, or signer material.
• Recommended: keep the approval-deciding interfaces, the gateway and the researcher's browser, outside the agent's reach.

Agent tools currently run with the gateway's operating-system identity. An approved command can read anything that identity can read and can change .heartwood/ state, including project settings, installed Skills, and session and audit files.

See Threat Boundaries for the current limits.

Audit and Provenance¶

• Recommended: operate a deployment-owned checkpoint signer, installed through /etc/heartwood/checkpoint-signers.toml or HEARTWOOD_CHECKPOINT_SIGNER_REGISTRY, with keys the agent cannot use.
• Recommended: enforce retention, immutability, and deletion for exported audit and experiment records.
• Required for platform services: keep an audit log of operations performed through the contract, joinable to Heartwood's audit by operation reference.

Heartwood's project-local audit and experiment records detect corruption but remain writable by the identity that runs the project. See Audit Checkpoints and Retention and Sessions and Audit.

Security Requirements¶

flowchart TB
    UI["Researcher's browser: Heartwood interface"]
    Proxy["Platform: authenticated proxy"]
    Gateway["Heartwood gateway: capability, policy, approval"]
    Tools["Agent tools: terminal, files, scripts, as the gateway's operating-system user"]
    State[(".heartwood state and project files, writable by that user")]
    Inference["Platform: inference endpoint"]
    Services["Platform: services"]
    UI -- "authenticated, with capability" --> Proxy --> Gateway
    Gateway --> Tools
    Gateway --> State
    Tools -. "same identity" .-> State
    Gateway -- "platform credential" --> Inference
    Gateway -. "reviewed call" .-> Services
    classDef heartwood fill:#0b694d26,stroke:#2b8268
    classDef platform fill:#3f5b7426,stroke:#6f8fae
    classDef planned stroke-dasharray: 5 5
    class UI,Gateway,Tools,State heartwood
    class Proxy,Inference,Services platform
    class Services planned

Both sides must preserve these properties.

1. Agent output cannot grant authority. No model output, tool output, service response, or dataset content can approve an action, widen policy, or grant platform permissions.
2. Approval is necessary, never sufficient. Heartwood approves the exact proposal; the platform still authorizes every call.
3. Secrets stay outside the session. Credentials never appear in project configuration, model context, tool environments, events, logs, or exports.
4. External content is data. Service results, tool descriptions, annotations, and platform responses are untrusted input, bounded in size, and never treated as instructions.
5. Uncertain outcomes are reconciled. A timeout or lost response is resolved by status, not by resubmitting an operation as though it were idempotent.
6. Egress is denied by default. Heartwood policy denies undeclared model endpoints, and the platform network is the authoritative egress control.

Failure States¶

A platform's failures must be distinguishable so every interface can show the same next step.

See Diagnostics and Troubleshooting for each code's recovery steps.

Contract Artifacts¶

A contract a platform can implement against needs exact, versioned artifacts, not only this page.

Validate a Platform¶

A platform integration advances through the evidence levels in Testing and Evidence, and Heartwood advertises a capability only at the level its evidence reaches.

1. Implemented: a platform adapter reports capabilities, detection, and policy, with contract tests.
2. CI validated: adapter conformance, ingress adversarial, credential-boundary, persistence, and interface tests pass in a production-derived image.
3. Live synthetic validated: the published artifact completes a synthetic task on the platform with approval, file verification, replay, and audit export.
4. Institution approved: separate institutional evidence covers the deployment; it is never inferred from the previous levels.

Follow Validate Conformance and Validate the Deployment for the exact checks. Before a wider rollout, record a standard environment, confirm the deployment security checklist, and run a pilot evaluation.

What Heartwood Asks of a Platform¶

Related Pages¶

• Deployment Responsibilities
• Add a Platform
• Security and Controlled Data
• System Architecture
• Product Boundaries