eve-manifest-authoring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Eve Manifest Authoring

Eve 清单编写指南

Keep the manifest as the single source of truth for build and deploy behavior.

将清单作为构建和部署行为的唯一可信来源。

Minimal skeleton (v2)

最小骨架（v2版本）

yaml

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

yaml

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

Registry Image Labels

镜像仓库镜像标签

Some registries require package metadata for permission and ownership inheritance. Add these labels to your Dockerfiles when supported by your registry:

dockerfile

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

Why this matters: Metadata helps preserve repository ownership and improves traceability. The Eve builder injects these labels automatically, but including them in your Dockerfile is still recommended.

For multi-stage Dockerfiles, add the labels to the final stage (the production image).

部分镜像仓库需要包元数据来实现权限和所有权继承。当你的镜像仓库支持时，在Dockerfile中添加以下标签：

dockerfile

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

重要性说明：元数据有助于保留代码仓库所有权并提高可追溯性。Eve构建器会自动注入这些标签，但仍建议在Dockerfile中手动添加。

对于多阶段Dockerfile，请将标签添加到最终阶段（生产镜像阶段）。

Registry Modes

镜像仓库模式

yaml

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 }

For BYO/private registries, provide:

yaml

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

yaml

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 }

对于自定义/私有镜像仓库，请提供：

yaml

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

Managed Databases

托管数据库

Declare platform-provisioned databases with

x-eve.role: managed_db

yaml

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

Not deployed to K8s — provisioned by the orchestrator on first deploy. Reference managed values elsewhere:

${managed.db.url}

使用

x-eve.role: managed_db

声明由平台提供的数据库：

yaml

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

该服务不会部署到K8s中——会在首次部署时由编排器自动配置。在其他地方引用托管数据库的值：

${managed.db.url}

。

Eve-Migrate for Database Migrations

使用Eve-Migrate进行数据库迁移

Use the platform's migration runner instead of Flyway, TypeORM, or Knex. It uses plain SQL files with timestamp prefixes, tracked in

schema_migrations

yaml

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

Migration files:

db/migrations/20260312000000_initial_schema.sql

. The

x-eve.files

directive mounts them into the container at

/migrations

In the pipeline, the migrate step must run after deploy (managed DB needs provisioning):

yaml

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 }

For local dev, use the same image via Docker Compose for parity:

yaml

undefined

使用平台提供的迁移运行器替代Flyway、TypeORM或Knex。它使用带时间戳前缀的纯SQL文件，记录在

schema_migrations

表中：

yaml

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

目录下。

在流水线中，迁移步骤必须在部署完成后运行（托管数据库需要先完成配置）：

yaml

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保持一致性：

yaml

undefined

docker-compose.yml

services: migrate: image: public.ecr.aws/w7c4v0w3/eve-horizon/migrate:latest environment: DATABASE_URL: postgres://app:app@db:5432/myapp volumes: - ./db/migrations:/migrations:ro depends_on: db: { condition: service_healthy }

undefined

undefined

Legacy manifests

旧版清单

If the repo still uses

components:

from older manifests, migrate to

services:

and add

schema: eve/compose/v2

. Keep ports and env keys the same.

如果代码仓库仍使用旧版清单中的

components:

字段，请迁移到

services:

并添加

schema: eve/compose/v2

。保持端口和环境变量键不变。

Services

服务配置

Provide
```
image
```
and optionally
```
build
```
(context and dockerfile).
Use
```
ports
```
,
```
environment
```
,
```
healthcheck
```
,
```
depends_on
```
as needed.

Use

x-eve.external: true

and

x-eve.connection_url

for externally hosted services.

Use
```
x-eve.role: job
```
for one-off services (migrations, seeds). For database migrations, prefer Eve's
```
eve-migrate
```
image (see below).

提供
```
image
```
字段，可选提供
```
build
```
配置（上下文目录和dockerfile）。
根据需要使用
```
ports
```
、
```
environment
```
、
```
healthcheck
```
、
```
depends_on
```
字段。
对于外部托管的服务，使用
```
x-eve.external: true
```
和
```
x-eve.connection_url
```
字段。
对于一次性服务（如迁移、数据初始化），使用
```
x-eve.role: job
```
。对于数据库迁移，优先使用Eve的
```
eve-migrate
```
镜像（见上文）。

Build configuration

构建配置

Services with Docker images should define their build configuration:

yaml

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]

Note: Every deploy pipeline should include a

build

step before

release

. The build step creates tracked BuildSpec/BuildRun records and produces image digests that releases use for deterministic deployments.

带有Docker镜像的服务应定义其构建配置：

yaml

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记录，并生成镜像摘要，供发布步骤用于确定性部署。

Local dev alignment

本地开发对齐

Keep service names and ports aligned with Docker Compose.
Prefer
```
${secret.KEY}
```
and use
```
.eve/dev-secrets.yaml
```
for local values.

保持服务名称和端口与Docker Compose一致。
优先使用
```
${secret.KEY}
```
，并在
```
.eve/dev-secrets.yaml
```
中设置本地开发值。

Environments, pipelines, workflows

环境、流水线与工作流

Link each environment to a pipeline via
```
environments.<env>.pipeline
```
.
When
```
pipeline
```
is set,
```
eve env deploy <env>
```
triggers that pipeline instead of direct deploy.
Use
```
environments.<env>.pipeline_inputs
```
to provide default inputs for pipeline runs.

Override inputs at runtime with

eve env deploy <env> --ref <sha> --inputs '{"key":"value"}' --repo-dir ./my-app

Use

--direct

flag to bypass pipeline and do direct deploy:

eve env deploy <env> --ref <sha> --direct --repo-dir ./my-app

Pipeline steps can be
```
action
```
,
```
script
```
, or
```
agent
```
.
Use
```
action.type: create-pr
```
for PR automation when configured.
Workflows live under
```
workflows
```
and are invoked via CLI;
```
db_access
```
is honored.
Workflow steps support
```
harness
```
,
```
harness_profile
```
, and
```
harness_options
```
per step (overrides agent-resolved values),
```
condition
```
for skip-if-false gating against upstream step status, and
```
git
```
controls (now correctly materialized at dispatch). See
```
references/manifest.md
```
for the full step shape.
Workflow- and step-level
```
scope
```
blocks narrow the step job token and org filesystem mount. Supported axes:
```
orgfs
```
,
```
orgdocs
```
,
```
envdb
```
,
```
cloud_fs
```
. Step scope intersects workflow scope — invocation scope may narrow but not widen. Use it to grant a step exactly the paths/tables/mounts it needs, default-deny everything else.

yaml

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 }

Request-supplied

scope

(workflow invoke API body) requires

jobs:harness_override

. No

--scope-*

CLI flag yet.

通过
```
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
```
类型。
配置完成后，使用
```
action.type: create-pr
```
实现PR自动化。
工作流定义在
```
workflows
```
字段下，可通过CLI调用；
```
db_access
```
权限会被生效。
工作流步骤支持每个步骤设置
```
harness
```
、
```
harness_profile
```
和
```
harness_options
```
（覆盖代理解析的值），支持
```
condition
```
用于根据上游步骤状态判断是否跳过，还支持
```
git
```
控制（现在会在调度时正确实例化）。完整的步骤定义请参考
```
references/manifest.md
```
。
工作流和步骤级别的
```
scope
```
块可缩小步骤作业令牌和组织文件系统挂载范围。支持的维度包括：
```
orgfs
```
、
```
orgdocs
```
、
```
envdb
```
、
```
cloud_fs
```
。步骤范围与工作流范围相交——调用范围可以缩小但不能扩大。使用它为步骤授予恰好需要的路径/表/挂载权限，默认拒绝所有其他权限。

yaml

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标志。

Custom Domains and Stable Egress

自定义域名与稳定出口

Bring-your-own hostnames and opt-in network shape are declared per service:

yaml

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
```
are bound on first deploy: the first env to deploy with a hostname owns it; other envs that reference the same hostname log
```
owned by environment "<A>"
```
and skip rendering. Operate ownership with
```
eve domain list|verify|status|transfer|unbind|remove
```
(see
```
eve-deploy-debugging
```
).
```
networking.egress: stable
```
schedules the pod on the stable-egress node group with
```
hostNetwork: true
```
. It bypasses NAT and constrains scheduling — only opt in when needed.

See

references/manifest.md

for the full field shape (validation rules, max counts, per-env overrides).

每个服务可声明自定义主机名和可选的网络形态：

yaml

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
```
会将Pod调度到带有
```
hostNetwork: true
```
的稳定出口节点组。它会绕过NAT并限制调度——仅在必要时启用。

完整的字段定义（验证规则、最大数量、环境级覆盖）请参考

references/manifest.md

。

Project Branding And Auth

项目品牌与认证

App-facing login, invite emails, and magic-link emails are project-scoped and declared in

x-eve.branding

x-eve.auth

eve project sync

writes both onto the project record; the SSO broker and Eve API mailer read from there.

面向应用的登录、邀请邮件和魔法链接邮件是项目级别的，可在

x-eve.branding

x-eve.auth

中声明。

eve project sync

会将这些配置写入项目记录；SSO代理和Eve API邮件服务会读取这些配置。

x-eve.branding

— invite + magic-link email branding

x-eve.branding

— 邀请邮件与魔法链接邮件品牌配置

yaml

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: "support@example.com"
    support_email: "support@example.com"
    support_url: "https://example.com/help"

email_from_name

reply_to_email

support_email

set headers on app-scoped mail while keeping the platform's verified sender address. Phase 1 emits logo + name + primary color in invite and magic-link templates.

yaml

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: "support@example.com"
    support_email: "support@example.com"
    support_url: "https://example.com/help"

email_from_name

、

reply_to_email

、

support_email

会设置应用级邮件的头信息，同时保留平台的验证发件人地址。第一阶段会在邀请邮件和魔法链接模板中显示Logo、名称和主色调。

x-eve.auth.login_method: magic_link

— passwordless apps

x-eve.auth.login_method: magic_link

— 无密码应用

yaml

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

Opt in per project. With

magic_link

, the SSO login page hides password and signup, and Eve API sends branded magic-link mail via

POST /auth/magic-link

(not GoTrue direct), so unknown emails get generic success without creating a GoTrue user when

self_signup: false

. With

invite_requires_password: false

, invite acceptance establishes the session and skips

/set-password

. Use

password_or_magic_link

to keep password login plus a secondary branded magic-link control.

yaml

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会通过

POST /auth/magic-link

发送品牌化的魔法链接邮件（而非直接调用GoTrue），因此当

self_signup: false

时，未知邮箱会收到通用成功提示，不会创建GoTrue用户。设置

invite_requires_password: false

时，接受邀请会直接建立会话并跳过

/set-password

步骤。使用

password_or_magic_link

可同时保留密码登录和品牌化魔法链接登录选项。

x-eve.auth.org_access.domain_signup

— pre-approved email domains

x-eve.auth.org_access.domain_signup

— 预批准邮箱域名

yaml

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 shape (2026-05-12). Each

domains[]

entry is an object with its own required

target_org

; the legacy list-of-strings + block-level

target_org

is no longer accepted. Each

target_org

must already appear in

allowed_orgs

. Matching is first-rule-in-declaration-order; declare more-specific patterns first. Invalid with

login_method: password

. Free-email domains (

free-mail.example

outlook.com

, ...) emit a coherence warning — declaring them lets anyone on Earth join.

yaml

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

— custom-domain apps

x-eve.auth.allowed_redirect_origins

— 自定义域名应用

yaml

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

Origins only —

scheme://host[:port]

. Paths, queries, fragments, and userinfo are rejected at sync.

http://

permitted only for

localhost

, loopback IPs, and

*.lvh.me

. The SSO broker also auto-includes the project's eligible

custom_domains

rows and (in

allowlist

mode) custom domains owned by

allowed_orgs

siblings, so a project with a registered custom domain does not need to repeat it here. Confirm the resolved list with

eve project auth-context <project_id>

See

references/manifest.md

for full validation rules (email-domain grammar, IDN normalization, duplicate detection, redirect-origin normalization).

yaml

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

仅允许源地址格式——

scheme://host[:port]

。路径、查询参数、片段和用户信息会在同步时被拒绝。仅允许

localhost

、环回IP和

*.lvh.me

使用

http://

。SSO代理还会自动包含项目的合格

custom_domains

条目，以及（在

allowlist

模式下）

allowed_orgs

关联的自定义域名，因此已注册自定义域名的项目无需在此重复声明。使用

eve project auth-context <project_id>

确认最终的允许列表。

完整的验证规则（邮箱域名语法、IDN规范化、重复检测、重定向源规范化）请参考

references/manifest.md

。

Service Token Permissions

服务令牌权限

Every deployed service receives an auto-injected

EVE_SERVICE_TOKEN

with read-only defaults. Declare any write scopes you need explicitly — anything not declared is denied:

yaml

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

Declared permissions are merged with the read-only defaults; you only list what you add. Default to declaring nothing and grant write scopes one at a time as the service actually needs them. See

references/manifest.md

for the full permission catalog.

每个已部署的服务会自动注入一个

EVE_SERVICE_TOKEN

，默认仅拥有只读权限。请明确声明所需的任何写入权限——未声明的权限都会被拒绝：

yaml

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

声明的权限会与默认只读权限合并；你只需列出需要添加的权限。默认情况下无需声明任何权限，仅在服务实际需要时逐个授予写入权限。完整的权限列表请参考

references/manifest.md

。

Platform-Injected Environment Variables

平台注入的环境变量

Eve automatically injects these into all deployed service containers:

Variable	Description
`EVE_API_URL`	Internal cluster URL for server-to-server calls
`EVE_PUBLIC_API_URL`	Public ingress URL for browser-facing apps
`EVE_PROJECT_ID`	The project ID
`EVE_ORG_ID`	The organization ID
`EVE_ENV_NAME`	The environment name

Use

EVE_API_URL

for backend calls from your container. Use

EVE_PUBLIC_API_URL

for browser/client-side code. Services can override these in their

environment

section.

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

部分覆盖这些变量。

Interpolation and secrets

插值与密钥

Env interpolation:

${ENV_NAME}

${PROJECT_ID}

${ORG_ID}

${ORG_SLUG}

${COMPONENT_NAME}

Secret interpolation:
```
${secret.KEY}
```
pulls from Eve secrets or
```
.eve/dev-secrets.yaml
```
.
Managed DB interpolation:
```
${managed.<service>.<field>}
```
resolves at deploy time.
Use
```
.eve/dev-secrets.yaml
```
for local overrides; set real secrets via the API for production.

环境变量插值：

${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 extensions

Eve扩展

Top-level defaults via
```
x-eve.defaults
```
(env, harness, harness_profile, harness_options, hints, git, workspace).
Top-level agent policy via
```
x-eve.agents
```
(profiles, councils, availability rules).
Agent packs via
```
x-eve.packs
```
with optional
```
x-eve.install_agents
```
defaults.

Agent config paths via

x-eve.agents.config_path

and

x-eve.agents.teams_path

Chat routing config via
```
x-eve.chat.config_path
```
.
Service extensions under
```
x-eve
```
(ingress, role, api specs, worker pools, cli, object_store, networking, permissions).
API specs:
```
x-eve.api_spec
```
or
```
x-eve.api_specs
```
(spec URL relative to service by default).
App CLI:
```
x-eve.cli
```
declares an agent-friendly CLI for the service (see below).
Toolchains: agent-level
```
toolchains
```
declarations inject on-demand runtimes (see below).
Cloud FS mounts: configured via integrations, not the manifest (see
```
references/integrations.md
```
).
Per-org OAuth: each org registers its own OAuth app credentials via
```
eve integrations configure
```
(see
```
eve-auth-and-secrets
```
).

Example:

yaml

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

通过
```
x-eve.defaults
```
设置顶层默认值（环境、harness、harness_profile、harness_options、提示、git、工作区）。
通过
```
x-eve.agents
```
设置顶层代理策略（配置文件、委员会、可用性规则）。
通过
```
x-eve.packs
```
设置代理包，可选择设置
```
x-eve.install_agents
```
默认值。

通过

x-eve.agents.config_path

和

x-eve.agents.teams_path

设置代理配置路径。

通过
```
x-eve.chat.config_path
```
设置聊天路由配置。
服务级扩展在
```
x-eve
```
下定义（入口、角色、API规范、工作池、CLI、对象存储、网络、权限）。
API规范：
```
x-eve.api_spec
```
或
```
x-eve.api_specs
```
（默认相对于服务的规范URL）。
应用CLI：
```
x-eve.cli
```
声明面向代理的服务CLI（见下文）。
工具链：代理级别的
```
toolchains
```
声明会注入按需运行时（见下文）。
云文件系统挂载：通过集成系统配置，而非清单（参考
```
references/integrations.md
```
）。
按组织OAuth：每个组织通过
```
eve integrations configure
```
注册自己的OAuth应用凭证（参考
```
eve-auth-and-secrets
```
）。

示例：

yaml

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

App CLI Framework

应用CLI框架

Recommended for every app with an API. Wrap your service API in a CLI and register it here. Agents strongly prefer CLI commands over raw REST — CLIs handle auth, URL construction, and error formatting transparently. This is the Eve way: coding agents should build a CLI in the repo and register it in the manifest rather than having agents call APIs directly.

The platform auto-discovers services with

x-eve.cli

x-eve.api_spec

from the manifest and makes them available on

$PATH

for all agent jobs in the project — no explicit

with_apis

needed. Just declare the CLI here and all agents get it.

yaml

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)

For compiled CLIs, use an image-based distribution:

yaml

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

推荐所有带API的应用使用。将服务API包装为CLI并在此处注册。代理更倾向于使用CLI命令而非原始REST接口——CLI会透明处理认证、URL构造和错误格式化。这是Eve的最佳实践：编码代理应在代码仓库中构建CLI并在清单中注册，而非直接调用API。

平台会自动从清单中发现带有

x-eve.cli

或

x-eve.api_spec

的服务，并将其添加到项目中所有代理作业的

$PATH

中——无需显式设置

with_apis

。只需在此处声明CLI，所有代理即可使用。

yaml

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，使用基于镜像的分发方式：

yaml

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

How It Works

工作原理

Manifest sync stores CLI metadata alongside
```
api_spec
```
.
Job workspace setup (after clone) runs
```
chmod +x
```
and symlinks the binary to
```
/usr/local/bin/
```
.
For image-based CLIs, an init container copies the binary from the image.
The CLI reads
```
EVE_APP_API_URL_{SERVICE}
```
and
```
EVE_JOB_TOKEN
```
(already injected) -- no manual auth or URL configuration.

清单同步会将CLI元数据与
```
api_spec
```
一起存储。
作业工作区设置（克隆后）会执行
```
chmod +x
```
并将二进制文件链接到
```
/usr/local/bin/
```
。
对于基于镜像的CLI，初始化容器会从镜像中复制二进制文件。
CLI会读取已注入的
```
EVE_APP_API_URL_{SERVICE}
```
和
```
EVE_JOB_TOKEN
```
——无需手动配置认证或URL。

CLI naming rules

CLI命名规则

Lowercase alphanumeric with hyphens:
```
[a-z][a-z0-9-]*
```
Must be unique per project
The name becomes the command agents invoke (e.g.,
```
eden projects list
```
)

小写字母数字加连字符：
```
[a-z][a-z0-9-]*
```
每个项目内必须唯一
名称即为代理调用的命令（例如：
```
eden projects list
```
）

Worker Toolchain Declarations

工作者工具链声明

Agents declare which runtime toolchains they need. The platform injects them as init containers -- no fat worker image required.

yaml

undefined

代理会声明所需的运行时工具链。平台会将其作为初始化容器注入——无需使用臃肿的工作者镜像。

yaml

undefined

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


Available toolchains: `python`, `media`, `rust`, `java`, `kotlin`.

Workflows can override agent defaults:

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

Toolchains are mounted at

/opt/eve/toolchains/{name}/

with binaries on

$PATH

. The default worker image is

base

(~800MB); toolchains add only what each job needs.

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`。

工作流可覆盖代理默认配置：

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

工具链会挂载到

/opt/eve/toolchains/{name}/

，二进制文件会添加到

$PATH

。默认工作者镜像为

base

（约800MB）；工具链仅会添加每个作业所需的内容。

Cloud FS Mounts

云文件系统挂载

Google Drive folders can be mounted into the org filesystem via cloud FS integrations. Configuration is through the integrations system, not the manifest.

bash

undefined

可通过云文件系统集成将Google Drive文件夹挂载到组织文件系统。配置通过集成系统完成，而非清单。

bash

undefined

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"


Developers browse mounted content with `eve cloud-fs ls` and search it with `eve cloud-fs search`. The mount stores the provider folder ID plus an optional human-readable root-folder path hint; there is no separate CLI `--mount-path` setting.

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`设置。

App Object Store

应用对象存储

Declare app-scoped object storage buckets in the manifest. Each bucket is provisioned per environment during deploy, tracked in

eve env diagnose

, and credentials are injected as environment variables.

yaml

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

在清单中声明应用级对象存储桶。每个桶会在部署时按环境配置，可通过

eve env diagnose

追踪，凭证会作为环境变量注入。

yaml

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

Auto-Injected Storage Environment Variables

自动注入的存储环境变量

When object store buckets are provisioned, these env vars are injected into the service container:

Variable	Description
`STORAGE_ENDPOINT`	S3-compatible endpoint URL
`STORAGE_REGION`	Storage region
`STORAGE_ACCESS_KEY_ID`	App-facing access key
`STORAGE_SECRET_ACCESS_KEY`	App-facing secret key
`STORAGE_BUCKET_<NAME>`	Physical bucket name for each logical bucket
`STORAGE_FORCE_PATH_STYLE`	`true` for MinIO local dev, omitted for AWS S3

On AWS staging, apps currently share one app-bucket IAM principal scoped to

demo-eve-app-*

. It cannot access platform internal buckets or org filesystem buckets, but it does not isolate app buckets from each other. Per-app IRSA is the production follow-up.

当对象存储桶配置完成后，以下环境变量会注入到服务容器：

变量名	描述
`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。

Design Rules

设计规则

One bucket per concern. Separate
```
uploads
```
from
```
avatars
```
from
```
exports
```
.
Set visibility intentionally. Only buckets serving public assets should be
```
visibility: public
```
.
Use CORS for browser uploads. Set
```
cors.origins
```
and
```
cors.methods
```
when the frontend uploads directly via presigned URLs.
Bucket names must be unique within a service. The platform derives the physical bucket name from the project, environment, and logical name.

For detailed storage layer documentation, see the

eve-read-eve-docs

skill:

references/object-store-filesystem.md

按用途划分桶：将
```
uploads
```
、
```
avatars
```
、
```
exports
```
分开。
明确设置可见性：仅服务于公开资源的桶才设置为
```
visibility: public
```
。
浏览器上传需配置CORS：当前端通过预签名URL直接上传时，设置
```
cors.origins
```
和
```
cors.methods
```
。
桶名在服务内必须唯一：平台会根据项目、环境和逻辑名称生成物理桶名称。

详细的存储层文档请参考

eve-read-eve-docs

技能：

references/object-store-filesystem.md

。