> ## Documentation Index
> Fetch the complete documentation index at: https://arkor-92aeef0e-eng-615.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# arkor dev

> Arkor Studio をローカル起動する。

# `arkor dev`

[Studio](/ja/concepts/studio)（ローカル Web UI）を `http://localhost:4000` で起動します。Studio は **Run training** をクリックして `src/arkor/index.ts` に対し `arkor start` を起動し、進捗をストリーミングで確認し、出来上がったアダプターと Playground でチャットするための場所です。

`arkor dev` 自体は学習を開始 **しません**。UI と SPA が通信するための小さなループバック API を提供するだけです。

## 概要

```
arkor dev [options]
```

<CodeGroup>
  ```bash pnpm theme={null}
  pnpm dev
  ```

  ```bash npm theme={null}
  npm run dev
  ```

  ```bash yarn theme={null}
  yarn dev
  ```

  ```bash bun theme={null}
  bun dev
  ```
</CodeGroup>

## オプション

| フラグ                 | デフォルト  | 説明                                                                                                                                                              |   |                                                                                                                                                                               |
| ------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-p, --port <port>` | `4000` | バインドするポート。表示 URL は `localhost` ですが、リスナーは `127.0.0.1` を直接バインドします。これにより `/etc/hosts` で `::1` が `127.0.0.1` より先に並ぶホストでも IPv6 専用に終わりません。CLI は値を \`Number(opts.port) |   | 4000` でパースするので、falsy な結果（`0`、非数）は `4000`に正規化されます。**truthy な不正値はそのまま透過します**。負のポートや`65535`を超えるポートはリスナーにそのまま到達し`serve()`の失敗（例:`RangeError\`）として現れます。1 から 65535 の標準範囲を自分で守ってください。 |
| `--open`            | off    | サーバー起動後にブラウザーで Studio URL を開く。                                                                                                                                  |   |                                                                                                                                                                               |

## 振る舞い

### 起動シーケンス

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 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` を実行して再試行してください）。
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.1` と `localhost` の両方を受け付けるので、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 ワークフローだけです。

プロセス終了時（通常終了、`SIGINT`、`SIGTERM`、`SIGHUP`）に studio-token ファイルはベストエフォートで削除されます。クラッシュするとファイルがディスク上に残ることがあり、その場合は次回 `arkor dev` がローテートします。

### ループバックと CSRF モデル

Studio サーバーはすべての `/api/*` リクエストに 3 つのチェックを課します。

1. `Host` ヘッダーは `127.0.0.1` か `localhost`（DNS リバインディング対策）。
2. CSRF トークンは `X-Arkor-Studio-Token` ヘッダーか `?studioToken=...`（カスタムヘッダーを送れない `EventSource` 用）として必須。比較には `timingSafeEqual` を使用しているため、タイミング攻撃に対して安全です。
3. CORS は意図的に未設定。SPA は同一オリジンなので CORS は意味を持たず、`*` を反射すると 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` の古いタブ。                                                                   | タブをリロード。トークンは起動ごとにローテート。                                                                                      |

## 例

デフォルトポート。

<CodeGroup>
  ```bash pnpm theme={null}
  pnpm dev
  ```

  ```bash npm theme={null}
  npm run dev
  ```

  ```bash yarn theme={null}
  yarn dev
  ```

  ```bash bun theme={null}
  bun dev
  ```
</CodeGroup>

ポート指定と自動オープン。

<CodeGroup>
  ```bash pnpm theme={null}
  pnpm dev --port 5000 --open
  ```

  ```bash npm theme={null}
  npm run dev -- --port 5000 --open
  ```

  ```bash yarn theme={null}
  yarn dev --port 5000 --open
  ```

  ```bash bun theme={null}
  bun dev --port 5000 --open
  ```
</CodeGroup>

## 関連項目

* [Studio コンセプト](/ja/concepts/studio): UI で実際に何が起きるか
* [`arkor login`](/ja/cli/auth): 匿名セッションを OAuth にアップグレード
* [プロジェクト構成](/ja/concepts/project-structure): `~/.arkor/` と `.arkor/` のレイアウト