Eve Manifest Authoring

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

Minimal skeleton (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

Registry Image Labels

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

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).

Registry Modes

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:

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:

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}.

Eve-Migrate for Database Migrations

Use the platform's migration runner instead of Flyway, TypeORM, or Knex. It uses plain SQL files with timestamp prefixes, tracked in 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

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):

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:

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

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.

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).

Build configuration

Services with Docker images should define their build configuration:

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.

Local dev alignment

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

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.

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.

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.

Eve extensions

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).
API specs: x-eve.api_spec or x-eve.api_specs (spec URL relative to service by default).

Example:

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 Object Store

Status: Schema exists, provisioning logic pending. The database schema (storage_buckets table) and bucket naming convention are implemented. Automatic provisioning from the manifest is not yet wired.

Declare app-scoped object storage buckets in the manifest. Each bucket is provisioned per environment with credentials injected as environment variables.

services:
  api:
    x-eve:
      object_store:
        buckets:
          - name: uploads
            visibility: private
          - name: avatars
            visibility: public
            cors:
              allowed_origins: ["*"]

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_ACCESS_KEY`	Access key for the bucket
`STORAGE_SECRET_KEY`	Secret key for the bucket
`STORAGE_BUCKET`	Physical bucket name
`STORAGE_FORCE_PATH_STYLE`	`true` for MinIO (local dev), `false` for cloud

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.allowed_origins 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.

eve-manifest-authoring