SDK 설치

Werft는 TypeScript SDK @werft-ai/sdk로 쓴다. SDK는 이미 떠 있는 Werft 서버에 API key로 붙는다. 이 페이지에서 SDK를 설치하고, 서버 주소와 key로 클라이언트를 만들고, 연결을 확인한다.

필요한 것제목 링크 복사

설치제목 링크 복사

앱 디렉터리를 만들고 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 key(apiKey)를 넘긴다. 서버 주소에 기본값은 없다. key는 코드에 적지 말고 환경 변수에서 읽는다.

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://를 쓰면 key가 평문으로 지나가므로 거절한다. 원격 서버에는 https://로 붙는다.
• 브라우저에서는 만들 수 없다. 페이지에 key를 두면 새기 때문이다.

재시도, timeout, 오류 종류 같은 나머지 옵션은 클라이언트 설정과 오류에 있다.

연결 확인제목 링크 복사

key의 주인과 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로 돌린다. key가 틀리면 APIError(401)가, 서버에 닿지 않으면 ConnectionError가 난다.

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

다음 단계제목 링크 복사

• 첫 세션 만들기: SDK로 세션을 만들고 모델의 답을 읽는다