Arkor Studio をローカル起動する。
Studio（ローカル Web UI）を http://localhost:4000 で起動します。Studio は Run training をクリックして src/arkor/index.ts に対し arkor start を起動し、進捗をストリーミングで確認し、出来上がったアダプターと Playground でチャットするための場所です。
arkor dev 自体は学習を開始 しません。UI と SPA が通信するための小さなループバック API を提供するだけです。
arkor dev [options]pnpm devnpm run devyarn devbun dev| フラグ | デフォルト | 説明 |
|---|---|---|
-p, --port <port> | 4000 | バインドするポート。表示 URL は localhost ですが、リスナーは 127.0.0.1 を直接バインドします。これにより /etc/hosts で ::1 が 127.0.0.1 より先に並ぶホストでも IPv6 専用に終わりません。CLI は値を `Number(opts.port) |
--open | off | サーバー起動後にブラウザーで Studio URL を開く。 |
~/.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 dev は Anonymous 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 を実行して再試行してください）。<meta name="arkor-studio-token"> として index.html にインジェクトされます。クロスオリジンタブはこの meta を読めず、/api/* のミドルウェアに拒否されます。127.0.0.1:<port> 上の Hono。Host ヘッダーのガードは 127.0.0.1 と localhost の両方を受け付けるので、CLI が表示する URL（http://localhost:<port>）は DNS リバインディング系の挙動なしで動きます。~/.arkor/studio-token（モード 0600）に書きます。studio-app の Vite dev サーバー（pnpm --filter @arkor/studio-app dev）が拾えるようにするためです。先にバインドするので、使用中ポートへの 2 つ目の起動がこのファイルに触れることはありません（下の「ポート競合」参照）。書き込みが失敗（$HOME が読み取り専用、umask が厳しいなど）しても arkor dev は続行します。影響を受けるのはスタンドアローン Vite dev ワークフローだけです。プロセス終了時（通常終了、SIGINT、SIGTERM、SIGHUP）に studio-token ファイルはベストエフォートで削除されます。クラッシュするとファイルがディスク上に残ることがあり、その場合は次回 arkor dev がローテートします。
Studio サーバーはすべての /api/* リクエストに 3 つのチェックを課します。
Host ヘッダーは 127.0.0.1 か localhost（DNS リバインディング対策）。X-Arkor-Studio-Token ヘッダーか ?studioToken=...（カスタムヘッダーを送れない EventSource 用）として必須。比較には timingSafeEqual を使用しているため、タイミング攻撃に対して安全です。* を反射すると preflight をスキップする「simple」なクロスオリジン POST（text/plain、urlencoded）を素通りさせてしまう。トークンが無ければミドルウェアが拒否します。これにより arkor dev は共有の開発環境でも安全です。別タブは meta を読めず、過去の起動の古いタブはトークンが一致せず、別オリジンの攻撃者ページはリクエストを偽造できません。
arkor dev は空きポートの自動採用はしません。指定ポートが既に使われている（前回の arkor dev が残っている、無関係な dev サーバー、など）と、リスナーの EADDRINUSE は捕捉され、arkor dev は Port <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 つ目のインスタンスが依存するトークンを上書き・削除することはありません。
| 症状 | 意味 | 対処 |
|---|---|---|
Port 4000 is already in use. Another `arkor dev` may be running; pass --port to choose a different one.（ポート 4000 は既に使用中。根本のエラーは EADDRINUSE） | 別プロセスがポートを保持。 | 止めるか --port <other>。 |
Could not reach <baseUrl> (fetch failed). Studio will keep running and retry on first /api/credentials hit.（<baseUrl> に到達できませんでした（fetch 失敗）。Studio は起動を続け、初回の /api/credentials 受信時に再試行します） | /v1/auth/cli/config は成功したが、続く /v1/auth/anonymous がトランスポート障害で失敗。Studio サーバーは起動して再試行する。 | 接続を回復させれば arkor dev を再起動せずに次の /api/credentials ポーリングで SPA が回復。 |
TypeError: fetch failed（または同等のトランスポートエラーで arkor dev がそのまま終了する場合） | /v1/auth/cli/config 自体に届かなかったため、デプロイモードが特定できず fail-fast。 | 接続を回復してから arkor dev を再実行。 |
No credentials on file. Bootstrapping an anonymous session. Run `arkor login --oauth` to sign in to your account instead.（認証情報ファイルがありません。匿名セッションを初期化します。アカウントでサインインしたい場合は arkor login --oauth を実行してください） | OAuth をアドバタイズしているデプロイで、この環境では初回の arkor dev。Studio をすぐ起動できるよう CLI が匿名で初期化している旨の案内で、エラーではない。 | 何もしなくてよい。本物のアカウントにアップグレードしたいなら、別途 arkor login --oauth を実行（~/.arkor/credentials.json を上書き）して Studio をリロード。 |
No credentials on file. Requesting an anonymous token.（認証情報ファイルがありません。匿名トークンを要求します） | 同上だが匿名専用デプロイの場合（/v1/auth/cli/config で OAuth がアドバタイズされていない）。arkor login --oauth は失敗するので OAuth ヒントは省かれる。 | 何もしなくてよい。 |
Anonymous 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） | 匿名初期化の完了後の情報行。クラウド側の識別子と、それを保持しているファイルの場所を明示する。 | 何もしなくてよい。別の環境から同じ匿名 ID を使いたいなら認証情報ファイルをバックアップ。 |
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 でサインインしてください） | デプロイが OAuth をサポートすると分かっているときに、成功メッセージと並んで出る永続性ナッジ。匿名作業はクラウド API 側で SLA がないので、本格的に作業する前にアップグレード経路を提示している。匿名専用デプロイでは抑制される。 | 任意。今後の作業をアカウントに紐付けたいなら arkor login --oauth。既存の匿名作業はその id に残り、現状マイグレーション手段はない。 |
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 を実行して再試行してください） | /v1/auth/anonymous が 4xx で拒否され、匿名セッションの初期化が進められない。 | arkor login --oauth でブラウザーフローを完了してから arkor dev を再実行。 |
Could not write ~/.arkor/studio-token (...). The Studio at http://localhost:<port> is unaffected, but the Vite SPA dev workflow will see 403s on /api/*.（~/.arkor/studio-token を書き込めませんでした（...）。http://localhost:<port> の Studio には影響しませんが、Vite SPA の dev ワークフローでは /api/* で 403 になります） | $HOME が読み取り専用、または umask が 0600 をブロック。同梱 Studio は機能し、影響はスタンドアローン Vite dev ワークフローのみ。 | 書ける home から実行するか、arkor dev が提供する同梱 Studio のみを使う。 |
HTTP 403 with { "error": "Studio API is loopback-only" }（Studio API はループバック専用です。ブラウザーの devtools で確認） | Host ヘッダーが 127.0.0.1 / localhost 以外。 | http://localhost:<port> か http://127.0.0.1:<port> で Studio に到達。リバースプロキシや 0.0.0.0 バインドのシェルは設計通り拒否されます。 |
HTTP 403 with { "error": "Missing or invalid studio token" }（studio token が欠けているか無効です。ブラウザーの devtools で確認） | ページ内の CSRF トークンが現在の起動と一致しない。たいていは前回 arkor dev の古いタブ。 | タブをリロード。トークンは起動ごとにローテート。 |
デフォルトポート。
pnpm devnpm run devyarn devbun devポート指定と自動オープン。
pnpm dev --port 5000 --opennpm run dev -- --port 5000 --openyarn dev --port 5000 --openbun dev --port 5000 --openarkor login: 匿名セッションを OAuth にアップグレード~/.arkor/ と .arkor/ のレイアウト