runtime.execute

The SDK execution method is harbor.runtime.execute. The CLI spelling is hrbr exec, and both submit work to Harbor's execution layer.

TypeScript execution

execute.ts

import { createHarborClient } from '@hrbr/client'

const harbor = createHarborClient({
  baseUrl: 'https://api.tryharbor.ai',
  workspaceId: process.env.HARBOR_WORKSPACE_ID!,
  auth: { kind: 'api_key', key: process.env.HARBOR_API_KEY! },
})

const run = await harbor.runtime.execute({
  code: 'return "hello from Harbor"',
})

console.log(run.result)
console.log(run.run_id)
console.log(run.content?.[0])

Execution requests accept mode, sources, timeout_ms, run_id, sand_session_id, origin_cwd, and execution_inputs in addition to code. The SDK fills workspace_id from the client unless a call supplies one explicitly.

Python execution

execute.py

from harbor_sdk import HarborClient

client = HarborClient(
    api_key="hrbr_...",
    workspace_id="workspace_...",
)

run = client.runtime.execute(code='return "hello from Harbor"')
print(run.result)
print(run.run_id)

Async Python hosts use AsyncHarborClient:

async-execute.py

from harbor_sdk import AsyncHarborClient

client = AsyncHarborClient(
    api_key="hrbr_...",
    workspace_id="workspace_...",
)

run = await client.runtime.execute(code='return "hello from Harbor"')

Content blocks

The raw result preserves the JSON-compatible value returned by the executed code. content is the language-friendly view used by TypeScript and Python callers:

Content type	Field	Use
`text`	`text`	Returned text, suitable for display or agent context.
`json`	`json` in TypeScript, `json_` in Python	Structured data returned by the execution.
`skill_bundle`	`skill`	Explicit Harbor skill content and attached files.

Skill bundles are never inferred from arbitrary objects. Return the explicit Harbor execution-result envelope when a run should expose a loadable skill:

skill-bundle-result.ts

const skillEnvelopeCode = [
  'return {',
  '  kind: "harbor.execute_result",',
  '  result: "Loaded harbor-example skill",',
  '  content: [{',
  '    type: "skill_bundle",',
  '    skill: {',
  '      slug: "harbor-example",',
  '      content: "---\\nname: harbor-example\\n---\\n# Harbor Example\\n",',
  '      content_hash: "abc123def456",',
  '      files: []',
  '    }',
  '  }]',
  '}',
].join('\n')

const run = await harbor.runtime.execute({
  code: skillEnvelopeCode,
})

for (const block of run.content ?? []) {
  if (block.type === 'text') console.log(block.text)
  if (block.type === 'json') console.log(block.json)
  if (block.type === 'skill_bundle') console.log(block.skill.slug)
}

skill-bundle-result.py

from harbor_sdk import (
    ExecuteResultJsonContent,
    ExecuteResultSkillBundleContent,
    ExecuteResultTextContent,
)

for block in run.content or []:
    if isinstance(block, ExecuteResultTextContent):
        print(block.text)
    elif isinstance(block, ExecuteResultJsonContent):
        print(block.json_)
    elif isinstance(block, ExecuteResultSkillBundleContent):
        print(block.skill.slug)

Local platform target

@hrbr/sdk/platform/local can host Harbor-compatible routes for local development. Point @hrbr/client at the printed local server URL:

local-platform.ts

import { createHarborClient } from '@hrbr/client'
import { Effect } from 'effect'
import { initLocalProject, startLocalHarborServer } from '@hrbr/sdk/platform/local'

const project = initLocalProject({
  workspaceId: 'workspace_local',
  workspaceName: 'Local SDK Workspace',
  authToken: 'local-token',
})

const server = await startLocalHarborServer({
  project,
  authToken: 'local-token',
  runtimeHost: (invocation) =>
    Effect.succeed({
      mode: invocation.request.mode,
      result: { ok: true, scopeId: invocation.context.scopeId },
      logs: [],
      warnings: [],
      timings: {},
    }),
})

const localHarbor = createHarborClient({
  baseUrl: server.url,
  workspaceId: 'workspace_local',
  auth: { kind: 'bearer', token: 'local-token' },
})

await localHarbor.runtime.execute({ code: 'return { ok: true }' })

Tool discovery

Search and inspect tool schemas before executing code.

Runs and invocations

Query runs, artifacts, job invocations, and app invocations.