ローカルエージェント API

Sentinelデーモンは、ローカルのUnixソケット/run/simaai-sentinel/api.sockを介して、バージョン管理されたHTTP/JSON APIを公開します。 TCPポートでリッスンすることはありません。 APIとターミナルUIは同じキャッシュとロックされたチェックポイントストアを使用するため、エージェントが開始したトレースはUIとCLIですぐに確認できます。

curl --unix-socket /run/simaai-sentinel/api.sock http://localhost/v1/health

エンドポイント

メソッドとパス	目的
`GET /v1/health`	バージョン、データの鮮度、サンプル数とメトリック数、エラー、およびアクティブなトレース。
`GET /v1/cache`	ライブキャッシュドキュメント全体。
`GET /v1/metrics`	メトリックの定義、単位、説明、および閾値。
`GET /v1/samples/latest`	タイムスタンプ付きの最新のメトリック値。
`GET /v1/traces/active`	アクティブなトレース、または`null`。
`POST /v1/traces`	名前付きトレースを開始します。
`POST /v1/traces/stop`	アクティブなトレースを停止して保存します。
`POST /v1/traces/{id}/stop`	アクティブなトレースのIDがまだ一致する場合にのみ、そのトレースを停止します。
`GET /v1/runs`	アクティブな実行と完了した実行の概要を一覧表示します。
`GET /v1/runs/{name-or-id}`	保存された実行とその生サンプルを取得します。
`GET /v1/compare?runs=A,B`	2つ以上の実行を比較します。最初の実行がベースラインになります。
`GET /v1/peripherals`	接続されている周辺機器をメモリから返します。
`POST /v1/peripherals/refresh`	再スキャンしてから、新しいカタログを返します。

開始リクエストの例：

curl --unix-socket /run/simaai-sentinel/api.sock \
  -H 'Content-Type: application/json' \
  -d '{"name":"baseline","note":"before optimization","tags":["compiler-v1"]}' \
  http://localhost/v1/traces

アクティブなトレースを停止します：

curl --unix-socket /run/simaai-sentinel/api.sock \
  -X POST http://localhost/v1/traces/stop

先にアクティブなトレースを読み取ったクライアントは、停止するときにそのIDを含めてください：

curl --unix-socket /run/simaai-sentinel/api.sock \
  -X POST http://localhost/v1/traces/20261004T120000.000Z-baseline/stop

別のクライアントがトレースを置き換えた場合、条件付きの形式は何も停止せずにHTTP 409を返します。IDの比較と停止は、同じ実行ストアのロックの下で行われます。

名前は一意である必要があり、アクティブにできるトレースは1つだけです。競合するライフサイクル操作はHTTP 409を返します。不明な実行とルートはHTTP 404を返します。無効なリクエストはHTTP 400を返します。利用できないメトリックについて、レスポンスはJSON nullを使用します。比較レスポンスには、デフォルトで実行メタデータ、統計、およびベースラインとの差分が含まれます。タイムスタンプ付きのサンプルが必要な場合にのみ、raw=1を追加してください。

周辺機器

検出スレッドは、デーモンの起動時、カーネルがデバイスの変更を通知したとき、およびリフレッシュ要求があったときに、ボードの周辺機器をスキャンします。デバイスプロバイダーはカーネルインターフェースを読み取るだけで、ストリームを開くことはありません。 boardブロックのU-Bootオーバーレイリストを読み取るため、各スキャンではfw_printenv -n dtbosも rootとして実行されます。環境を変更することはありませんが、環境のロックを取得するため、 /var/lock/fw_printenv.lockが作成されます。GET /v1/peripheralsは最新の結果を返します：

{"revision": 1791155282460, "observed_at": "2026-10-04T23:08:02.460Z",
 "board": {"model": "SiMa.ai Modalix SoM 16Gig Board", "configured_cameras": [...], ...},
 "devices": [{"type": "camera", "id": "camera:v4l2:3f2a9c0d41b7e650", ...}],
 "errors": [{"provider": "camera.v4l2", "code": "io.permission_denied", "reason": "..."}]}

フィールド	意味
`revision`	`board`、`devices`、または`errors`が変わるたびに変化します。デーモンの起動時にランダムな値から始まるため、再起動や時刻の変更によって同じ値が繰り返される可能性は非常に低くなっています。比較は等価性の判定にのみ使用してください。値は常に2^52未満であるため、倍精度浮動小数点数を使用するJSONリーダーでも正確に表現されます。
`observed_at`	この結果の元になったスキャンの開始時刻。最初のスキャンが完了するまでは`null`です。
`board`	カメラ向けのボードの設定：モデル、U-Bootが適用するオーバーレイ、デバイスツリーが構成するカメラ（カタログに該当するカメラがある場合は、それぞれのセンサーにあたる`camera.mipi`カメラの`id`を含みます）、およびインストール済みのオーバーレイがサポートするセンサー。`devices`と同じスキャンで読み取られます。最初のスキャンが完了するまでは存在しません。ボードのカメラ構成を参照してください。
`devices`	デバイスごとに1つのオブジェクトで、`type`でタグ付けされます。`id`は同じポートへの再接続後も変わらず、`/dev/videoN`の名前になることはありません。
`errors`	最新のスキャンで失敗したプロバイダー、および`board`ブロックのうち完全には読み取れなかったフィールド（プロバイダー`board.<field>`、たとえば`board.overlays`）。失敗したプロバイダーのデバイスは、最後に成功したスキャンの結果が`devices`に残り、失敗した`fw_printenv`は最後のオーバーレイリストを保持します。`hotplug.unavailable`は、カーネルのueventを受信できないため、再スキャンがリフレッシュ時にしか行われないことを意味します。

Sentinelはハードウェアの事実のみを報告します。アプリケーションがデバイスやモードをサポートするかどうかは、そのアプリケーションが判断します。

POST /v1/peripherals/refreshは、リクエスト後に開始されるスキャンを待ち、そのカタログをHTTP 200で返します。これはGETと同じドキュメントです。同時に行われたリフレッシュはスキャンを共有します。検出スレッドは各スキャンの後に1秒間休止するため、リフレッシュはスキャン開始まで最大でその時間だけ待つことがあり、リフレッシュを繰り返しても検出を動かし続けることはできません。スキャンが10秒以内に完了しない場合はHTTP 504を返し、すでに8件のリフレッシュ要求が待機している場合はHTTP 429を返します。検出が無効化されている場合（--no-peripherals）または停止している場合、どちらのルートもHTTP 503を返します。

simaai-sentinel peripheralsは同じ結果を表形式で出力します。生のドキュメントを得るには--jsonを、先に再スキャンするには--refreshを追加してください。

デバイスレコードはタイプごとに説明しています：USBカメラ、 MIPI CSI-2カメラ、マイク。boardブロックについてはボードのカメラ構成で説明しています。

peripherals/catalog-example.jsonは、 DevKitから取得した完全なレスポンスです（USBカメラはフォーマットごとに1つのモードに絞っています）。そのboardブロックは、キャプチャしたものではなくDevKitから書き写したものです。 Sentinelのテストがこれをスキーマに照らして検証しているため、クライアントはこれを基準にテストできます。

セキュリティと並行処理

このソケットはDevKit上のローカルなものであり、Sentinelがリモートに公開することはありません。 InsightやCLIなどのクライアントがroot権限なしで動作できるよう、意図的にローカルユーザーがアクセスできるようにしています。制御操作はテレメトリトレースの開始と停止、および周辺機器の再スキャン要求であり、 APIは実行の削除、ワークロードの実行、ハードウェアの変更を行いません。再スキャンは読み取りのみを行い、各スキャン後の1秒間の休止により、リフレッシュ要求が引き起こす処理量は制限されます。ローカルユーザーが8件のリフレッシュを待機させ続けると、他のリフレッシュはHTTP 429を返しますが、GETは引き続き動作します。リモートアクセスは、このソケットを転送したり認証なしのTCPリスナーを追加したりするのではなく、認証されたKerrigan/Fleet Managerプロキシによって提供する必要があります。

キャッシュの書き込みにはアトミックなリネームを使用します。実行操作には、CLI、TUI、デーモンレコーダーと同じ排他的ファイルロックを使用します。 IDを含む停止ルートは、クライアントが観測したトレースを置き換えたトレースを停止してはならない場合に使用してください。

エージェントスキル

インストール中、生成されたSentinelインストールスクリプトは、パッケージのビルド元である正確なSentinel Gitコミットを指定してsima-cli playbooks installを実行します。これにより、Vulcanアーティファクトにネストされたスキルリソースを追加することなく、ランタイムとスキルのリビジョンが揃います。プレイブックマネージャーは、サポートされている各エージェント向けにスキルをインストールし、そのソースコミットをローカルレジストリに記録します。

DevKitへのSentinelのインストールは常にsima-cli neat install sentinelから始まるため、通常、そこでは別途スキルをインストールする手順は必要ありません。 DevKitパッケージがインストールされていない環境（たとえばSDKコンテナーや開発者ワークステーション）で Sentinelスキルを使用するには、その環境のsima-cliを使用して、GitHubから直接スキルをインストールします：

sima-cli playbooks install gh:sima-neat/sentinel/skills/use-sentinel

mainに反映される前のリビジョンをテストするには、Git refを末尾に付加します：

sima-cli playbooks install --force \
  gh:sima-neat/sentinel/skills/use-sentinel@feature/checkpoint-run-comparison

スキルの更新や削除は、引き続きsima-cli playbooksで管理します。

エンドポイント​

周辺機器​

セキュリティと並行処理​

エージェントスキル​

エンドポイント

周辺機器

セキュリティと並行処理

エージェントスキル