本文へスキップ
Ankole

デプロイメント環境変数

AI Agent 向け: このページの Markdown 版は https://ankole.agentbull.com/ja-JP/docs/environment-variables/index.md、ドキュメント索引は https://ankole.agentbull.com/ja-JP/llms.txt にあります。

このページでは、PostgreSQL、Pod Base シャードデータベース、ankole-function-runtime、デプロイ用の秘密情報、オブジェクトストア、およびプロセス設定に関する起動時環境変数をまとめます。なお、Worker provider の構成自体は環境変数ではなく、PostgreSQL 内に YAML として保存されます。

インスタンス稼働中に管理者が動的に変更できるランタイム設定については、アプリケーション設定を参照してください。それらのランタイム設定を .env や Kubernetes Secret に記述しないでください。

ブートストラップと secret(プロセス起動)

以下の変数は、control plane を起動する前に設定しておく必要があります。Docker Compose では .env に、Helm chart では参照先の Secret に設定します。

変数 必須 意味
DATABASE_URL はい(prod) control plane(Ankole.Repo)用の PostgreSQL 18+ 接続文字列
BASE_DB_URLS いいえ 物理 Pod Base シャード(Ankole.Pod.BaseRepo)用の ; 区切り PostgreSQL 18+ 接続 URL(任意)。クエリパラメータ ankole_sharding、ankole_pool_size、ankole_stock_only に対応します。単一 DB の FOSS 構成で未設定の場合は DATABASE_URL を base_default として使用し、sslmode は拒否します
ANKOLE_SECRET_BASE はい(prod) サイト全体の secret base。暗号化キーや署名キーの導出に使われます
RELEASE_COOKIE はい(prod) Erlang distribution cookie。同一デプロイ内のすべての control plane ノードで同じ値を共有します
ANKOLE_FUNCTION_RUNTIME_TOKEN はい(prod) control plane と ankole-function-runtime が共有する内部 Bearer シークレット
ANKOLE_FUNCTION_RUNTIME_URL はい(prod) ankole-function-runtime の内部 HTTP URL(例:Compose では http://function-runtime:9000)
POSTGRES_PASSWORD バンドル版 PostgreSQL のみ PostgreSQL のパスワード(バンドル版 PostgreSQL を有効にした場合に必須。それ以外は DATABASE_URL または外部 Secret で指定)
ANKOLE_HOST Compose デプロイメントを公開する DNS ホスト名
ACME_EMAIL Compose Caddy が Let’s Encrypt の証明書発行に使う連絡先メールアドレス
ANKOLE_DOCKER_GID Compose Docker socket を所有するグループ ID。非特権ユーザーで動作する control plane がこのグループ権限で socket にアクセスします

これらの値は .env または Secret で厳重に管理し、バージョン管理システムには絶対にコミットしないでください。Docker Compose 環境では、付属の .env.example を初期テンプレートとして利用できます。

なお、Worker 用の認証キーを運用者が .env や Secret に用意する必要はありません。control plane が Worker ごとに専用の認証情報を発行して渡します。

Helm chart の values.yaml では、これらに対応する設定キーとして secrets.ankoleSecretBase、secrets.releaseCookie、secrets.functionRuntimeToken、secrets.databaseURL、secrets.baseDBURLs、secrets.postgresqlPassword、controlPlane.siteAdminConsolePath、functionRuntime.* が定義されています。

ランタイム調整(プロセス環境)

以下の変数はプロセス起動時に読み取られ、control plane や ankole-function-runtime の動作パラメータを調整します。秘密情報ではありません。

変数 デフォルト 意味
ANKOLE_ENV — デプロイメント環境のラベル(例:prod、dev)
ANKOLE_LOG_LEVEL info ログレベル(debug、info、warning、error)
POOL_SIZE 10 control-plane プロセスが直接読み取る Ankole.Repo のデータベース接続プールサイズ
ANKOLE_DATABASE_POOL_SIZE 10 Docker Compose 用の .env 変数(compose.yaml 内で POOL_SIZE にマッピングされます)
ANKOLE_POSTGRES_MAX_CONNECTIONS 300 バンドル版 PostgreSQL サーバーに設定する max_connections の値
ANKOLE_SITE_ADMIN_CONSOLE_PATH /site-admin-console Site Admin Console の URL パス
ANKOLE_FUNCTION_RUNTIME_IMAGE リリース既定値 Docker Compose で使用する ankole-function-runtime コンテナイメージ
ANKOLE_FUNCTION_RUNTIME_MAX_CONCURRENCY 32 ankole-function-runtime コンテナあたりの最大同時実行数
ANKOLE_LIBRARY_ROOT chart のデフォルト 同梱の Agent Library(app/library)へのパス
ANKOLE_INTERNAL_SKILLS_ROOT — 内部 Skill bundle へのパス
ANKOLE_AI_GATEWAY_BASE_URL — AIGateway のベース URL の上書き指定

ファイルストア(プロセス起動)

ANKOLE_FILES_STORE は control plane のオブジェクトストア(Ankole.ObjectStore)を構成します。ここには Unified Drive のイミュータブルなファイルオブジェクト(Pod スペース、メンバーのプライベートスペース、Agent ドライブ、会話ファイルを支える file_objects)、Pod・Applet アセット(ドキュメントや Base のアセット、コンパイル済み Applet バンドル、カスタム絵文字を含む pod_files)、Skill 同梱バイナリ(skill_files)、および凍結されたメッセージ・配信添付ファイルが保存されます。Worker にはストレージの認証情報を渡さず、ファイルデータの読み書きはすべて control plane を経由してストリーミングされます。対応するすべての OpenDAL backend の詳細については、control plane ドライブ・オブジェクトストレージの設定を参照してください。

変数 必須 意味
ANKOLE_FILES_STORE はい fs は control plane の永続ボリューム上のディレクトリ、s3 は Amazon S3 または Cloudflare R2 などの S3 互換ストア
ANKOLE_FILES_FS_ROOT fs ストアの絶対パス。Docker Compose では /var/lib/ankole/files にマウントされた files_data ボリュームを使用します
ANKOLE_FILES_S3_BUCKET s3 バケット名
ANKOLE_FILES_S3_REGION s3 リージョン。Cloudflare R2 の場合は auto
ANKOLE_FILES_S3_ENDPOINT いいえ S3 互換ストアのカスタムエンドポイント
ANKOLE_FILES_S3_ROOT いいえ バケット内のオブジェクトキー接頭辞(prefix)
ANKOLE_FILES_S3_ACCESS_KEY_ID、ANKOLE_FILES_S3_SECRET_ACCESS_KEY いいえ 固定の認証情報。省略時は EKS Pod Identity を含む既定の AWS 認証情報チェーンを使用します

fs ストアを使用できるのは、control plane が 1 レプリカの構成に限られます。複数レプリカで運用する場合は s3 などの共有リモートストレージを使用してください。

また、s3 への大容量ファイルの書き込みにはマルチパートアップロードが使用されます。アップロード途中に control plane が停止すると未完了のパートがバケット内に残るため、未完了のマルチパートアップロードを自動中止するライフサイクルルールをバケットに設定してください。

Worker Provider の初期設定

起動時に読み取られる以下の変数は、デプロイメントの識別名や起動対象の Worker イメージを指定します。個々の Worker provider は Console → Workers → Providers で YAML として設定し、認証情報は別途暗号化して保存されます。provider 作成後に種類・配置・永続ストレージ方式を変更することはできません。インスタンス設定の変更は、対象 Agent がアイドル状態になった時点で反映されます。

変数 意味
ANKOLE_AGENT_COMPUTER_IMAGE control plane のリリースに対応する Worker イメージ
ANKOLE_WORKER_RUNTIME_FABRIC_ENDPOINT 既定の RuntimeFabric WebSocket URL。プロバイダーに endpoints.runtimeFabricUrl の指定がない Worker がこの URL に接続します。プロバイダーが endpoints.relayOrigin を指定していない限り、Worker は接続先の RuntimeFabric URL と同じ HTTP オリジンの /api/v1/vfs/ を通じてドライブもマウントするため、そのオリジンからコントロールプレーンのすべてのレプリカに到達できる必要があります
ANKOLE_WORKER_INSTALLATION デプロイメント識別ラベル(既定値:ankole)
ANKOLE_WORKER_PROVIDERS_FILE 任意の provider 初期投入(seed)用 YAML。初回読み込みと既存 Agent への割り当てが同一トランザクションで実行されます

ローカル開発時(bun dev)のソースコードや内部 Skill のマウントは config/dev.exs で構成されており、本番リリースイメージには開発用マウントは含まれません。

Provider の Egress プロキシ

model provider への通信をアウトバウンドプロキシ経由にする必要がある場合は、control-plane プロセスに以下の標準プロキシ変数を設定します(https_proxy などの小文字表記も使用できます)。

変数 意味
HTTPS_PROXY HTTPS およびセキュア WebSocket(wss)の provider リクエスト用プロキシ
HTTP_PROXY HTTP および WebSocket(ws)の provider リクエスト用プロキシ。HTTPS_PROXY と ALL_PROXY がどちらも未設定の場合、セキュアなリクエストにも使用されます
ALL_PROXY プロトコル固有の変数が未設定の場合に使われるフォールバックプロキシ
NO_PROXY プロキシを経由せず直接接続するホスト名またはドメイン接尾辞のカンマ区切りリスト

プロキシ URL には http、https、socks5、socks5h スキームを指定でき、プロキシ認証が必要な場合は URL 内に認証情報を埋め込むことも可能です。判定時は常に NO_PROXY が最優先されます。セキュアなリクエストでは HTTPS_PROXY → ALL_PROXY → HTTP_PROXY の順に、平文のリクエストでは HTTP_PROXY → ALL_PROXY の順に参照されます。これらの変数を変更した後は control plane を再起動してください。

Worker 専用の環境(Agent Computer Worker)

以下の変数は Worker 作成時に control plane が自動設定するものであり、運用者が手動で設定することはありません。Worker は WORKER_ID から担当の Agent を識別します。なお、Session や Turn の情報は環境変数ではなく、各 turn_start メッセージで渡されます。

変数 意味
WORKER_ID 担当する Agent の UID。Worker はこの Agent 専用として動作します
ANKOLE_RUNTIME_FABRIC_ENDPOINT Worker の接続先となる ws:// または wss:// の RuntimeFabric URL
ANKOLE_RUNTIME_FABRIC_WORKER_AUTH_KEY generation ごとに発行されるランダム認証情報。control plane 側にはダイジェストと暗号化された再試行用の値が保存されます
ANKOLE_WORKER_STORAGE provider が指定するストレージ準備モード

Worker コンテナに追加の環境変数を渡したい場合は、provider YAML の env または Kubernetes の podTemplate で設定します。ANKOLE_MAX_CONCURRENT_SLOTS は Worker 内の環境ワークスペースと Codex turn の同時実行上限を制御します(既定値:12、通常の model turn は slot を消費しません)。これらの設定を変更すると、アイドル時に Worker が置き換えられます。

なお、ANKOLE_BROWSER_* や ANKOLE_BUILTIN_SKILLS_ROOT などのブラウザ・組み込み Skill 用パスは Worker イメージ側で固定されており、管理者が変更することはできません。

また、PATH、HOME、DATABASE_URL、および ANKOLE_ で始まる変数名は Agent 環境エディターでは予約済みのため指定できません。必要な場合は provider YAML の対応フィールドで設定してください。詳しくは環境変数を参照してください。

デプロイメント環境変数を変更する

起動時環境変数を変更する場合は、Docker Compose の .env または Helm の values を更新したうえで、対象プロセスを再起動します。Worker provider の設定変更は Console から行ってください(一度読み込まれた seed ファイルが既存のデータベース設定を上書きすることはありません)。Worker イメージやインスタンス設定を変更した場合は、各 Agent がアイドル状態になったタイミングで Worker が順次置き換えられます。

次のステップ

  • Agent が使用するカスタム環境変数については、環境変数を参照してください。
  • ランタイム設定と AppConfigure キーの一覧については、AppConfigureを参照してください。
  • デプロイメント全体での環境変数の位置づけについては、Quick start のデプロイメントセクションを参照してください。