クイックスタート

Arkor プロジェクトを生成し、小さなオープンウェイト LLM をファインチューニングして、ローカル Studio からチャットしてみる。

数分でゼロからスタートし、ローカル Playground でチャットできるファインチューン済みモデルが得られます。学習自体は 7〜12 分。セットアップ時間は回線と既存のインストール状況に左右されます。

​

前提条件

• Node.js 22.22.0 以降。 Node 24 を推奨します。
• パッケージマネージャー。 pnpm、npm、yarn、bun のいずれでも動きます。以下のスニペットはタブグループになっており、普段使う 1 つを選べばページ全体がそれに揃います。
• インターネット接続。学習は Arkor のマネージド GPU で実行されます。

アカウントもクレジットカードも、手元の GPU も不要です。

​

1. プロジェクトを生成する

pnpm

pnpm create arkor my-arkor-app
cd my-arkor-app

プロジェクト生成ツールがどのテンプレートを使うか尋ねてきます。最終的に作りたいものに最も近いものを選んでください:

テンプレート	タスク	出力の形	推定学習時間
triage	サポートのトリアージ	{ category, urgency, summary, nextAction }	約 7 分
translate	9 言語の翻訳	{ translation, detectedLanguage }	約 7 分
redaction	個人情報のマスク	{ redactedText, redactedCount, tags }	約 12 分

いずれも同じ小型のオープンウェイトベース（gemma-4-E4B-it）と、HuggingFace 上の厳選された公開データセットを組み合わせたものです。学習は本物で、数分で終わるので、ループ全体をエンドツーエンドで体験できます。

プロンプトをスキップしたいとき:

pnpm

pnpm create arkor my-arkor-app --template triage

​

Claude Code 下での実行（CLAUDECODE=1）

Claude Code は子プロセスに CLAUDECODE=1 を渡し、対話プロンプトに応答できません。エージェントが隠れたデフォルトで黙ってプロジェクトを生成してしまうのを防ぐため、この環境変数下では create-arkor も厳格モードに切り替わります。下記のキュレーション済みフラグセットが必須となり、不足があれば実行ではなく、再実行用のコマンドを stderr に出して終了します。同じルールは arkor init にも適用されますが、create-arkor だけ追加で [dir]（または --name）も必須となります。これは positional 省略時のフォールバック先 arkor-project/ サブディレクトリが意図的に選ばれることはまずなく、ほぼ常に指定漏れだからです。ASCII の英数字を 1 文字も含まない入力（空、空白だけ、!!! のような記号だけ）も拒否されます。sanitise() が同じ generic フォールバックに collapse させてしまうためです。一方、サニタイズ結果がたまたま arkor-project になるような 意図的な名前（例: Arkor Project、arkor_project、Arkor.Project のようにセパレータ文字が - に書き換えられるもの）は受け入れます。英数字が含まれていることがエージェントの明示的入力の証拠になるためです。

必須フラグ（または -y/--yes で「すべてデフォルトで進める」にオプトイン）:

• [dir]（例 my-arkor-app）または --name <name>: 明示的なプロジェクト名。ASCII の英数字を 1 文字も含まない入力（空、空白だけ、!!! のような記号だけ）は、arkor-project フォールバックに collapse させてしまうため拒否。Arkor Project、arkor_project のように 意図的でたまたま サニタイズ結果が arkor-project になる入力は受け入れます。
• --template <triage|translate|redaction>
• --git（推奨。対話モードのデフォルトと同じ）または --skip-git
• パッケージマネージャー系フラグ: --use-npm / --use-pnpm / --use-yarn / --use-bun、または --skip-install
• --agents-md（特に CLAUDECODE 下では推奨）または --no-agents-md

フラグが不足したときの stderr 例:

create-arkor: CLAUDECODE=1 detected. Interactive prompts are disabled.
Re-run with explicit flags:
  [dir] (e.g. `my-arkor-app`) or --name <name>
      Project directory (positional) and the `package.json` name. Without `--name`, the basename of `[dir]` is used. Inputs with no ASCII letter or digit (empty, whitespace-only, or punctuation-only like `!!!` / `***`) are rejected because they would collapse to the generic `arkor-project` fallback inside `sanitise()`.
  --template <triage|translate|redaction>
      Starter template: `triage` (support routing), `translate` (9-language translation), or `redaction` (PII removal).
  --git (recommended) or --skip-git
      `--git` runs `git init` and creates an initial commit (matches the interactive default); `--skip-git` leaves git setup to the user.
  --use-pnpm (or --use-npm / --use-yarn / --use-bun, or --skip-install)
      Which package manager to run `install` with after scaffolding. `--skip-install` leaves the install step to the user.
  --agents-md (recommended) or --no-agents-md
      `--agents-md` writes `AGENTS.md` + `CLAUDE.md` to brief AI coding agents that arkor post-dates their training data (recommended, especially under CLAUDECODE); `--no-agents-md` skips them.
Or pass -y/--yes to accept all defaults.

終了コードは 1、早期終了の前にファイル生成は一切行われないので、親ディレクトリは元の状態のままです。

​

2. 生成されたものを眺める

my-arkor-app/
├── src/arkor/
│   ├── index.ts        # createArkor({ trainer })
│   └── trainer.ts      # createTrainer({ ... })
├── arkor.config.ts
├── .arkor/             # 状態 + ビルド成果物（gitignore 済み）
└── package.json        # dev / build / start

当面重要なのはこの 2 ファイルです:

• src/arkor/trainer.ts にトレーナー定義を置きます。モデル、データセット、LoRA 設定、ハイパーパラメーター（学習率や学習ステップ数など、学習の進み方を決める設定値。データから機械的には決められず、人が事前に与える必要があります）、ライフサイクルコールバックがすべてここに集まります。
• src/arkor/index.ts はエントリーポイントです。createArkor({ trainer }) を呼ぶことで、CLI と Studio が何を実行すべきか発見できるようにします。

trainer.ts を開いてみてください。構造はどのテンプレートでも共通で、データセット、出力スキーマ、サンプルプロンプトだけが異なります。

​

3. Studio を開いて学習を始める

pnpm

pnpm dev

これは arkor dev を実行し、Studio を http://localhost:4000 で起動します。Studio は UI で、arkor dev 自体は学習を開始することも、トレーナーファイルを監視することもしません。

ブラウザーで Run training をクリック。Studio はバックグラウンドでマネージドバックエンドにジョブを投入し、出力をページにストリーム表示します。最初に何らかの操作を行ったタイミングで匿名ワークスペースが自動作成されます。サインアップもクレジットカードも不要です。

学習が進行中に重要なビューは 3 つあります:

• Jobs。 学習ジョブの一覧。クリックするとライブステータスが見られます。
• Loss チャートとイベントログ。 マネージド GPU から進捗がストリームされるにつれて、Loss（学習中のモデルの誤差を示す数値で、低いほどモデルが正解に近づいているサイン）の曲線が更新され、ログのテールに学習イベントが表示されます。最初の学習はテンプレートにより 7〜12 分かかります。
• Playground。 ジョブが完了したら、最終アダプターをセレクターから選んでチャット。モード切替でベースモデルとアダプターを行き来できます。学習中に中間チェックポイントで推論を走らせたい場合は Studio ではなく onCheckpoint コールバックを使ってください。

学習の合間に src/arkor/ を編集した場合は、Run training ページをリロード（または arkor build を実行）してから次のクリックをすると、新しいコードが動きます。

​

4. アカウントに紐づける（任意）

匿名ワークスペースは試用には便利ですが、作業はローカルの匿名トークンに紐づくため、別の環境や別のアカウントからは見えません。学習をアカウントに残したい場合は、次の学習を始める前に OAuth でサインインしてください。

pnpm

pnpm arkor login --oauth

これでループバックポート上で Arkor Cloud の OAuth（PKCE）フローが走り、ローカルの認証情報がアカウントに紐づきます。以降、この環境からの学習はどのデバイスからも当該アカウントの下に表示されます。

生成されたプロジェクトは arkor をローカル devDependency としてインストールするので、CLI をグローバルにインストールしていない限り、素の arkor ではなく利用しているパッケージマネージャーのローカル bin 実行コマンドを使ってください。生成される README には pnpm / npm / yarn / bun の各パッケージマネージャーでのセットアップ手順が並列で書かれています。

注意点として、arkor login をフラグなしで実行すると初期選択が Anonymous の対話ピッカーが出ます。これを受け入れると新しい匿名トークンが発行されて認証情報ファイルが上書きされ、それまでの匿名ワークスペースのジョブとは別の ID になります（OAuth に切り替えても同様で、過去の匿名作業はアカウント側へ自動で移行されません）。匿名で先に始めてしまった作業をあとからアカウントに統合する機能は将来的にサポート予定です。それまでは、アカウントに残したい学習はサインインを済ませてから開始してください。

​

5. 次に読むもの

• コンセプト。 Concepts を読み、createArkor、createTrainer、ライフサイクルコールバック、Studio のメンタルモデルを構築してください。
• トレーナーをカスタマイズ。 src/arkor/trainer.ts を開き、lora.r や maxSteps を調整したり、コールバックを追加したり。Run training ページをリロード（または arkor build）してから次のクリックで反映されます。
• 別のテンプレートを試す。 プロジェクト生成ツールを別の --template で再実行して比較してみてください。