SDK のインストール

Werft は TypeScript SDK @werft-ai/sdk で使う。SDK は、すでに動いている Werft サーバーに API キーで接続する。このページでは SDK をインストールし、サーバーのアドレスとキーでクライアントを作り、接続を確認する。

必要なもの見出しのリンクをコピー

インストール見出しのリンクをコピー

アプリのディレクトリを作り、npm から @werft-ai/sdk をインストールする。

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

このコマンドはリリース版(dist-tag latest)をインストールする。main push ごとのプレリリース自動公開は停止した。既存の main dist-tag は更新されないため、リリース版を使用する。

SDK パッケージは Apache License 2.0 である。サーバーとリポジトリの残りは PolyForm Small Business License 1.0.0 に従う source-available のコードである。

クライアントを作る見出しのリンクをコピー

Werft を作るときに、サーバーのアドレス(baseUrl)と API キー(apiKey)を渡す。サーバーのアドレスに既定値はない。キーはコードに書かず、環境変数から読む。

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 はサーバーのアドレスである。/v1 は付けない。
• オプションを省くと、環境変数 WERFT_BASE_URL、WERFT_API_KEY を読む。どちらかがなければ new Werft() が TypeError を投げる。
• loopback 以外のアドレスに http:// を使うとキーが平文で流れるため、拒否する。リモートのサーバーには https:// で接続する。
• ブラウザでは作れない。ページにキーを置くと漏れるからである。

リトライ、timeout、エラーの種類などの残りのオプションはクライアントの設定とエラーにある。

接続を確認する見出しのリンクをコピー

キーの持ち主と scope、サーバーに登録されたプロファイルを読む。

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 以上と Bun は .ts ファイルをそのまま実行する。それより古い Node では npx tsx check.ts で実行する。キーが間違っていれば APIError(401)が、サーバーに届かなければ ConnectionError が起きる。

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

次のステップ見出しのリンクをコピー

• 最初のセッションを作る: SDK でセッションを作り、モデルの答えを読む