Install the SDK

You use Werft through the TypeScript SDK @werft-ai/sdk. The SDK connects to a running Werft server with an API key. On this page you install the SDK, create a client with the server address and a key, and check the connection.

PrerequisitesCopy Anchor Link

InstallCopy Anchor Link

Create an app directory and install @werft-ai/sdk from npm.

mkdir my-werft-app && cd my-werft-app
npm init -y
npm pkg set type=module
npm install @werft-ai/sdk

This command installs the release (dist-tag latest). Automatic prerelease publishing on main pushes has stopped. The existing main dist-tag is no longer updated, so use a release version.

The SDK package is under the Apache License 2.0. The server and the rest of the repository are source-available code under the PolyForm Small Business License 1.0.0.

Create a clientCopy Anchor Link

Pass the server address (baseUrl) and the API key (apiKey) when you create Werft. The server address has no default. Do not write the key in code; read it from an environment variable.

import { Werft } from "@werft-ai/sdk";

export const werft = new Werft({
  baseUrl: "http://127.0.0.1:3000",
  apiKey: process.env.WERFT_API_KEY,
});

• baseUrl is the server's address. Do not append /v1.
• Leave an option out and the client reads the WERFT_BASE_URL or WERFT_API_KEY environment variable. If either is missing, new Werft() throws a TypeError.
• http:// to an address other than loopback is refused, because the key would cross the network in clear text. Connect to a remote server over https://.
• You cannot create a client in a browser, because a key in a page leaks.

The remaining options, such as retries, timeouts and error types, are in Client settings and errors.

Check the connectionCopy Anchor Link

Read the key's owner and scopes, and the profiles registered on the server.

import { werft } from "./werft.ts";

const me = await werft.auth.me();
console.log(me.principal.kind, me.scopes);

const { items } = await werft.profiles.list();
for (const profile of items) console.log(profile.id, profile.repository_mode);

WERFT_API_KEY=csp_… node check.ts

api_key [
  'sessions:read',
  'sessions:write',
  'sessions:approve',
  'sessions:control',
  'sessions:recover'
]
claude-coding-auto required
claude-coding-local required
general none

Node 22.18 or later and Bun run .ts files directly. On an older Node, run npx tsx check.ts. A wrong key raises APIError (401), and a server that cannot be reached raises ConnectionError.

curl -sS -w '\n' "$API/v1" -H "Authorization: Bearer $KEY"

Next stepsCopy Anchor Link

• Create your first session: create a session with the SDK and read the model's answer