Install Harbor SDKs
Install the TypeScript and Python packages for Harbor clients and system integrations.
Harbor keeps the public package surface small: two npm packages and one
Python package. Use @hrbr/client for app code,
@hrbr/sdk for Harbor system surfaces, and
harbor-sdk for Python.
Packages
| Package | Install | Use it for |
|---|---|---|
@hrbr/client | npm install @hrbr/client | Promise-first TypeScript calls to the hosted or local Harbor API. |
@hrbr/sdk | npm install @hrbr/sdk | Composite Harbor contracts, runtime and platform adapters, registry types, and local platform helpers. |
harbor-sdk | python -m pip install harbor-sdk | Sync and async Python clients over the same Harbor protocol. |
The source package repository is github.com/zonko-ai/harbor-sdk. The generated protocol artifacts still come from the main Harbor monorepo, then land in that publish-shaped repository.
Requirements
| Runtime | Requirement |
|---|---|
| TypeScript / JavaScript | Node.js 22 or newer. |
| Effect host code | effect@4.0.0-beta.66 when importing @hrbr/client/effect or Effect-backed @hrbr/sdk surfaces. |
| Python | Python 3.10 or newer. |
TypeScript install
Install the normal application client first:
npm install @hrbr/clientCreate a workspace-scoped client with either a Harbor workspace API key or an application-owned bearer token:
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 health = await harbor.api.getHealth()
const run = await harbor.runtime.execute({
code: 'return "hello from Harbor"',
})
console.log(health.status)
console.log(run.result)Install the composite system SDK when you need Harbor-owned building blocks instead of the app client:
npm install @hrbr/sdkimport { Core, Platform, Plugins, Protocol, Runtime } from '@hrbr/sdk'
import { initLocalProject } from '@hrbr/sdk/platform/local'
const project = initLocalProject({
workspaceId: 'workspace_local',
workspaceName: 'Local SDK Workspace',
authToken: 'local-token',
})
console.log(Core.ROUTES.exec)
console.log(Protocol.harborOpenApiDocument.info.title)
console.log(Runtime.Core.RuntimeExecutionMode)
console.log(Plugins.ToolSearchMode)
console.log(project.workspaceId)Python install
Install the Python package and use the public harbor_sdk facade:
python -m pip install harbor-sdkfrom harbor_sdk import HarborClient
client = HarborClient(
api_key="hrbr_...",
workspace_id="workspace_...",
)
run = client.runtime.execute(code='return "hello from Harbor"')
print(run.result)api_key defaults to HARBOR_API_KEY,
workspace_id defaults to HARBOR_WORKSPACE_ID, and
base_url defaults to https://api.tryharbor.ai.
HARBOR_API_BASE_URL and HARBOR_SDK_BASE_URL can
override the API base URL for local or staging targets.
Pre-release source checkout
Before the packages are published, install from the checkout:
git clone https://github.com/zonko-ai/harbor-sdk.git
cd harbor-sdk
bun install
bun run smoke
bun run python:sdk:testThe Python package can also be installed editable from the checkout:
python3 -m pip install -e packages/python