eve-manifest-authoring

Eve マニフェストの作成

ビルドとデプロイの動作を決定する唯一の情報源として、マニフェストを使用してください。

最小構成のひな形（v2）

schema: eve/compose/v2
project: my-project

registry: "eve"  # Use managed registry by default for Eve apps
services:
  api:
    build:
      context: ./apps/api           # Build context directory
      dockerfile: Dockerfile        # Optional, defaults to context/Dockerfile
    # image omitted by default; when build is present, Eve derives image name from service key
    ports: [3000]
    environment:
      NODE_ENV: production
    x-eve:
      ingress:
        public: true
        port: 3000

environments:
  staging:
    pipeline: deploy
    pipeline_inputs:
      some_key: default_value

pipelines:
  deploy:
    steps:
      - name: build
        action:
          type: build               # Builds all services with build: config
      - name: release
        depends_on: [build]
        action:
          type: release
      - name: deploy
        depends_on: [release]
        action:
          type: deploy

レジストリのイメージラベル

一部のレジストリでは、権限と所有権の継承にパッケージのメタデータが必要です。 レジストリでサポートされている場合は、これらのラベルを Dockerfile に追加してください。

LABEL org.opencontainers.image.source="https://github.com/YOUR_ORG/YOUR_REPO"
LABEL org.opencontainers.image.description="Service description"

重要な理由：メタデータは、リポジトリの所有権を維持し、トレーサビリティを向上させるのに役立ちます。Eve ビルダーはこれらのラベルを自動的に挿入しますが、Dockerfile に含めることも引き続き推奨されます。

マルチステージ Dockerfile の場合は、ラベルを最終ステージ（本番イメージ）に追加してください。

レジストリモード

registry: "eve"     # Eve-native registry (internal JWT auth)
registry: "none"    # Disable registry handling (public images)
registry:           # BYO registry (full object — see section below)
  host: public.ecr.aws/w7c4v0w3
  namespace: myorg
  auth: { username_secret: REGISTRY_USERNAME, token_secret: REGISTRY_PASSWORD }

BYO／プライベートレジストリの場合は、以下を指定してください。

registry:
  host: public.ecr.aws/w7c4v0w3
  namespace: myorg
  auth:
    username_secret: REGISTRY_USERNAME
    token_secret: REGISTRY_PASSWORD

マネージドデータベース

x-eve.role: managed_db を指定して、プラットフォームがプロビジョニングするデータベースを宣言します。

services:
  db:
    x-eve:
      role: managed_db
      managed:
        class: db.p1
        engine: postgres
        engine_version: "16"

K8s にはデプロイされず、初回のデプロイ時にオーケストレーターによってプロビジョニングされます。 他の場所では、${managed.db.url} を使ってマネージド値を参照してください。

データベースのマイグレーションに Eve-Migrate を使用する

Flyway、TypeORM、Knex の代わりに、プラットフォームのマイグレーションランナーを使用してください。タイムスタンプの接頭辞を付けたプレーンな SQL ファイルを使用し、schema_migrations で追跡します。

services:
  migrate:
    image: public.ecr.aws/w7c4v0w3/eve-horizon/migrate:latest
    environment:
      DATABASE_URL: ${managed.db.url}
      MIGRATIONS_DIR: /migrations
    x-eve:
      role: job
      files:
        - source: db/migrations
          target: /migrations

マイグレーションファイルの例：db/migrations/20260312000000_initial_schema.sql。x-eve.files ディレクティブにより、ファイルはコンテナ内の /migrations にマウントされます。

パイプラインでは、マイグレーションステップをデプロイ後に実行する必要があります（マネージドデータベースのプロビジョニングが必要です）。

pipelines:
  deploy:
    steps:
      - name: build
        action: { type: build }
      - name: release
        depends_on: [build]
        action: { type: release }
      - name: deploy
        depends_on: [release]
        action: { type: deploy }
      - name: migrate
        depends_on: [deploy]
        action: { type: job, service: migrate }

ローカル開発では、環境の一貫性を保つため、Docker Compose で同じイメージを使用してください。

# docker-compose.yml
services:
  migrate:
    image: ghcr.io/eve-horizon/eve-migrate:latest
    environment:
      DATABASE_URL: postgres://app:app@db:5432/myapp
    volumes:
      - ./db/migrations:/migrations:ro
    depends_on:
      db: { condition: service_healthy }

レガシーマニフェスト

リポジトリで以前のマニフェストの components: がまだ使用されている場合は、services: に移行し、 schema: eve/compose/v2 を追加してください。ポートと環境変数のキーはそのままにしてください。

サービス

• image を指定し、必要に応じて build（コンテキストと Dockerfile）を指定します。
• 必要に応じて ports、environment、healthcheck、depends_on を使用します。
• 外部でホストされるサービスには x-eve.external: true と x-eve.connection_url を使用します。
• 一度だけ実行するサービス（マイグレーション、シード）には x-eve.role: job を使用します。データベースのマイグレーションには、Eve の eve-migrate イメージを優先してください（下記参照）。

ビルド設定

Docker イメージを使用するサービスでは、ビルド設定を定義してください。

services:
  api:
    build:
      context: ./apps/api           # Build context directory
      dockerfile: Dockerfile        # Optional, defaults to context/Dockerfile
    # image: api      # optional if using build; managed registry derives this
    ports: [3000]

注：すべてのデプロイパイプラインには、release の前に build ステップを含めてください。ビルドステップは追跡対象の BuildSpec／BuildRun レコードを作成し、リリースが決定論的なデプロイに使用するイメージダイジェストを生成します。

ローカル開発との整合性

• サービス名とポートを Docker Compose に合わせてください。
• ${secret.KEY} を優先して使用し、ローカルの値には .eve/dev-secrets.yaml を使用してください。

環境、パイプライン、ワークフロー

• 各環境を environments.<env>.pipeline でパイプラインにリンクします。
• pipeline が設定されている場合、eve env deploy <env> は直接デプロイする代わりに、そのパイプラインを実行します。
• environments.<env>.pipeline_inputs を使用して、パイプライン実行時のデフォルト入力を指定します。
• 実行時に入力を上書きするには、eve env deploy <env> --ref <sha> --inputs '{"key":"value"}' --repo-dir ./my-app を使用します。
• --direct フラグを使用すると、パイプラインを介さずに直接デプロイできます：eve env deploy <env> --ref <sha> --direct --repo-dir ./my-app。
• パイプラインのステップには、action、script、または agent を指定できます。
• 設定済みの場合、PR の自動化には action.type: create-pr を使用します。
• ワークフローは workflows の下に定義し、CLI から実行します。db_access が適用されます。
• ワークフローのステップでは、ステップごとに harness、harness_profile、harness_options（エージェントによって解決された値を上書き）、condition（上流ステップのステータスに基づく、false の場合にスキップするゲート）、および git の制御（ディスパッチ時に正しく適用されるようになりました）をサポートします。ステップの完全な形式については、references/manifest.md を参照してください。
• ワークフローおよびステップレベルの scope ブロックを使用すると、ステップのジョブトークンと組織のファイルシステムマウントの範囲を絞り込めます。サポートされる軸：orgfs、orgdocs、envdb、cloud_fs。ステップのスコープはワークフローのスコープと交差します。呼び出しスコープで範囲を狭めることはできますが、広げることはできません。ステップに必要なパス、テーブル、マウントだけを許可し、それ以外はデフォルトで拒否するために使用します。

workflows:
  create-design:
    scope:
      orgfs: { allow_prefixes: [/groups/projects/proj-a/**] }
    steps:
      - name: publish
        scope:
          cloud_fs: { allow_mount_ids: [mount_a] }
        agent: { name: publisher }

リクエストで指定する scope（ワークフロー呼び出し API の本文）には jobs:harness_override が必要です。--scope-* CLI フラグはまだありません。

カスタムドメインと安定したエグレス

独自ホスト名とオプトインのネットワーク構成は、サービスごとに宣言します。

services:
  api:
    x-eve:
      ingress:
        public: true
        port: 3000
        domains: ["app.example.com", "www.example.com"]    # max 10
      networking:
        egress: stable    # default 'nat'; opt in only when a vendor needs allowlisted source IPs

• ingress.domains は初回デプロイ時に割り当てられます。ホスト名を指定して最初にデプロイした 最初の環境 がその所有者となり、同じホスト名を参照する他の環境では owned by environment "<A>" がログに記録され、レンダリングがスキップされます。所有権は eve domain list|verify|status|transfer|unbind|remove で操作します（eve-deploy-debugging を参照）。
• networking.egress: stable を設定すると、ポッドは hostNetwork: true を使用して安定エグレスのノードグループにスケジュールされます。NAT を迂回し、スケジューリングが制限されるため、必要な場合にのみオプトインしてください。

フィールドの完全な形式（検証ルール、最大数、環境ごとの上書き）については、references/manifest.md を参照してください。

プロジェクトのブランディングと認証

アプリ向けのログイン、招待メール、マジックリンクメールはプロジェクト単位で設定し、x-eve.branding / x-eve.auth で宣言します。eve project sync は両方をプロジェクトレコードに書き込み、SSO ブローカーと Eve API メーラーはそこから読み取ります。

x-eve.branding — 招待メールとマジックリンクメールのブランディング

x-eve:
  branding:
    app_name: "ACME Portal"                                    # required, <=60 chars
    app_logo_url: "https://app.example.com/logo.svg"          # https only on emitted mail
    primary_color: "#1f6feb"                                  # six-digit hex
    email_from_name: "ACME Portal"                              # From-name header
    reply_to_email: "[email protected]"
    support_email: "[email protected]"
    support_url: "https://example.com/help"

email_from_name、reply_to_email、support_email は、プラットフォームの検証済み送信者アドレスを維持しながら、アプリ単位のメールにヘッダーを設定します。フェーズ 1 では、招待テンプレートとマジックリンクテンプレートにロゴ、名前、プライマリカラーが表示されます。

x-eve.auth.login_method: magic_link — パスワードレスアプリ

x-eve:
  auth:
    login_method: magic_link            # password_or_magic_link | password | magic_link
    self_signup: false
    invite_requires_password: false

プロジェクトごとにオプトインします。magic_link を設定すると、SSO ログインページでパスワードとサインアップが非表示になり、Eve API は GoTrue への直接アクセスではなく、POST /auth/magic-link 経由でブランディング済みのマジックリンクメールを送信します。そのため、self_signup: false の場合、未知のメールアドレスには一般的な成功応答が返され、GoTrue ユーザーは作成されません。invite_requires_password: false を設定すると、招待の承認時にセッションが確立され、/set-password がスキップされます。パスワードログインを維持しつつ、2 つ目のブランディング済みマジックリンク操作を追加するには、password_or_magic_link を使用します。

x-eve.auth.org_access.domain_signup — 事前承認済みメールドメイン

x-eve:
  auth:
    org_access:
      mode: allowlist
      allowed_orgs: [org_acme, org_partner]
      domain_signup:
        enabled: true
        domains:
          - { domain: acme.com,   target_org: org_acme,  role: member }
          - { domain: partner.example,  target_org: org_partner }
          - { domain: "*.acme.com", target_org: org_acme }  # wildcard; apex needs its own rule

v2 の形式（2026-05-12）です。各 domains[] エントリは、独自の必須 target_org を持つオブジェクトです。従来の文字列リストとブロックレベルの target_org の組み合わせは、現在は受け付けられません。各 target_org は、allowed_orgs にすでに含まれている必要があります。一致判定は宣言順で最初に一致したルールが適用されるため、より具体的なパターンを先に宣言してください。login_method: password との併用は無効です。フリーメールのドメイン（free-mail.example、outlook.com、...）を指定すると整合性に関する警告が出ます。これらを宣言すると、世界中の誰でも参加できるようになります。

x-eve.auth.allowed_redirect_origins — カスタムドメインのアプリ

x-eve:
  auth:
    allowed_redirect_origins:
      - https://app.example.com
      - https://www.example.com

オリジンのみを指定します — scheme://host[:port]。パス、クエリ、フラグメント、ユーザー情報は同期時に拒否されます。http:// が許可されるのは、localhost、ループバック IP、*.lvh.me のみです。SSO ブローカーは、プロジェクトの対象となる custom_domains 行と（allowlist モードでは）allowed_orgs の兄弟組織が所有するカスタムドメインも自動的に含めるため、カスタムドメインが登録されているプロジェクトでは、ここに重複して指定する必要はありません。解決済みのリストは eve project auth-context <project_id> で確認してください。

検証ルール（メールドメインの文法、IDN の正規化、重複検出、リダイレクトオリジンの正規化）の詳細は references/manifest.md を参照してください。

サービストークンの権限

デプロイされた各サービスには、読み取り専用のデフォルト権限を持つ EVE_SERVICE_TOKEN が自動的に注入されます。必要な書き込みスコープは明示的に宣言してください。宣言されていないものはすべて拒否されます。

services:
  api:
    x-eve:
      permissions: [jobs:write, events:write, threads:write]

宣言した権限は読み取り専用のデフォルト権限と統合されます。追加する権限のみを列挙してください。何も宣言しない状態をデフォルトとし、サービスで実際に必要になったときに書き込みスコープを1つずつ付与してください。権限の一覧は references/manifest.md を参照してください。

プラットフォームが注入する環境変数

Eve は、デプロイされたすべてのサービスコンテナーに次の変数を自動的に注入します。

変数	説明
EVE_API_URL	サーバー間通信用の内部クラスター URL
EVE_PUBLIC_API_URL	ブラウザー向けアプリ用のパブリックイングレス URL
EVE_PROJECT_ID	プロジェクト ID
EVE_ORG_ID	組織 ID
EVE_ENV_NAME	環境名

コンテナーからのバックエンド呼び出しには EVE_API_URL を使用してください。ブラウザー／クライアント側のコードには EVE_PUBLIC_API_URL を使用してください。サービスの environment セクションでこれらの値を上書きできます。

補間とシークレット

• 環境変数の補間：${ENV_NAME}、${PROJECT_ID}、${ORG_ID}、${ORG_SLUG}、${COMPONENT_NAME}。
• シークレットの補間：${secret.KEY} は Eve のシークレットまたは .eve/dev-secrets.yaml から値を取得します。
• マネージドデータベースの補間：${managed.<service>.<field>} はデプロイ時に解決されます。
• ローカルでの上書きには .eve/dev-secrets.yaml を使用し、本番環境用のシークレットは API 経由で設定してください。

Eve の拡張機能

• トップレベルのデフォルト設定は x-eve.defaults で指定します（env、harness、harness_profile、harness_options、hints、git、workspace）。
• トップレベルのエージェントポリシーは x-eve.agents で指定します（profiles、councils、availability rules）。
• エージェントパックは x-eve.packs で指定し、オプションで x-eve.install_agents のデフォルト設定を指定できます。
• エージェント設定のパスは x-eve.agents.config_path と x-eve.agents.teams_path で指定します。
• チャットのルーティング設定のパスは x-eve.chat.config_path で指定します。
• サービスの拡張機能は x-eve の下に指定します（ingress、role、api specs、worker pools、cli、object_store、networking、permissions）。
• API 仕様は x-eve.api_spec または x-eve.api_specs で指定します（デフォルトでは、仕様の URL はサービスからの相対パスです）。
• アプリ CLI：x-eve.cli で、サービス用のエージェント向け CLI を宣言します（下記を参照）。
• ツールチェーン：エージェントレベルの toolchains 宣言により、オンデマンドのランタイムを注入します（下記を参照）。
• クラウド FS のマウント：マニフェストではなく、インテグレーションで設定します（references/integrations.md を参照）。
• 組織ごとの OAuth：各組織は eve integrations configure で独自の OAuth アプリ認証情報を登録します（eve-auth-and-secrets を参照）。

例：

x-eve:
  agents:
    version: 1
    config_path: agents/agents.yaml
    teams_path: agents/teams.yaml
  chat:
    config_path: agents/chat.yaml
  install_agents: [claude-code, codex]
  packs:
    - source: ./skillpacks/my-pack

アプリ CLI フレームワーク

API を持つすべてのアプリでの使用を推奨します。 サービスの API を CLI でラップし、ここに登録してください。エージェントは生の REST よりも CLI コマンドを優先します。CLI が認証、URL の構築、エラーの整形を透過的に処理するためです。これが Eve の推奨する方法です。コーディングエージェントが API を直接呼び出すのではなく、リポジトリに CLI を作成してマニフェストに登録するようにしてください。

プラットフォームは、マニフェストから x-eve.cli または x-eve.api_spec があるサービスを自動検出し、プロジェクト内のすべてのエージェントジョブで $PATH から利用できるようにします。明示的に with_apis を指定する必要はありません。ここで CLI を宣言するだけで、すべてのエージェントが利用できるようになります。

services:
  api:
    x-eve:
      api_spec:
        type: openapi
      cli:
        name: myapp              # Binary name (goes on $PATH)
        bin: cli/bin/myapp       # Path relative to repo root (pre-bundled)

コンパイル済みの CLI には、イメージベースの配布を使用してください。

services:
  api:
    x-eve:
      cli:
        name: myapp
        image: ghcr.io/org/myapp-cli:latest    # Pre-built image

仕組み

1. マニフェストの同期により、CLI メタデータが api_spec とともに保存されます。
2. ジョブのワークスペース設定（クローン後）で chmod +x を実行し、バイナリを /usr/local/bin/ にシンボリックリンクします。
3. イメージベースの CLI の場合、init コンテナがイメージからバイナリをコピーします。
4. CLI は EVE_APP_API_URL_{SERVICE} と EVE_JOB_TOKEN（すでに注入済み）を読み取るため、手動での認証や URL の設定は不要です。

CLI の命名規則

• 小文字の英数字とハイフンを使用します：[a-z][a-z0-9-]*
• プロジェクト内で一意である必要があります
• 名前はエージェントが実行するコマンドになります（例：eden projects list）

ワーカーツールチェーンの宣言

エージェントは必要なランタイムツールチェーンを宣言します。プラットフォームはそれらを init コンテナとして注入するため、肥大化したワーカーイメージは不要です。

# In agents.yaml
agents:
  data-analyst:
    name: Data Analyst
    skill: analyze-data
    harness_profile: claude-sonnet
    toolchains: [python]           # Needs python + uv

  doc-processor:
    name: Document Processor
    skill: process-documents
    harness_profile: claude-sonnet
    toolchains: [media]            # Needs ffmpeg + whisper

利用可能なツールチェーン：python、media、rust、java、kotlin。

ワークフローではエージェントのデフォルト設定を上書きできます。

workflows:
  process-document:
    steps:
      - name: process
        agent: doc-processor
        toolchains: [media, python]  # Override: needs both

ツールチェーンは /opt/eve/toolchains/{name}/ にマウントされ、バイナリは $PATH 上に配置されます。デフォルトのワーカーイメージは base（約800MB）で、ツールチェーンは各ジョブに必要なものだけを追加します。

クラウド FS マウント

Google Drive フォルダーは、クラウド FS インテグレーションを通じて組織のファイルシステムにマウントできます。設定はマニフェストではなく、インテグレーションシステムで行います。

# Org admin registers Google Drive OAuth app credentials (BYOA)
eve integrations configure google-drive \
  --client-id "xxx.apps.googleusercontent.com" \
  --client-secret "GOCSPX-xxx"

# Connect and mount a Drive folder
eve integrations connect google-drive
eve cloud-fs mount --org org_xxx \
  --provider google-drive \
  --folder-id <drive-folder-id> \
  --label "Shared Drive"

開発者は eve cloud-fs ls でマウントされたコンテンツを閲覧し、eve cloud-fs search で検索できます。マウントにはプロバイダーのフォルダー ID と、任意の人間が読めるルートフォルダーのパスヒントが保存されます。CLI に個別の --mount-path 設定はありません。

アプリのオブジェクトストア

マニフェストでアプリスコープのオブジェクトストレージバケットを宣言します。各バケットはデプロイ時に環境ごとにプロビジョニングされ、eve env diagnose で追跡されます。認証情報は環境変数として注入されます。

services:
  api:
    x-eve:
      object_store:
        buckets:
          - name: uploads
            visibility: private
          - name: avatars
            visibility: public
            cors:
              origins: ["*"]
              methods: [GET, PUT, HEAD]
              max_age_seconds: 3600

自動注入されるストレージ環境変数

オブジェクトストアのバケットがプロビジョニングされると、以下の環境変数がサービスコンテナに注入されます。

変数	説明
STORAGE_ENDPOINT	S3 互換のエンドポイント URL
STORAGE_REGION	ストレージのリージョン
STORAGE_ACCESS_KEY_ID	アプリ向けアクセスキー
STORAGE_SECRET_ACCESS_KEY	アプリ向けシークレットキー
STORAGE_BUCKET_<NAME>	各論理バケットの物理バケット名
STORAGE_FORCE_PATH_STYLE	MinIO のローカル開発では true。AWS S3 では省略

AWS ステージング環境では、現在、アプリは demo-eve-app-* にスコープされた単一のアプリバケット用 IAM プリンシパルを共有しています。このプリンシパルからプラットフォーム内部のバケットや組織ファイルシステムのバケットにはアクセスできませんが、アプリのバケット同士は分離されません。今後、本番環境ではアプリごとの IRSA を導入する予定です。

設計ルール

• 用途ごとにバケットを1つ用意します。 uploads、avatars、exports は別々にします。
• 公開範囲を意図的に設定します。 公開アセットを提供するバケットに限り、visibility: public を設定します。
• ブラウザーからのアップロードには CORS を使用します。 フロントエンドから署名付き URL を使って直接アップロードする場合は、cors.origins と cors.methods を設定します。
• バケット名はサービス内で一意である必要があります。 プラットフォームはプロジェクト、環境、論理名から物理バケット名を生成します。

ストレージレイヤーの詳細なドキュメントについては、eve-read-eve-docs スキルの references/object-store-filesystem.md を参照してください。