Local 開発

このページの内容

UI と backend を個別に動かす
独自の backend runtime を使う

Local 開発では、2 つのターミナルで 2 つの独立した process を動かします。あなたがアプリの watcher を所有し、CLI が Development session と、手元のマシンへ届く tunnel を所有します。Sota CLI があなたの process を起動・再起動・停止することは一切ありません。Session を止めたときも同様です。

ターミナル

# terminal 1 — アプリの watcher
npm run dev

# terminal 2 — Development session と tunnel
npm run dev:sota   # sota dev と同じ

Watcher を起動

npm run dev を実行します。Backend と native UI の両方を含む scaffold では、この 1 コマンドで両方が動きます。concurrently が backend watcher と UI watch build を backend／ui というラベルで並行起動し、--kill-others により片方が落ちたら対で停止します。片側だけが動き続ける状態になりません。

Development を開く

sota dev を実行して organization と workspace を選び、process を起動したままにします。CLI はまず local ですべてを準備し——manifest の compile、build 済み frontend output の検証、tunnel transport の確立——その後に session を 1 回の commit で公開します。準備中に失敗した場合、server 側には何も作られません。

安全に反復

CLI は compile 済み manifest の元になったすべてのファイル——manifest 本体、JSON Schema、locale ファイル、native asset、inline 化された skill 本文——を監視し、変更があれば個人 session へ再同期します。Compile error は diagnostics を表示するだけで、last-known-good manifest は置き換えません。15 秒ごとの heartbeat が session の lease を延長します。

停止

sota dev stop を実行するか、sota dev のターミナルで Ctrl-C を押します。Development app は消え、Core 管理のデータ cleanup が予約されます。あなたの frontend／backend process はそのまま動き続けます——CLI が終了時に明示的にそう表示します。

UI と backend を個別に動かす#

npm run dev は、独立して存在する 2 つの script をまとめた便宜的な wrapper にすぎません。片方だけ再起動したいとき、片方だけに debugger を接続したいとき、そして何より backend が Node.js の process でないときは、個別に実行してください。

Script	実際に動くもの	備考
`npm run dev`	`concurrently --kill-others --names backend,ui "tsx watch src/backend/server.ts" "sota contracts ensure && vite build --watch"`	両方を同時に。Backend のみ／UI のみの project ではその片方だけになります。
`npm run dev:backend`	`tsx watch src/backend/server.ts`	アプリの HTTP service。Source 変更で再起動します。`PORT`（既定 `8787`）で listen します。
`npm run dev:ui`	`sota contracts ensure && vite build --watch`	Dev server ではなく watch build です。App UI type contract を更新し、変更のたびに `dist/ui/app.js` と `dist/ui/app.css` を build し直します。
`npm run dev:sota`	`sota dev`	Development session、manifest 同期、tunnel。上の 2 つとは独立しています。

Local の UI server が存在しないのは意図的です。

Native UI は localhost ではなく SotaAgents の host 内で動きます。dev:ui は build 済み module をディスク上で最新に保つだけでよく、その bytes をそのまま tunnel が platform に配ります。だからこそ、deploy 済み artifact に packaging された後もまったく同じファイルが動作します。

独自の backend runtime を使う#

Scaffold が TypeScript と Express なのは広く理解されているからで、platform の要求ではありません。SotaAgents と backend の間の contract は素の HTTP と検証済み token だけなので、Go、Python、Java、Rust の service も一級の app backend です。SotaAgents の system app の一つは FastAPI の service で、まったく同じ invocation token を、同じ Core JWKS endpoint に対して Python で検証しています。

その場合、Node の backend script は単に使いません。自分の stack のやり方で service を起動し、UI があるなら native UI 用に npm run dev:ui を残し、local overlay を service の listen ポートに向けます。

ターミナル

# terminal 1 — 自分の言語で書いた backend
uvicorn app.main:app --reload --port 8787

# terminal 2 — native UI の watch build（UI がある場合のみ）
npm run dev:ui

# terminal 3 — Development session
sota dev

sota dev は Local Backend Endpoint を次の順で解決します：--local-url flag、manifest の environments.local.service.baseUrl、最後に使った endpoint（.sota/dev.json に記憶）。対話的なターミナルではいずれも無ければ入力を求め、そうでなければ LOCAL_BACKEND_UNAVAILABLE で失敗します。その後 CLI は約 1 秒ごとにその endpoint を polling し、[backend] available／[backend] unavailable を表示します。この確認は情報提供のみで、session の公開を妨げません。Backend が一時的に落ちても Development app は失われません。

Live session は個人用です。

1 developer・1 workspace に属します。再実行は自分の session だけを置換し、共有 Staging にはなりません。Staging と Production が tunnel に依存することはなく、host 済み backend を直接呼び出します。