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:
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).
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:
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.
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 or 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.
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:
Available toolchains: python, media, rust, java, kotlin.
Workflows can override agent defaults:
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.
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.
# 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.
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.
