Build a runtime

In HCP the harness is the runtime. Whatever already drives the agent loads packs, enforces grants, mints Binding and runs Adapters, so there is no separate server to host and no daemon to keep alive. Start on the reference TypeScript SDK below, or build in any language against the contract and prove it with the conformance vectors.

Start with the reference SDK#

The reference runtime is @harnesscontextprotocol/runtime, the Hcp class (also at @harnesscontextprotocol/sdk/runtime). It is file-backed, in-process and local, takes pack directories, a Principal and grants with nothing else implicit, and exists so the protocol runs from day one and the conformance vectors have something to run against.

@harnesscontextprotocol:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

bun add @harnesscontextprotocol/runtime
bun add @harnesscontextprotocol/sdk
bun add -g @harnesscontextprotocol/cli

import { Hcp } from '@harnesscontextprotocol/runtime'

const hcp = await Hcp.create({
  packDirs: ['./packs/transit', './packs/ledger'],
  sandbox: true,                        // default posture
  allowBins: ['transit', 'ledger'],     // wrap bins the sandbox may spawn
  principal: { id: 'user_42', kind: 'human' },
  tenant_id: 'acme',
  project_id: null,                     // required only for land: brain
  grants: [
    { capability: 'verb.exec.read',  pack_id: 'transit' },
    { capability: 'verb.exec.read',  pack_id: 'ledger' },
    { capability: 'verb.exec.write', pack_id: 'ledger', verb_keys: ['transfer'] },
    { capability: 'pack.connect',    pack_id: 'ledger' },
  ],
})

await hcp.activate(['transit', 'ledger'])
await hcp.connect('ledger')                    // Binding mint; skipped for public packs

const read = await hcp.exec('transit', 'plan', { from: 'A', to: 'B' })
// { ok: true, pack_id: 'transit', verb_key: 'plan', result: {…} }

const denied = await hcp.exec('ledger', 'transfer', { amount: 10 })
// { ok: false, error: 'confirm required' }

const ok = await hcp.exec('ledger', 'transfer', { amount: 10, confirm: true })
// { ok: true, … }

import { buildPackAvailability } from '@harnesscontextprotocol/sdk'

for (const pack of await hcp.listPacks()) {
  const report = buildPackAvailability({
    pack,
    installed: true,
    activated: hcp.activatedPacks().includes(pack.pack_id),
    connected: false,
    grants: hcp.authz.grants,
  })
  // report.verbs[i] → { verb_key, operation, land, executable, reason? }
}

The contract#

A conforming runtime does these ten things, each in whatever way it chooses. Every exec passes them in the order of the pipeline, and any step may deny.

A runtime implements the protocol, stores and runs packs, and enforces their Policy. It must not:

• Add its own Policy rows, override a pack's, or rewrite a pack.
• Extend the protocol's types (a "Connector", another land, a new capability) without an RFC.
• Fall back to environment tokens when mint fails.
• Collapse read, write and connect into one boolean in a multi-tenant product.
• Let an end-user Principal reach a mothership Binding without an explicit elevation grant.
• Treat polling as Sense, or deliver undeclared triggers.

Drivers#

Hcp is a thin front over an HcpRuntimeDriver, a small interface with listPacks, getPack, exec and an optional connect. Two drivers ship, and your own implements the same interface:

Proprietary runtimes#

The pack format is open and a runtime does not have to be, so a company can put HCP in a real product without publishing its internals while its packs stay portable. HCP needs no public network "HCP server", because remote transport is a runtime choice and the protocol defines no server role, and no registry, since a local directory install is enough for HCP/1.x. Harnesses see only activate, connect, exec, the Skill and optional Sense.

None of these is an HCP type, and you never publish ACL tables, catalog schema or hub internals. The protocol fixes what keeps packs portable:

Your runtime is an HcpRuntimeDriver:

import type { HcpRuntimeDriver, HcpAuthzContext } from '@harnesscontextprotocol/sdk'

export function createAcmeRuntime(deps: { catalog: Catalog; hub: Hub; rbac: Rbac; audit: Audit }): HcpRuntimeDriver {
  return {
    id: 'acme',
    kind: 'proprietary',

    listPacks: () => deps.catalog.list(),
    getPack:   (id) => deps.catalog.get(id),

    async connect(pack_id, authz) {
      if (!deps.rbac.has(authz, 'pack.connect', pack_id)) return { ok: false, error: 'denied: missing pack.connect' }
      return deps.hub.connect(pack_id, authz.principal)
    },

    async exec({ pack_id, verb_key, args = {}, authz, sandbox }) {
      const pack = await deps.catalog.get(pack_id)
      if (!pack) return { ok: false, pack_id, verb_key, error: `unknown pack ${pack_id}` }
      const policy = pack.policy.verbs[verb_key]
      if (!policy) return { ok: false, pack_id, verb_key, error: `no policy for ${verb_key}` }

      const cap = policy.operation === 'write' ? 'verb.exec.write' : 'verb.exec.read'
      if (!deps.rbac.has(authz, cap, pack_id, verb_key)) return { ok: false, pack_id, verb_key, error: `denied: missing ${cap} for ${pack_id}.${verb_key}` }
      if (policy.privacy.land === 'brain' && !authz.project_id) return { ok: false, pack_id, verb_key, error: 'denied: privacy.land brain requires project_id' }
      if (policy.confirm && args.confirm !== true && args.apply !== true) return { ok: false, pack_id, verb_key, error: 'confirm required' }

      const cred = await deps.hub.mint(pack, authz)          // fail closed inside
      const result = await runAdapter(pack, verb_key, args, cred, sandbox)
      if (policy.operation === 'write') await deps.audit.write({ authz, pack_id, verb_key, binding: cred.identity })
      return result
    },
  }
}

const hcp = await Hcp.create({ runtime: createAcmeRuntime(deps), grants: [] })

createProprietaryStubRuntime is an in-memory version of this shape, so you can test multi-runtime behaviour before your real dependencies exist. A company runtime meets the same contract: a private catalog is fine, the JSON face of the exec envelope is required and the CLI face only if you expose one, and the five capability axes are the minimum.

Because packs never reference a runtime, the same ledger pack activates on the reference-local runtime in CI, a developer's desktop in native-local, and a company runtime in production, with the same Skill, Policy and commands. Only the hub that mints and the RBAC that grants differ.

Related#

• Implementations
• Specification: Conformance