opentool-daemon-client

TypeScript SDK for talking to a locally running opentoold daemon.

This package is a pure client library with no runtime dependencies. It does not bundle or start the daemon. You must have opentoold already running on the local machine.

Install

npm install opentool-daemon-client

Runtime

• Node.js 18+
• The local daemon defaults to http://127.0.0.1:19627/opentool-daemon

Quick Start

import { DaemonClient } from "opentool-daemon-client";

const client = new DaemonClient();

// Get daemon version
const version = await client.getVersion();
console.log(version.name, version.version);

// List running tools
const tools = await client.listTool();
console.log(tools);

Custom connection

const client = new DaemonClient({
  protocol: "http",
  host: "127.0.0.1",
  port: 19627,
  prefix: "/opentool-daemon",
});

API

Daemon

getVersion(): Promise<VersionDto>

Returns the daemon name and version string.

Hub authentication

loginHub(info: LoginInfoDto): Promise<LoginResultDto>

Log in to the OpenTool Hub registry.

userHub(): Promise<UserInfoDto>

Returns the currently logged-in user info.

logoutHub(): Promise<UserInfoDto>

Log out from the Hub.

API keys (requires sudo token)

createApiKey(params: { sudoToken: string; name?: string }): Promise<ApiKeyDto>

Create a new daemon API key.

listApiKeys(params: { sudoToken: string }): Promise<ApiKeyDto[]>

List all daemon API keys.

deleteApiKey(params: { sudoToken: string; apiKey: string }): Promise<void>

Delete a daemon API key.

Servers

listServer(): Promise<OpenToolServerDto[]>

List all installed servers.

buildServer(info: BuildInfoDto, callbacks): Promise<void>

Build a server image from a local Opentoolfile, streaming build output via SSE.

await client.buildServer(
  { opentoolfile: "./Opentoolfile", name: "my-tool" },
  {
    onStart: (msg) => console.log("Build started:", msg.message),
    onData: (out) => process.stdout.write(out.output),
    onDone: (msg) => console.log("Done:", msg.message),
    onError: (err) => console.error("Stream error:", err),
  },
);

pullServer(info: PullInfoDto, callbacks): Promise<void>

Pull a server image from the registry, streaming download progress.

await client.pullServer(
  { name: "my-tool", tag: "latest" },
  {
    onStart: (data) => console.log(`Pulling ${data.sizeByByte} bytes`),
    onDownload: (data) => console.log(`${data.percent}%`),
    onDone: (info) => console.log("Pull complete:", info.name),
  },
);

pushServer(serverId: string, callbacks): Promise<void>

Push a server image to the registry, streaming upload progress.

deleteServer(serverId: string): Promise<ServerIdDto>

Delete an installed server.

tagServer(serverId: string, tag?: string): Promise<OpenToolServerDto>

Tag a server image.

exportServer(serverId: string, targetPath: string): Promise<ServerIdDto>

Export a server image to a local file path.

importServer(sourcePath: string): Promise<OpenToolServerDto>

Import a server image from a local file path.

setAliasServer(serverId: string, alias?: string): Promise<OpenToolServerDto>

Set or clear the alias for a server.

Tools

listTool(all?: boolean): Promise<ToolDto[]>

List tools. Pass true to include tools from all hosts.

listToolWithApiKeys(all: boolean | undefined, params: { daemonApiKey: string }): Promise<ToolWithApiKeyDto[]>

List tools together with their per-tool API keys. Requires a daemon API key.

subscribeToolEvents(params: { daemonApiKey: string; snapshot?: boolean }): Promise<DaemonSseStream<ToolLifecycleEventDto>>

Subscribe to tool lifecycle events (ready, draining, unavailable, removed) via a persistent SSE stream. Requires a daemon API key.

const stream = await client.subscribeToolEvents({ daemonApiKey: "..." });

for await (const event of stream) {
  console.log(event.type, event.tool.id);
}

// Close the stream when done
await stream.close();

runServer(serverId: string, hostType?: string, options?): Promise<CommandResultDto>

Start a new tool instance from an installed server. Returns once the tool is ready.

const result = await client.runServer("my-server-id", undefined, {
  timeoutSeconds: 30,
});
console.log("Tool ID:", result.command);

startTool(toolId: string, callbacks): Promise<void>

Start a stopped tool, streaming status via SSE.

stopTool(toolId: string): Promise<ToolIdDto>

Stop a running tool.

deleteTool(toolId: string): Promise<ToolIdDto>

Stop and delete a tool instance.

callTool(toolId: string, call: FunctionCall): Promise<ToolReturn>

Call a tool function and wait for the result.

const result = await client.callTool("my-tool-id", {
  id: "call-1",
  name: "myFunction",
  arguments: { input: "hello" },
});
console.log(result.result);

streamCallTool(toolId: string, call: FunctionCall, callbacks): Promise<void>

Call a tool function and stream back events via SSE.

loadTool(toolId: string): Promise<OpenTool | null>

Load the OpenTool definition for a running tool.

setAliasTool(toolId: string, alias: string): Promise<ToolDto>

Set the alias for a tool instance.

Error handling

import { HttpError, SseRequestError, CommandException } from "@opentool/daemon-client";

try {
  await client.callTool("my-tool-id", call);
} catch (err) {
  if (err instanceof HttpError) {
    console.error(`HTTP ${err.statusCode}: ${err.body}`);
  } else if (err instanceof SseRequestError) {
    console.error(`SSE request failed ${err.statusCode}: ${err.body}`);
  } else if (err instanceof CommandException) {
    console.error(`Command "${err.command}" failed: ${err.message}`);
  }
}

Notes

• Server and tool long-running endpoints use SSE over plain HTTP requests.
• listToolWithApiKeys and subscribeToolEvents require a daemon API key.
• createApiKey, listApiKeys, and deleteApiKey require a sudo token.