Preloop

🚀 Preloop: AIエージェント用ポリシーエンジン

Preloopは、AIエージェントの行動を完全に制御できる包括的なMCPファイアウォールです。アクセスポリシー、承認ワークフロー、および監査トレイルを定義できます。条件に基づいて、許可、拒否、または承認を要求することができます。

Preloopは、管理されたランタイム用のAIワークフォースコントロールプレーンとしても進化しています。フローは、Preloopが所有するOpenAI互換ゲートウェイを介してモデルトラフィックをルーティングできるようになり、使用状況、支出、ランタイムID、および予算を集中的に管理できます。

OpenClaw、Claude Code、Cursor、Codex、およびすべてのMCP互換エージェントと互換性があります。

公式ドキュメントを読む: 完全なガイドとチュートリアルは、docs.preloop.aiで入手できます。

🚀 クイックスタート

AIエージェントであるClaude Code、Cursor、OpenClawなどは、私たちの仕事のやり方を変革しています。しかし、大きな力には大きなリスクも伴います。Preloopは、これらのリスクを解決し、安全な操作を可能にするポリシーを定義できます。

✨ 主な機能

アクセスポリシー

任意のAIツールまたは操作に対して、細かいアクセス制御を定義できます。

• ツールは複数の順序付けられたアクセスルールをサポートします（単純な承認/拒否だけでなく）。
• ルールは優先順位で評価され、最初に一致するルールが適用されます。
• 各ルールには、アクション（許可/拒否/承認要求）、オプションのCEL条件、およびオプションの拒否メッセージがあります。
• ルールは、UIでドラッグアンドドロップで並べ替えることができます。

承認ワークフロー

AIが保護された操作を試みると、Preloopは一時停止し、通知を送信します。

• モバイルアプリ、メール、Slack、またはMattermostを介した即時通知
• 携帯電話、ウォッチ、またはデスクトップからのワンタップ承認
• 非同期承認モード — ツールはすぐに戻り、エージェントは承認されるまでget_approval_statusをポーリングし、その後ツールの結果を受け取ります（Enterprise）
• ツールごとの正当化 — 承認前にエージェントにツールを呼び出す理由を説明することを要求またはオプションで要求します（Enterprise）
• チームベースの承認 クォーラム要件付き（Enterprise）
• エスカレーションポリシー 時間に敏感な操作の場合（Enterprise）

ポリシーアズコード

YAMLでポリシーを定義し、CLIまたはAPIを介して管理できます。

# 例: 本番デプロイに承認を要求する
version: "1.0"
metadata:
  name: "Production Safeguards"
  description: "Require approval before deploying to production"
  tags: [security, production]

approval_workflows:
  - name: "deploy-approval"
    timeout_seconds: 600
    required_approvals: 1
    async_approval: true          # エージェントはブロックせずにポーリングする

tools:
  - name: "bash"
    source: mcp
    approval_workflow: "deploy-approval"
    justification: required        # エージェントは呼び出しの理由を説明する必要がある
    conditions:
      - expression: "args.command.contains('deploy') && args.command.contains('production')"
        action: require_approval
        description: "Production deployments require approval"

• コードと一緒にポリシーをバージョン管理します。
• ポリシー変更のためのGitOpsワークフロー
• 自動化とスクリプト用のCLI管理
• プログラムによるポリシー管理のためのAPIアクセス

完全な監査トレイル

すべてのAIアクションは、完全なコンテキストとともにログに記録されます。

• 試行された内容（ツール、パラメータ、コンテキスト）
• どのポリシーが一致したかとその理由
• 誰が承認または拒否したか（およびいつ）
• 実行結果と時間

セキュリティレビュー、コンプライアンス、およびデバッグに不可欠です。

AIモデルゲートウェイ

Preloopは、管理されたランタイムの代わりにモデルトラフィックを終端でき、エージェントコンテナにプロバイダの資格情報を直接渡す必要はありません。

• OpenAI互換ゲートウェイエンドポイント: GET /openai/v1/models, POST /openai/v1/chat/completions, POST /openai/v1/responses
• Anthropic互換ゲートウェイエンドポイント: POST /anthropic/v1/messages
• チャット補完と応答のSSEストリーミングサポート
• アカウント、フロー、フロー実行、APIキー、およびランタイムプリンシパルへのリクエストごとの属性付け
• トークンと推定コストの会計をゲートウェイ使用履歴台帳に保持
• アカウントレベルとフローレベルの予算管理（ソフトリミットアノテーションとハードストップ付き）
• アカウントとフローの監視のための製品向け使用状況要約エンドポイント
• フローを超えた管理セッションを閲覧するためのアカウントスコープのランタイムセッションエクスプローラエンドポイント
• GET /api/v1/flows/executions/{execution_id}/gateway-eventsを介した実行スコープのゲートウェイイベントの検査
• 最近のランタイムセッションを閲覧し、キャプチャされたゲートウェイインタラクションを検索するためのコンソール画面

シークレット管理

Preloopは、プロバイダに依存しないシークレット抽象化の背後にAIモデルの資格情報を保存するようになりました。

• シンプルなセルフホストデプロイメント用の組み込みlocal_encryptedバックエンド
• フロー実行用のハッシュのみのランタイムAPIトークン
• Vault/OpenBao互換のKV v2ストア用のオプションの外部シークレットバックエンドパス
• エージェントランタイムは、プロバイダのシークレットの代わりに短期間有効なPreloopゲートウェイトークンを受け取ることができます。

AWS Agent Coreとの比較

Preloopは、ベンダーに依存しないセルフホストAIガバナンスを望むチームにとって、AWS Agent Coreのオープンソース代替案です。

AIエージェント -> Preloop -> [ポリシーチェック] -> 許可 / 拒否 / 承認要求 -> 実行

動作原理:

1. 各ツールに対してポリシーを定義します: 許可、拒否、または承認を要求します。
2. ポリシーは細かく設定でき、パラメータ値とコンテキストをチェックできます。
3. AIエージェントは、PreloopのMCPプロキシを介してツールを呼び出します。
4. アクションは、あなたのポリシーに基づいて許可、拒否、または承認のために一時停止されます。
5. すべてのアクションと決定の完全な監査トレイルが記録されます。

キー機能

安全性とコントロール

• ポリシーエンジン 任意のツールまたはアクションに対して、許可、拒否、および承認ワークフローを定義します。
• アクセスルール 各ツールに複数の順序付けられたルールがあり、許可/拒否/承認要求のアクションがあります。
• ドラッグアンドドロップによる優先順位設定 ルールの評価優先順位を視覚的に並べ替えます。
• 細かいルール ポリシーは、ツール名、パラメータ値、およびコンテキストをチェックできます。
• 即時通知 モバイル、メール、Slack、またはMattermostでアラートを受け取ります。
• ワンタップ承認 携帯電話、ウォッチ、またはデスクトップから承認または拒否します。
• 完全な監査トレイル すべてのAIアクションとポリシー決定の完全なログ。
• 非同期承認モード 非ブロッキング承認: ツールはすぐに戻り、エージェントは人間が決定するまでget_approval_statusをポーリングします。
• ツールごとの正当化 エージェントに各ツール呼び出しの理由を提供することを要求します。モード: required（理由がないとブロック）またはoptional（エージェントが提供する場合がある）
• 柔軟な条件 CEL式を使用したコンテキスト認識ルール（Enterprise）
• AIによる承認 (Enterprise) 構成可能なモデル、プロンプト、信頼度閾値、およびフォールバック動作を持つAI駆動の承認
• チーム承認 重要な操作に対して複数のチームメンバーからのクォーラムを要求します（Enterprise）

統合と互換性

• MCPプロキシ 任意のModel Context Protocol互換のAIエージェントと互換性があります。
• インフラストラクチャの変更不要 ドロップインソリューションで、コードの変更は必要ありません。
• 組み込みツール イシューとPR/MR管理用の11のツールが含まれています。
• 外部MCPサーバー 任意の外部MCPサーバーをPreloopのセーフティレイヤーを介してプロキシできます。
• イシュートラッカーの同期 Jira、GitHub、GitLabを接続して完全なコンテキストを取得します。

自動化プラットフォーム

• エージェントフロー Webhook、スケジュール、またはトラッカーイベントによってトリガーされるイベント駆動型のワークフローを構築します。
• ゲートウェイ経由のモデルアクセス 管理されたフローは、Preloopが所有するモデルゲートウェイを使用して、集中的なコスト管理、テレメトリ、およびキー管理を行うことができます。
• ベクトル検索 埋め込みを使用したインテリジェントな類似性検索。
• 重複検出 自動的に重複するイシューを識別します。
• コンプライアンスメトリクス イシューの品質を評価し、改善します。
• Web UI Lit、Vite、およびShoelaceで構築されたモダンなインターフェイス。

エンタープライズ機能を探していますか？ Preloopエンタープライズエディションには、RBAC、チームベースの承認、高度な監査ログなどが追加されています。詳細は、以下のエンタープライズ機能を参照してください。

オープンソースとエンタープライズの比較 (重要)

• オープンソース: メール、モバイルアプリ、Slack、およびMattermost通知を伴う単一ユーザー承認。
• エンタープライズ: 高度な条件 (CEL)、チームベースの承認 (クォーラム)、およびエスカレーションが追加されます。
• モバイルとウォッチアプリ: iOS/ウォッチおよびAndroidアプリは、セルフホスト/オープンソースのPreloopデプロイメントで使用できます。

サポートされるイシュートラッカー

• Jira CloudおよびServer
• GitHub Issues
• GitLab Issues
• （将来のリリースで、Azure DevOpsやLinearなどが追加される予定）

📚 詳細ドキュメント

アーキテクチャ

Preloopは、AIエージェント用の安全なコントロールプレーンを提供するために設計されたモジュール型アーキテクチャを備えており、コアAPIサーバー、データベースモデル、バックエンド同期サービス、およびWebフロントエンドコンソールが分離されています。

システムコンポーネント、データフロー、およびインフラストラクチャの完全な概念的な概要については、アーキテクチャドキュメントを参照してください。

フロントエンドとCLI

• Preloopコンソール (フロントエンド): frontendディレクトリにあり、ガバナンスコントロール、ツール管理、およびダッシュボードの可視性を提供するWebインターフェイスです。詳細は、frontend/README.mdを参照してください。
• Preloop CLI: コマンドラインからポリシーとシステム状態を管理します。使用方法については、cli/README.mdを参照してください。

📦 インストール

前提条件

• Python 3.11以上
• PostgreSQL 14以上
• PostgreSQLのPGVector拡張機能（ベクトル検索機能のため）

ローカルセットアップ

# リポジトリをクローンする
git clone https://github.com/preloop/preloop.git
cd preloop

# 仮想環境を作成してアクティブ化する
python -m venv .venv
source .venv/bin/activate  # Windowsの場合は: .venv\Scripts\activate

# 依存関係をインストールする
pip install -e ".[dev]"

# データベースをセットアップする

# 環境を構成する
cp .env.example .env
# .envを設定に合わせて編集する

設定

環境変数

Preloopは環境変数を介して構成されます。.env.exampleを.envにコピーし、必要に応じてカスタマイズしてください。

コア設定

モデルゲートウェイとシークレット

機能フラグ

自己登録の無効化

システムへのアクセスを制御したいプライベートデプロイメントの場合:

# .envファイルまたはDocker環境で
REGISTRATION_ENABLED=false

登録が無効になっている場合:

• UIから「サインアップ」ボタンが非表示になります。
• /registerページは/loginにリダイレクトされます。
• /api/v1/auth/register APIエンドポイントは403 Forbiddenを返します — 直接のAPI登録試行を防止します。
• 新しいユーザーは管理者によって招待される必要があります。

セキュリティに関する注意: REGISTRATION_ENABLED=falseの場合、バックエンドAPIはエンドポイントレベルで制限を強制します。APIを介した登録試行（スクリプトまたは直接のHTTPリクエストを含む）はすべて、403ステータスコードで拒否されます。

登録が無効になっている場合にユーザーを招待するには、管理者APIまたはCLIを使用してください（エンタープライズエディションにはユーザー管理用の完全な管理者ダッシュボードが含まれています）。

GitHubアプリ (オプション)

PRステータスチェックやボットのリアクションなどの高度なGitHub統合を行うには:

これらはオプションで、GitHubアプリを認証またはPRのリアクション管理などの高度な機能に使用する場合にのみ必要です。

OAuthサインイン (エンタープライズ)

GitHub、Google、および/またはGitLabを介したOAuthサインイン/サインアップを有効にします。ユーザーは既存のプロバイダーアカウントで認証でき、Preloop固有のパスワードを作成する必要はありません。

GitHub OAuthサインインは、上記のGitHubアプリの資格情報を再利用します。Helm値を介して有効にします。

mcpOauth:
  enabled: true
googleOauth:
  enabled: true
  clientId: "your-google-client-id"
  clientSecret: "your-google-client-secret"
gitlabOauth:
  enabled: true
  clientId: "your-gitlab-client-id"
  clientSecret: "your-gitlab-client-secret"

サポートされるフロー:

• GitHub: サインイン + 自動トラッカー設定プロンプト
• Google: サインインのみ (トラッカーは作成されません)
• GitLab: サインイン + 自動トラッカー設定プロンプト

MCP OAuth 2.1サーバー

Preloopには、MCPクライアント認証用の組み込みOAuth 2.1認可サーバーが含まれています（例: Claude Desktop）。mcpOauth.enabled=trueの場合、自動的に有効になります。

ディスカバリエンドポイント:

• GET /.well-known/oauth-authorization-server — RFC 8414メタデータ
• GET /.well-known/oauth-protected-resource — RFC 9728メタデータ

OAuthエンドポイント:

• POST /oauth/register — 動的クライアント登録 (RFC 7591)
• GET /oauth/authorize — 認可エンドポイント (同意ページにリダイレクト)
• POST /oauth/token — トークン交換 (MCPの場合はAuthorization Code + PKCE、CLIの場合はJWT)
• POST /oauth/revoke — トークン失効

Dockerセットアップ

# リポジトリをクローンする
git clone https://github.com/preloop/preloop.git
cd preloop

# 完全な開発スタックを実行する (バックエンド + ワーカー + HMR付きのフロントエンド)
docker compose up

# タグ付きのリリースイメージで実行する (本番環境)
PRELOOP_VERSION=0.8.0 SECRET_KEY=$(openssl rand -hex 32) \
  docker compose -f docker-compose.release.yaml up -d

クイックインストーラーも利用可能です。

# スタンドアロンCLIをインストールする
curl -fsSL https://preloop.ai/install/cli | sh

# OSSスタックをインストールする
curl -fsSL https://preloop.ai/install/oss | sh

どちらのコマンドの前にもPRELOOP_VERSION=0.8.0を設定して特定のリリースを固定するか、https://preloop.ai/install/<script>?version=0.8.0を使用してください。

デフォルトのdocker compose upコマンドは、ローカル開発用にdocker-compose.override.ymlを使用するため、backend/とfrontend/のソース変更は直接コンテナにマウントされます。フロントエンドはViteを介してhttp://localhost:5173で実行され、バックエンドAPIはhttp://localhost:8000に留まります。

完全な構成と必要な環境変数については、を参照してください。

リリース管理

リリーススクリプトを使用して、主要なリリース面で新しいバージョンを準備します。

./scripts/release.sh 0.8.0

このスクリプトは、オプションでリリース準備をコミットし、v<version>を作成してプッシュし、ghでGitHubのReleaseワークフローを監視することもできます。

完全なチェックリストについては、を参照し、リリース準備ヘルパーについては、を参照してください。

Kubernetesセットアップ

Preloopは、提供されているHelmチャートを使用してKubernetesにデプロイできます。

# Spacecode Helmリポジトリを追加する (利用可能な場合)
# helm repo add spacecode https://charts.spacecode.ai
# helm repo update

# ローカルチャートからインストールする
helm install preloop ./helm/preloop

# またはGitHubリリースからパッケージ化されたチャートをインストールする
# helm install preloop https://github.com/preloop/preloop/releases/download/v0.8.0-beta.3/preloop-0.8.0-beta.3.tgz

# またはカスタム値でインストールする
helm install preloop ./helm/preloop --values custom-values.yaml

Helmチャートの詳細については、チャートREADMEを参照してください。

💻 使用例

サーバーの起動

1. 環境変数を設定する: 必要な環境変数が設定された.envファイルがあることを確認してください（.env.exampleを参照）。重要な変数には、データベース接続詳細、APIキーなどが含まれます。
2. Preloop APIを起動する: 提供されているスクリプトを使用して、メインAPIサーバーを起動します。

   ./start.sh
   

   このスクリプトは通常、仮想環境をアクティブ化し、サーバーを実行します（例: python -m preloop.server）。
3. Preloop同期サービスを起動する: 別のターミナルで、同期サービスを起動して、構成されたトラッカーからデータをインデックス化し始めます。

   # 仮想環境がまだアクティブでない場合はアクティブ化する
   # source .venv/bin/activate
   preloop-sync scan all
   

   このコマンドは、Preloop Syncにすべての構成されたトラッカーをスキャンし、データベースを更新するように指示します。

APIドキュメント

実行中のとき、APIドキュメントは以下のURLで利用可能です。

http://localhost:8000/docs

OpenAPI仕様も以下のURLで利用可能です。

http://localhost:8000/openapi.json

REST APIの使用

PreloopはRESTfulなHTTP APIを提供します。

import requests
import json

# Preloop APIのベースURL
base_url = "http://localhost:8000/api/v1"

# 認証してトークンを取得する
auth_response = requests.post(
    f"{base_url}/auth/token",
    json={"username": "your-username", "password": "your-password"}
)
token = auth_response.json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}

# トラッカーの接続をテストする
connection = requests.post(
    f"{base_url}/projects/test-connection",
    headers=headers,
    json={
        "organization": "spacecode",
        "project": "astrobot"
    }
)
print(json.dumps(connection.json(), indent=2))

# 認証に関連するイシューを検索する
results = requests.get(
    f"{base_url}/issues/search",
    headers=headers,
    params={
        "organization": "spacecode",
        "project": "astrobot",
        "query": "authentication problems",
        "limit": 5
    }
)
print(json.dumps(results.json(), indent=2))

# 新しいイシューを作成する
issue = requests.post(
    f"{base_url}/issues",
    headers=headers,
    json={
        "organization": "spacecode",
        "project": "astrobot",
        "title": "Improve login error messages",
        "description": "Current error messages are not clear enough...",
        "labels": ["enhancement", "authentication"],
        "priority": "High"
    }
)
print(json.dumps(issue.json(), indent=2))

🔧 技術詳細

APIエンドポイント

Preloopは、認証、ツール管理、承認ワークフロー、ポリシー生成、および統合のための包括的なREST APIを提供します。

完全なREST APIリファレンス（インタラクティブなSwaggerエンドポイントを含む）については、公式APIドキュメントを参照してください。

統一WebSocket

Preloopは、アプリケーション全体のリアルタイム更新に統一WebSocket接続を使用します。 接続: ws://localhost:8000/api/v1/ws/unified

メッセージルーティング:

• フロー実行更新 (flow_executionsトピック)
• 承認要求通知 (approvalsトピック)
• システムアクティビティ更新 (activityトピック)
• セッションイベント (systemトピック)

機能:

• 指数関数的バックオフによる自動再接続
• サブスクライバーへのPub/Subメッセージルーティング
• 効率的なメッセージ配信のためのトピックベースのフィルタリング
• アクティビティ追跡によるセッション管理
• ハートビート監視

フロントエンドでの使用:

import { unifiedWebSocketManager } from './services/unified-websocket-manager';

// フロー実行更新を購読する
const unsubscribe = unifiedWebSocketManager.subscribe(
  'flow_executions',
  (message) => console.log('Flow update:', message),
  (message) => message.execution_id === myExecutionId  // オプションのフィルター
);

// 完了したらクリーンアップする
unsubscribe();

APIを介したMCPツールの使用

Preloop APIには、動的なツールフィルタリングを備えた統合MCPツールエンドポイントが含まれており、任意のHTTPベースのMCPクライアントが直接接続できます。

docs.preloop.aiのMCP統合ガイドを読んで、Claude Code、Cursor、Windsurfなどのクライアントを認証し、ワークフローやタイムアウトを設定する詳細を確認してください。

モバイルプッシュ通知 (iOS/Android)

オープンソースユーザーは、https://preloop.aiの本番Preloopサーバーを介してリクエストをプロキシすることで、モバイルプッシュ通知を有効にすることができます。

セットアップ手順:

1. https://preloop.aiでアカウントを作成します。
2. 設定ページからpush_proxyスコープを持つAPIキーを生成します。
3. これらの環境変数でインスタンスを構成します。

# プッシュ通知プロキシの構成
PUSH_PROXY_URL=https://preloop.ai/api/v1/push/proxy
PUSH_PROXY_API_KEY=your-api-key-here

4. Preloopコンソールの通知設定ページでプッシュ通知を有効にします。
5. 通知設定で表示されるQRコードをスキャンしてモバイルデバイスを登録します。

設定が完了すると、承認要求が登録されたiOSまたはAndroidデバイスにプッシュ通知をトリガーします。

注意: モバイルアプリ（iOS/ウォッチおよびAndroid）は、セルフホストのPreloopインスタンスで動作するように設計されています。QRコードから抽出されたサーバーURLに接続します。

バージョンチェックと更新

デフォルトでは、Preloopは起動時と毎日1回、https://preloop.aiに接続してバージョン更新をチェックします。これにより、新しいリリースやセキュリティ更新に関する情報を得ることができます。

プライバシー: インスタンスのUUID、バージョン番号、およびIPアドレスのみが送信されます。ユーザーデータは送信されません。

オプトアウト: PRELOOP_DISABLE_TELEMETRY=trueまたはDISABLE_VERSION_CHECK=trueを設定すると、バージョンチェックとテレメトリを完全に無効にすることができます。

詳細なアーキテクチャについては、ARCHITECTURE.mdを参照してください。

テスト

Preloopは、ユニットテストと統合テストにpytestを使用しています。テストスイートは、APIエンドポイント、データベースモデル、およびトラッカー統合をカバーしています。

テストの実行

すべてのテストを実行するには:

# すべてのテストを実行する
pytest

# 詳細な出力で実行する
pytest -v

# 特定のテストファイルを実行する
pytest tests/endpoints/test_webhooks.py

# 特定のテストケースを実行する
pytest tests/endpoints/test_webhooks.py::TestWebhooksEndpoint::test_github_webhook_valid_signature

テスト構造

• ユニットテスト: tests/ディレクトリにあり、個々のコンポーネントを分離してテストします。
• 統合テスト: コンポーネント間の相互作用をテストします。
• エンドポイントテスト: モックされたデータベースセッションを使用してAPIエンドポイントをテストします。

ウェブフックのテスト

ウェブフックエンドポイントのテスト（tests/endpoints/test_webhooks.py）は、以下を検証します。

1. GitHubとGitLabのウェブフックの署名/トークンによる認証
2. 無効な署名、欠落したトークンなどのエラー処理
3. 組織識別子の解決
4. データベースの更新（last_webhook_updateタイムスタンプ）
5. データベースエラーのエラー処理

これらのテストは、外部依存関係からウェブフック処理ロジックを分離するためにモッキングを使用しています。

ロードマップ

Preloopは、AIエージェント用の包括的なコントロールプレーンに進化しています。これからの予定は以下の通りです。

• 🔜 エージェントレジストリ — AIエージェントを主要なエンティティとして登録、資格付与、および管理します。
• 🔜 AIモデルゲートウェイ — コスト追跡、レート制限、および使用状況分析を備えた統一モデルプロキシ。
• 🔜 エージェント監視 — エージェントのアクティビティ、支出、および健全性のリアルタイム可視性。
• 🔜 予算管理 — エージェントごとの支出上限とアラートおよび強制力。

リポジトリにスターを付け、更新をお待ちください！

エンタープライズ機能

Preloopエンタープライズエディションは、オープンソースのコアに、チームや組織向けの追加機能を拡張しています。

エンタープライズエディションのライセンスについては、sales@preloop.aiにお問い合わせください。

コントリビュート

コントリビューションは歓迎されます！詳細な開始方法については、コントリビューションガイドを参照してください。

1. リポジトリをフォークします。
2. 機能ブランチを作成します (git checkout -b feature/amazing-feature)。
3. 変更をコミットします (git commit -m 'Add some amazing feature')。
4. ブランチにプッシュします (git push origin feature/amazing-feature)。
5. プルリクエストを作成します。

📄 ライセンス

Preloopは、Apache License 2.0の下でライセンスされたオープンソースソフトウェアです。

Copyright (c) 2026 Spacecode AI Inc.