Skip to main content

arkor dev

Studio(ローカル Web UI)を http://localhost:4000 で起動します。Studio は Run training をクリックして src/arkor/index.ts に対し arkor start を起動し、進捗をストリーミングで確認し、出来上がったアダプターと Playground でチャットするための場所です。 arkor dev 自体は学習を開始 しません。UI と SPA が通信するための小さなループバック API を提供するだけです。

概要

オプション

振る舞い

起動シーケンス

  1. 認証情報の初期化。 ~/.arkor/credentials.json が無いとき、CLI は 常に匿名セッションの初期化を試みます/v1/auth/cli/config を呼び、続いて /v1/auth/anonymous から匿名トークンを要求します。初期化前のメッセージはデプロイが OAuth をアドバタイズしているかで分岐します。OAuth が設定されている場合は No credentials on file. Bootstrapping an anonymous session. Run `arkor login --oauth` to sign in to your account instead.(認証情報ファイルがありません。匿名セッションを初期化します。アカウントでサインインしたい場合は arkor login --oauth を実行してください)を出して、好きなタイミングで本物のアカウントへアップグレードできることを案内します。匿名専用デプロイでは代わりに No credentials on file. Requesting an anonymous token.(認証情報ファイルがありません。匿名トークンを要求します)を出し、arkor login --oauth がそのデプロイでは失敗するため OAuth ヒントは省略されます。いずれの場合も OAuth フローを自動で起動することはありません。トークンが届くと arkor devAnonymous id: <id>. Arkor Cloud uses this id to recognise this client across sessions. Keep `<home>/.arkor/credentials.json` to stay signed in as the same anonymous identity.(匿名 id: <id>。Arkor Cloud はこの id でセッション間でこのクライアントを識別します。同じ匿名 ID を維持するには認証情報ファイルを保持してください。パスは credentialsPath() の解決結果で、Linux と macOS では通常 ~/.arkor/credentials.json)を出します。デプロイが OAuth をアドバタイズしている場合に限り、成功メッセージと並んで warn(Anonymous sessions aren't guaranteed to persist. Sign in with `arkor login --oauth` to tie future work to your Arkor Cloud account.、和訳: 匿名セッションは永続性が保証されないので、今後の作業を Arkor Cloud アカウントに紐付けたいなら arkor login --oauth でサインインしてください)が発行され、アップグレード経路が発行時点で見えます。匿名専用デプロイでは arkor login --oauth を案内すると失敗するコマンドへユーザーを誘導してしまうので、warn は意図的に抑制されます。一過性のトランスポート障害(fetch failed)の扱いはタイミングで分かれます。/v1/auth/cli/config が成功してデプロイモードが特定済みのあと、/v1/auth/anonymous で同様の障害が出た場合のみ警告して続行し、Studio サーバーは初回の /api/credentials ヒットで再試行します。/v1/auth/cli/config 自体に到達できなかった場合は同じトランスポートエラーがそのまま再スローされて arkor dev は fail-fast で終了するので、接続を回復してから再実行してください。/v1/auth/anonymous が 4xx で拒否される場合(例えば、このデプロイで匿名サインインが無効になっているなど)は HTTP ステータスを含むエラーで arkor login --oauth を案内します(フルメッセージ: Failed to bootstrap an anonymous session (HTTP <status>). This deployment may require sign-in. Run `arkor login --oauth` and try again.、和訳: 匿名セッションの初期化に失敗しました(HTTP <status>)。このデプロイはサインインが必要かもしれません。arkor login --oauth を実行して再試行してください)。
  2. CSRF トークン。 この起動用に 32 バイトのトークン(base64url、約 43 文字)を生成。同一オリジンの SPA が読めるよう <meta name="arkor-studio-token"> として index.html にインジェクトされます。クロスオリジンタブはこの meta を読めず、/api/* のミドルウェアに拒否されます。
  3. リスナー。 127.0.0.1:<port> 上の Hono。Host ヘッダーのガードは 127.0.0.1localhost の両方を受け付けるので、CLI が表示する URL(http://localhost:<port>)は DNS リバインディング系の挙動なしで動きます。
  4. トークンの永続化(ベストエフォート、バインド成功後)。 リスナーが立ち上がってから、トークンを ~/.arkor/studio-token(モード 0600)に書きます。studio-app の Vite dev サーバー(pnpm --filter @arkor/studio-app dev)が拾えるようにするためです。先にバインドするので、使用中ポートへの 2 つ目の起動がこのファイルに触れることはありません(下の「ポート競合」参照)。書き込みが失敗($HOME が読み取り専用、umask が厳しいなど)しても arkor dev は続行します。影響を受けるのはスタンドアローン Vite dev ワークフローだけです。
プロセス終了時(通常終了、SIGINTSIGTERMSIGHUP)に studio-token ファイルはベストエフォートで削除されます。クラッシュするとファイルがディスク上に残ることがあり、その場合は次回 arkor dev がローテートします。

ループバックと CSRF モデル

Studio サーバーはすべての /api/* リクエストに 3 つのチェックを課します。
  1. Host ヘッダーは 127.0.0.1localhost(DNS リバインディング対策)。
  2. CSRF トークンは X-Arkor-Studio-Token ヘッダーか ?studioToken=...(カスタムヘッダーを送れない EventSource 用)として必須。比較には timingSafeEqual を使用しているため、タイミング攻撃に対して安全です。
  3. CORS は意図的に未設定。SPA は同一オリジンなので CORS は意味を持たず、* を反射すると preflight をスキップする「simple」なクロスオリジン POST(text/plainurlencoded)を素通りさせてしまう。トークンが無ければミドルウェアが拒否します。
これにより arkor dev は共有の開発環境でも安全です。別タブは meta を読めず、過去の起動の古いタブはトークンが一致せず、別オリジンの攻撃者ページはリクエストを偽造できません。

ポート競合

arkor dev は空きポートの自動採用はしません。指定ポートが既に使われている(前回の arkor dev が残っている、無関係な dev サーバー、など)と、リスナーの EADDRINUSE は捕捉され、arkor devPort <port> is already in use. Another `arkor dev` may be running; pass --port to choose a different one.(ポート <port> は既に使用中です。別の arkor dev が動いているかもしれません。--port で別のポートを選んでください)という明確なメッセージとともに非ゼロで終了します。-p <port> で別のポートを選ぶか、占有しているプロセスを止めてください。 トークンファイル(~/.arkor/studio-token)はポートのバインド成功 にのみ書き込まれるため、使用中ポートへの 2 つ目の起動が失敗しても、正常に動いている 1 つ目のインスタンスが依存するトークンを上書き・削除することはありません。

エラー

デフォルトポート。
ポート指定と自動オープン。

関連項目