• Designing a new application from scratch on Eve
• Migrating an existing app onto the platform
• Evaluating whether your current architecture uses Eve's capabilities well
• Planning service topology, database strategy, or deployment pipelines
• Deciding between managed and external services

eve-manifest-authoring

eve-deploy-debugging

eve-auth-and-secrets

eve-pipelines-workflows

1. One concern per service. Separate HTTP serving from background processing. An API service should not also run scheduled jobs.
2. Use managed DB for Postgres. Declare

   x-eve.role: managed_db

   and let the platform provision, connect, and inject credentials. No manual connection strings.
3. Mark external services explicitly. Use

   x-eve.external: true

   with

   x-eve.connection_url

   for services hosted outside Eve (Redis, third-party APIs).
4. Use

   x-eve.role: job

   for one-off tasks. Migrations, seeds, and data backfills are job services, not persistent processes.
5. Expose ingress intentionally. Only services that need external HTTP access get

   x-eve.ingress.public: true

   . Internal services communicate via cluster networking.
6. Choose a hostname strategy early. Every public service gets a generated platform URL by default. Layer on

   x-eve.ingress.alias

   for a friendlier platform-subdomain (

   ingest.eve.example.com

   ), or

   x-eve.ingress.domains: [limelee.com]

   to bring your own domain. Custom domains are env-scoped and first-bind-wins — design which environment owns the apex (usually

   production

   ) before declaring it. See

   eve-manifest-authoring

   and

   eve-deploy-debugging

   for declaration and DNS verification flow.

services:
  api:
    x-eve:
      object_store:
        buckets:
          - name: uploads
            visibility: private
          - name: avatars
            visibility: public

Note: The database schema for app object stores exists, but automatic provisioning from the manifest is not yet wired. See

references/object-store-filesystem.md

for current status.

STORAGE_ENDPOINT

STORAGE_ACCESS_KEY

STORAGE_SECRET_KEY

STORAGE_BUCKET

STORAGE_FORCE_PATH_STYLE

build → release → deploy → migrate → smoke-test

pipelines:
  deploy:
    steps:
      - name: build
        action:
          type: build          # Creates BuildSpec + BuildRun, produces image digests
      - name: release
        depends_on: [build]
        action:
          type: release        # Creates immutable release from build artifacts
      - name: deploy
        depends_on: [release]
        action:
          type: deploy         # Deploys release to target environment
      - name: migrate
        depends_on: [deploy]
        action:
          type: job
          service: migrate     # Runs eve-migrate against the managed DB
      - name: smoke-test
        depends_on: [migrate]
        script:
          run: ./scripts/smoke-test.sh
          timeout: 300

• build

  produces SHA256 image digests.

  release

  pins those exact digests.

  deploy

  uses the pinned release. You deploy exactly what you built — no tag drift, no "latest" surprises.

• migrate

  runs after deploy because the managed DB must be provisioned first. The eve-migrate job applies any pending SQL migrations.

• smoke-test

  validates the deployed services end-to-end before the pipeline reports success.

1. Diagnose:

   eve env diagnose <project> <env>

   — shows health, recent deploys, service status.
2. Logs:

   eve env logs <project> <env>

   — container output.
3. Rollback: Redeploy the previous known-good release.
4. Reset:

   eve env reset <project> <env>

   — nuclear option, reprovisions from scratch.

1. Build the CLI early. Don't wait until the API is "done." Start the CLI alongside the first API endpoints. Agents will use it immediately.
2. Mirror the API surface. Every REST endpoint should have a CLI subcommand.

   GET /items

   →

   myapp items list

   ,

   POST /items

   →

   myapp items create --file data.json

   .
3. Support

   --json

   everywhere. Default output is human-readable tables;

   --json

   gives machine-readable output for agent pipelines.
4. Bundle as a single file. Use esbuild to produce a self-contained Node.js script committed to the repo. Zero startup latency.
5. Point agent skills at the CLI. Skill instructions should say "Use

   myapp items list

   ", never "curl the API at..."

myapp:{project_id}:{conversation_id}

@eve-horizon/chat

@eve-horizon/chat-react

• Map your product objects (a document, a project, a ticket) to Eve threads by stable key. The platform owns thread state; your app owns product projections that reference

  thread_id

  .
• Route through

  chat.yaml

  , an agent, a team, or a workflow using the same primitives external gateways use. Chat is just another dispatch target.
• Phase 1 push uses SSE with snapshot + polling catch-up; design your UI to tolerate brief reconnects rather than assuming a persistent socket.

references/eve-sdk.md

eve-read-eve-docs

1. Set secrets per-project. Use

   eve secrets set KEY "value" --project proj_xxx

   . Keep project secrets self-contained.
2. Use interpolation in the manifest. Reference

   ${secret.KEY}

   in service environment blocks. The platform resolves at deploy time.
3. Validate before deploying. Run

   eve manifest validate --validate-secrets

   to catch missing secret references before they cause deploy failures.
4. Use

   .eve/dev-secrets.yaml

   for local development. Mirror the production secret keys with local values. This file is gitignored.
5. Never store secrets in environment variables directly. Always use

   ${secret.KEY}

   interpolation. This ensures secrets flow through the platform's resolution and audit chain.

1. EveAuthProvider

   checks

   sessionStorage

   for cached token
2. If no token, probes SSO broker

   /session

   (root-domain cookie)
3. If SSO session exists, gets fresh Eve RS256 token
4. If no session, shows login form (SSO redirect or token paste)
5. All API requests include

   Authorization: Bearer <token>

x-eve:
  auth:
    login_method: magic_link            # or password_or_magic_link, password
    self_signup: false                  # unknown emails return generic success, no email
    invite_requires_password: false     # invite acceptance skips /set-password

• Users are created through invites, not self-signup. Plan your admin invite UX accordingly.
• The magic-link email reuses the same

  x-eve.branding

  block as invite emails — one branding source, two email copies.
• Eve API handles eligibility (existing user, pending invite, domain signup) before any email is sent, so account-enumeration defense is preserved without app-side work.

x-eve:
  auth:
    org_access:
      mode: allowlist
      allowed_orgs: [org_customer123, customer-slug]
      invite:
        enabled: true
        admin_roles: [admin, owner]
        invited_role: member          # fixed; app invites cannot create admins

• Backends should use

  eveAppUserAuth()

  (not

  eveUserAuth()

  ) so authorization is bound to the app policy, not the project owner org. The middleware consults

  GET /auth/app-access

  and selects an org from

  X-Eve-Org-Id

  ,

  ?eve_org_id=

  , or the first allowed org.
• Build admin pages around

  POST /auth/app-invites

  (sends branded magic-link onboarding) instead of generic org-invite APIs. The platform enforces org role + app allowlist policy before sending.
• The React SDK exposes

  useEveAppAccess()

  for orgs/admin-org listings and inviting members.

@yourcompany.com

org_yourcompany

x-eve:
  auth:
    org_access:
      mode: allowlist
      allowed_orgs: [org_acme, org_globex]
      domain_signup:
        enabled: true
        domains:
          - { domain: acme.com,   target_org: org_acme,   role: member }
          - { domain: globex.com, target_org: org_globex }

• Rules are walked in declaration order — first match wins. Declare more-specific patterns first.
• The trust model is "operator declares, platform trusts" — no DNS proof in v1. Declaring

  free-mail.example

  produces a coherence warning but is permitted.
• Explicit pending invites (Path B) always win over domain signup (Path C); existing users with allowed-org membership (Path A) get the standard branded send.
• Removing a rule stops new signups but does not retroactively remove existing memberships — plan offboarding as an explicit

  eve org members remove

  .
• Audit via

  auth.domain_signup.invite_created

  and

  auth.domain_signup.member_attached

  events.

1. Use the SDK, not custom auth. The SDK replaces ~750 lines of hand-rolled auth with ~50 lines.
2. Non-blocking middleware first. Use

   eveUserAuth()

   globally, then

   eveAuthGuard()

   on protected routes. This enables mixed public/private routes.
3. The

   /auth/config

   endpoint is the handshake. The frontend discovers the SSO URL by calling the backend's

   eveAuthConfig()

   endpoint. This decouples the frontend from platform env vars and works identically in local dev and deployed environments.
4. Design for token staleness. The

   orgs

   JWT claim reflects membership at mint time (1-day TTL). Use

   strategy: 'remote'

   for immediate revocation if needed.

references/auth-sdk.md

eve-read-eve-docs

• Each service has one responsibility
• Managed DB declared for Postgres needs
• External services marked with

  x-eve.external: true

• Only public-facing services have ingress enabled
• Platform-injected env vars used (not hardcoded URLs)
• Hostname strategy chosen (generated URL, alias, or custom domain via

  x-eve.ingress.domains

  )
• Stable egress opted in only for services that integrate with source-IP-allowlisted vendors

• Migrations are plain SQL files in

  db/migrations/

  with timestamp prefixes

• eve-migrate

  job service declared in manifest with

  x-eve.files

  mount

• DatabaseService

  wraps all DB access with RLS context (

  set_config

  )
• RLS policies on every table with

  org_id

• pgcrypto

  extension enabled, UUID primary keys,

  updated_at

  triggers
• App data separated from agent data by schema or convention

• Canonical

  build → release → deploy → migrate → smoke-test

  pipeline defined
• Migrate step runs after deploy (managed DB must exist first)
• Smoke test script validates deployed services end-to-end
• Registry chosen and credentials set as secrets
• OCI labels on Dockerfiles (for GHCR)
• Image digests flow through release (no tag-based deploys)

• Staging and production environments defined
• Each environment linked to a pipeline
• Promotion workflow defined (build once, deploy many)
• Recovery procedure known (diagnose -> rollback -> reset)

• All secrets set per-project via

  eve secrets set

• Manifest uses

  ${secret.KEY}

  interpolation

• eve manifest validate --validate-secrets

  passes

• .eve/dev-secrets.yaml

  exists for local development
• Git credentials (

  github_token

  or

  ssh_key

  ) configured
• Service token permissions declared per service (default read-only; write opted in explicitly)

• @eve-horizon/auth

  middleware added to backend (

  eveUserAuth

  +

  eveAuthGuard

  , or

  eveAppUserAuth

  for multi-org apps)
• Auth config endpoint serves SSO discovery (

  eveAuthConfig

  )

• @eve-horizon/auth-react

  wraps frontend (

  EveAuthProvider

  +

  EveLoginGate

  or custom

  useEveAuth

  gate)

• createEveClient

  used for authenticated API calls from frontend
• Platform-injected auth env vars used (

  EVE_SSO_URL

  ,

  EVE_ORG_ID

  ,

  EVE_PROJECT_ID

  )
• Eve roles mapped to app roles in one place (bridge middleware), not scattered across controllers
• If passwordless:

  x-eve.auth.login_method: magic_link

  +

  invite_requires_password: false

• If multi-tenant:

  x-eve.auth.org_access.mode: allowlist

  with

  allowed_orgs

  declared; in-app admin invites use

  POST /auth/app-invites

• If domain-based onboarding:

  domain_signup.domains

  declares per-rule

  target_org

  ; more-specific rules listed first
• If custom domain:

  x-eve.auth.allowed_redirect_origins

  declared;

  eve project auth-context

  confirms resolved allowlist
• If branded:

  x-eve.branding

  declared (shared by invite and magic-link emails);

  From:

  display name and logo set

• App API wrapped in a domain CLI (e.g.,

  eden projects list

  )
• CLI declared in manifest via

  x-eve.cli

  with

  name

  and

  bin

• CLI bundled as single-file executable (esbuild for Node.js)
• CLI reads

  EVE_APP_API_URL_{SERVICE}

  and

  EVE_JOB_TOKEN

  automatically
• All CLI commands support

  --json

  for machine-readable output
• Agent skill references CLI commands, not raw curl/REST calls

• Services expose health endpoints
• The debugging ladder is understood (status -> diagnose -> logs -> recover)
• Pipeline logs are accessible via

  eve pipeline logs --follow

• SPA + API + managed Postgres implementation:

  references/spa-api-managed-db.md

• Manifest syntax and options:

  eve-manifest-authoring

• Deploy commands and error resolution:

  eve-deploy-debugging

• Secret management and access groups:

  eve-auth-and-secrets

• Pipeline and workflow definitions:

  eve-pipelines-workflows

• Local development workflow:

  eve-local-dev-loop

• Layering agentic capabilities onto this foundation:

  eve-agentic-app-design

• Auth SDK and SSO integration:

  eve-read-eve-docs

  →

  references/auth-sdk.md

• Object storage and filesystem:

  eve-read-eve-docs

  →

  references/object-store-filesystem.md

• External integrations (Slack, GitHub):

  eve-read-eve-docs

  →

  references/integrations.md