Client

Discover the daemon, verify its identity, and get a connected client.

3 min read36 pages in SDK Reference

On this page3

Connect
Daemon identity
Start a private daemon

import { Compozy } from "@compozy/client";

Connect

Construct a connected client. Both clients check the daemon's identity before they return one. A local process outside the browser does not need an app token.

Signature

Compozy.connect(options?: ConnectOptions): Promise<Compozy>

In Node, Bun, and Deno, discovery checks baseUrl, then COMPOZY_URL, then the daemon.json in the daemon home, then http://127.0.0.1:2123. In a browser, the client uses baseUrl or http://localhost:2123.

Options

baseUrlstring: Selects a daemon ahead of COMPOZY_URL and local discovery. An HTTP(S) URL without credentials, query, or fragment.
tokenstring: App token, sent as a bearer token. In Node, Bun, and Deno, COMPOZY_APP_TOKEN is used when this is unset.
homestring: Daemon home ahead of COMPOZY_HOME and ~/.compozy. Browsers do not read it.
timeoutMsnumber: Timeout of the identity check. Defaults to 5000.
fetchtypeof fetch: A fetch implementation for runtimes that do not provide one.
clientIdstring: Sent as X-Compozy-Client-ID. Defaults to sdk-ts.
onVersionMismatch(versions: { client: string; daemon: string }) => void: Called when the daemon's major or minor version differs from the client's. The client still connects. Without it, the client logs a warning.

Example

import { Compozy } from "@compozy/client";

const compozy = await Compozy.connect({ baseUrl: "http://127.0.0.1:2123" });
console.log(`Connected to CompozyOS ${compozy.daemon.version}`);

Daemon identity

The identity the daemon reported when the client connected.

Signature

compozy.daemon: DaemonIdentity

Options

versionstring
httpHoststring
httpPortnumber
pidnumber
userHomeDirstring: Empty when the daemon does not report it.
startedAtstring: Empty when the daemon does not report it.

Start a private daemon

The Node-only @compozy/client/node entry adds Compozy.start(). It connects to the daemon already running in that home, or starts one when the home has none. close({ stopDaemon: true }) stops only the daemon this client started, and only while the home's daemon.json still names that process. The binary lookup is binaryPath, COMPOZY_BIN, installed @compozy/cli, then PATH.

Signature

Compozy.start(options?: StartOptions): Promise<Compozy>
compozy.close(options?: { stopDaemon?: boolean }): Promise<void>

Options

homestring: The daemon home, created when missing. Defaults to COMPOZY_HOME, then ~/.compozy.
timeoutMsnumber: Start timeout. Defaults to 30000.
binaryPathstring: Path to the compozy binary.

StartOptions also takes token, fetch, clientId, and onVersionMismatch, as connect() does.

Example

import { Compozy } from "@compozy/client/node";

const compozy = await Compozy.start({
  home: "/tmp/my-app-home",
  timeoutMs: 30000,
});
console.log(compozy.daemon.version);
await compozy.close({ stopDaemon: true });