Eve Deploy and Debug Use these steps to deploy and diagnose app issues quickly. Environment Setup Get the staging API URL from your admin. Create and use a profile: eve profile create staging --api-url https://api.eh1.incept5.dev eve profile use staging Infrastructure Change Policy Never run kubectl apply , helm install , or any direct Kubernetes resource creation against shared infrastructure. All infrastructure changes go through Terraform. Use the Eve CLI ( eve env , eve env deploy ) to manage application deployments — the platform handles the underlying k8s resources. Deploy Flow (Staging)

Create env if needed

eve env create staging --project proj_xxx --type persistent

Deploy (requires --ref with 40-char SHA or a ref resolved against --repo-dir)

eve env deploy staging --ref main --repo-dir .

When environment has a pipeline configured, the above triggers the pipeline.

Use --direct to bypass pipeline and deploy directly:

eve env deploy staging --ref main --repo-dir . --direct

Pass inputs to pipeline:

eve

env

deploy staging

--ref

main --repo-dir

.

--inputs

'{"key":"value"}'

Deploy Polling Flow

When

eve env deploy

is called:

Direct deploy

(no pipeline): Returns

deployment_status

directly. Poll health endpoint until

ready === true

.

Pipeline deploy

Returns pipeline_run_id . Poll GET /pipelines/{name}/runs/{id} until all steps complete, then check health. Deploy is complete when: ready === true AND active_pipeline_run === null . Observe the Deploy eve job list --phase active eve job follow < job-id

Real-time SSE streaming

eve job watch < job-id

Poll-based status updates

eve job diagnose < job-id

Full diagnostic

eve job result < job-id

Final result

eve job runner-logs < job-id

Raw worker logs

Real-Time Debugging (3-Terminal Approach)

Terminal 1: Pipeline/job progress

eve job follow < job-id

Terminal 2: Environment health

eve env diagnose < project

< env

Terminal 3: System-level logs

eve system logs Debugging Workflows Job Won't Start Check dependencies: eve job dep list Check if blocked: eve job show → look at blocked_by Verify environment readiness: eve env show Check orchestrator: eve system orchestrator status Job Failed Get the error: eve job diagnose Check logs: eve job follow or eve job runner-logs If build failure: eve build diagnose If secret failure: eve secrets list --project Job Stuck Active Check if waiting for input: eve job show → effective_phase Check thread messages: eve thread messages Check runner pod: eve system pods System Issues API health: eve system health Orchestrator: eve system orchestrator status Recent events: eve system events Common Error Messages Error Cause Fix 401 Unauthorized Token expired eve auth login git clone failed Missing credentials Set github_token or ssh_key secret service not provisioned Environment not created eve env create image pull backoff Registry auth failed If using BYO/custom registry, verify REGISTRY_USERNAME + REGISTRY_PASSWORD ; for managed apps use registry: "eve" healthcheck timeout App not starting Check app logs, verify ports in manifest Build Failures If a deploy pipeline fails at the build step: eve build list --project < project_id

eve build diagnose < build_id

eve build logs < build_id

eve secrets list --project < project_id

Required for BYO/custom registry: REGISTRY_USERNAME, REGISTRY_PASSWORD

Common build failures:

Registry auth

For BYO/custom registry, verify

REGISTRY_USERNAME

and

REGISTRY_PASSWORD

secrets

Dockerfile not found

Check

build.context

path in manifest

Multi-stage build failure

BuildKit handles these correctly; Kaniko may have issues

Workspace errors

Build context not available — check

eve build diagnose

Worker Image Registry

Eve publishes worker images to the configured private registry with these variants:

Variant

Contents

base

Node.js, git, standard CLI tools

python

Base + Python runtime

rust

Base + Rust toolchain

java

Base + JDK

kotlin

Base + Kotlin compiler

full

All runtimes combined

Version pinning

Use semver tags (e.g., v1.2.3 ) in production. Use SHA tags or :latest in development. Platform Environment Variables Eve automatically injects these into every deployed service container: Variable Purpose EVE_API_URL Internal cluster URL for server-to-server calls EVE_PUBLIC_API_URL Public ingress URL for browser-facing apps (when configured) EVE_SSO_URL SSO broker URL for user authentication (when configured) EVE_PROJECT_ID Current project ID EVE_ORG_ID Current organization ID EVE_ENV_NAME Current environment name Use EVE_API_URL for backend calls. Use EVE_PUBLIC_API_URL for browser/client-side code. Services can override any of these by defining them explicitly in their manifest environment section. Access URLs URL pattern: {service}.{orgSlug}-{projectSlug}-{env}.{domain} Local dev default domain: lvh.me Ask the admin for the correct domain (staging vs production). Environment-Specific Debugging Environment How to Debug Local (k3d) Direct service access via ingress, eve system logs Docker Compose docker compose logs , dev-only (no production use) Kubernetes Ingress-based access, kubectl -n eve logs as last resort Workspace Janitor Production disk management for agent workspaces: EVE_WORKSPACE_MAX_GB — total workspace budget EVE_WORKSPACE_MIN_FREE_GB — trigger cleanup threshold EVE_SESSION_TTL_HOURS — auto-evict stale sessions LRU eviction when approaching budget; TTL cleanup for idle sessions K8s: per-attempt PVCs deleted on completion