メインコンテンツまでスキップ

SDK リファレンス

NanoTermClient クラスの全メソッドです。すべての非同期メソッドは型付きの結果を返します。エラーは共通エラーエンベロープに従います。

ワークスペース​

createWorkspace(config?)​

新しいワークスペースを作成します。

const ws = await client.createWorkspace({
  name: 'my-agent',      // 省略可
  image: 'ubuntu:22.04'  // 省略可、デフォルト: ubuntu:22.04
})

console.log(ws)
// {
//   id: 'ws_a1b2c3d4',
//   name: 'my-agent',
//   image: 'ubuntu:22.04',
//   status: 'running',
//   createdAt: '2026-04-06T...'
// }

戻り値: Promise<WorkspaceInfo>

listWorkspaces()​

現在の組織のワークスペース一覧を取得します。

const workspaces = await client.listWorkspaces()
// WorkspaceInfo[]

getWorkspace(id)​

特定のワークスペースの詳細を取得します。

const ws = await client.getWorkspace('ws_a1b2c3d4')

terminateWorkspace(id)​

ワークスペースを停止・削除します。

await client.terminateWorkspace('ws_a1b2c3d4')

コマンド実行​

exec(workspaceId, command, opts?)​

コマンドを実行して結果を返します。

const result = await client.exec('ws_a1b2c3d4', ['npm', 'test'])

console.log(result)
// {
//   stdout: 'PASS src/index.test.ts\nTests: 12 passed',
//   stderr: '',
//   exitCode: 0
// }

// サブディレクトリで実行
await client.exec('ws_a1b2c3d4', ['pnpm', 'build'], {
  cwd: '/workspace/api',
})

パラメータ:

名前型説明
workspaceIdstring対象ワークスペース ID
commandstring[]コマンドと引数
opts.cwdstringワークスペース内の作業ディレクトリ（デフォルト /workspace）

戻り値: Promise<ExecResult>

interface ExecResult {
  stdout: string
  stderr: string
  exitCode: number
}

getTerminalUrl(workspaceId)​

対話型ターミナル用の WebSocket URL を取得します。

const url = client.getTerminalUrl('ws_a1b2c3d4')
// wss://api.nanoterm.dev/api/workspaces/ws_a1b2c3d4/terminal

WebSocket のアップグレードハンドシェイクは HTTP と同じ認証で ゲートされます。生 WebSocket クライアントには getAuthHeaders() で取得したヘッダーを渡して ください:

import WebSocket from 'ws'
const ws = new WebSocket(client.getTerminalUrl(id), {
  headers: client.getAuthHeaders(),
})

メッセージは JSON フレーム形式：

クライアント → サーバー:

{ type: 'stdin', data: '<base64>' }     // 入力
{ type: 'resize', cols: 80, rows: 24 }  // リサイズ

サーバー → クライアント:

{ type: 'stdout', data: '<base64>' }    // 出力

ファイル​

writeFile(workspaceId, filePath, content)​

ワークスペース内のファイルに書き込みます。サーバーは書き込み後に ファイルを stat して、実際の bytes と mtime を返します。 呼び出し側は bytes が送信サイズと一致することを確認してから 成功扱いしてください。

const content = new TextEncoder().encode('hello\n').buffer
const result = await client.writeFile('ws_a1b2c3d4', '/workspace/hello.txt', content)
// { bytes: 6, mtime: '2026-05-06T08:01:23.000Z' }

if (result.bytes !== 6) {
  throw new Error('write was truncated upstream')
}

4xx / 5xx レスポンスは NanoTermError として throw されます。代表的 なエラーコード:

コード意味
FILE_WRITE_BYTE_MISMATCHディスク上のバイト数が送信内容と一致しない（経路上のプロキシ／ストリーミング問題）。リトライ。

readFile(workspaceId, filePath)​

ワークスペースからファイルを ArrayBuffer で読みます。非 2xx レスポンス（共通エラーエンベロープ含む）では throw します。

const buf = await client.readFile('ws_a1b2c3d4', '/workspace/result.json')
const text = new TextDecoder().decode(buf)

認証ヘルパー​

getAuthHeaders()​

SDK が通常の HTTP リクエストに付けるヘッダー（Authorization, X-Org-Id, X-Client-Name, X-Client-Version）を返します。 生 WebSocket / fetch でターミナル・プロキシ等を開くときに、 アップグレードハンドシェイクを正しく認証するために使用します:

const ws = new WebSocket(client.getTerminalUrl(id), {
  headers: client.getAuthHeaders(),
})

エラーハンドリング​

SDK が throw するのは NanoTermError（サーバーからの HTTP エンベ ロープ）または TransientNetworkError（ネットワークエラー / 非 JSON 5xx）です。どちらもエージェントが利用できる以下のフィールドを持ち ます:

フィールドセットされるとき意味
codeNanoTermError安定エラー識別子（例 WORKSPACE_NOT_FOUND）
retryable両方同一呼び出しが後で成功しうるか
requestSent両方false = サーバーに届いていない（非冪等操作も安全に再試行可）。true = 副作用が発生している可能性
attemptNanoTermErrorこのエラーを生んだリトライ回数（1 始まり）
status両方HTTP ステータス
retryAfterSecNanoTermError 429 時再試行までの待機秒数

CLI の --json モードはこのフィールド構造をそのまま stderr に出力 するので、エージェントは文字列を解釈せずに復旧戦略を決められます。

型定義​

すべての型は @nanoterm/types からインポートできます：

import type {
  WorkspaceInfo,
  WorkspaceStatus,
  CreateWorkspaceRequest,
  ExecRequest,
  ExecResult,
  TerminalInputMessage,
  TerminalOutputMessage,
  OrgInfo,
  ApiKeyInfo,
} from '@nanoterm/types'