Deploy Eigencloud

EigenCloud Deployment — Agent Runbook

You are deploying to EigenCloud TEE (Trusted Execution Environment) infrastructure. This is a sequential gate-based runbook. Execute each gate in order. On failure, apply the fix and retry before proceeding.

Constraints you will get wrong without reading this

1. All images must be linux/amd64. TEEs run on Intel TDX. An arm64 image will deploy successfully but crash at runtime with no useful error. On Apple Silicon: always docker buildx build --platform linux/amd64.

2. Always use hex app IDs (0x...), never display names. Name lookup is profile-based and silently fails on some commands (confirmed: app info by name returns not found while the same app works fine by ID).

3. Exit codes. Most commands return exit 1 for any error (parse stdout/stderr to see what went wrong). app deploy and app upgrade are the exception — they emit distinct codes so you can branch without parsing text:

   • 2 — invalid/missing input; failed before any build. Fix flags and re-run.
   • 3 — build/push failed; no on-chain transaction was attempted. No image was produced.
   • 4 — build/push succeeded but the on-chain transaction failed. The image is already built and pushed; re-running deploy/upgrade reuses it (you are not paying for another ~7-min build).
   • 1 — generic/unclassified error.

4. Env vars are encrypted client-side before transmission. They are only decrypted inside the TEE. Never visible in logs or API responses.

5. Derived keys (EVM + Solana wallets) are deterministic per app ID. They persist across stop/start/upgrade. They are permanently lost if you terminate and redeploy — new app ID means new keys.

6. --json is only available on: app status, app releases, build submit, build status, build info, build list, build verify. It is NOT available on: app list, app info, app deploy, billing status. Do not pass --json to commands that don't support it.

7. No --dry-run exists anywhere in the CLI. No --yes on deploy/upgrade (they don't prompt interactively). --force only exists on: app terminate, billing cancel, auth logout.

Current environment

CLI version: !ecloud --version 2>&1 Auth: !ecloud auth whoami 2>&1 Environment: !ecloud compute environment show 2>&1 Host arch: !uname -m Docker: !docker version --format '{{.Client.Version}}' 2>&1

Gate 0: Prerequisites

Run all five checks. Fix any that fail before proceeding.

CLI

ecloud --version

Pass: outputs @layr-labs/ecloud-cli/<version>. Fail: npm install -g @layr-labs/ecloud-cli

Auth

ecloud auth whoami

Pass: output contains Address: 0x and Source: stored credentials. Fail:

• New user → ecloud auth generate --store (generates key, stores in OS keyring)
• Has existing key → ecloud auth login (interactive prompt for private key)
• CI/automation → set ECLOUD_PRIVATE_KEY env var instead of keyring

Environment

ecloud compute environment show

Two environments exist:

• sepolia — Testnet (default). Uses Sepolia ETH for gas. Deploy here first to test. Billing subscription flow is the same but uses test payment methods. All on-chain records are on Sepolia. Dashboard: verify-sepolia.eigencloud.xyz.
• mainnet-alpha — Production. Uses real ETH for gas, real USDC for payments. Apps are publicly visible on the mainnet verify dashboard: verify.eigencloud.xyz. Use when the app is ready for real users and real funds.

Always develop and test on sepolia first, then redeploy to mainnet-alpha for production.

Pass: output shows the intended environment. Fix: ecloud compute env set sepolia --yes (or mainnet-alpha).

Billing

ecloud billing status

Pass: output contains Status: ✓ Active. Fail:

1. ecloud billing subscribe — creates the subscription
2. ecloud billing top-up --amount 50 — purchases USDC credits

Docker

docker version --format '{{.Client.Version}}'

Pass: outputs a version string. Fail: install Docker Desktop or Docker Engine.

Gate 1: Build and push image

Determine host architecture, then build accordingly.

uname -m

If arm64 (Apple Silicon — most common dev machine):

docker buildx build --platform linux/amd64 -t <registry>/<image>:<tag> --push .

This cross-compiles AND pushes in one step. The --push flag is required because buildx cross-compiled images can't be loaded into the local daemon.

If x86_64 (native):

docker build -t <registry>/<image>:<tag> . && docker push <registry>/<image>:<tag>

After push, verify architecture:

docker manifest inspect <registry>/<image>:<tag> 2>&1 | grep architecture

Must contain amd64. If it shows arm64, the image will crash in the TEE.

Image requirements:

• Must be in a public registry (Docker Hub, GHCR, etc.) — the TEE pulls at deploy time
• Must be OCI-compliant
• App should bind to 0.0.0.0 on its listening port (not 127.0.0.1)

Gate 2: Deploy

Instance types

Suffix convention (inferred, not officially documented): t = Intel TDX, s = likely AMD SEV, v = vTPM. Only TDX is confirmed in official EigenCloud docs. Prices are approximate — sourced from billing line items and may change.

For verifiable execution with full attestation, use a t (TDX) instance.

Prepare .env

Create .env in the project directory. The CLI reads it by default (override with --env-file <path>).

PORT=3000
MY_SECRET=value

The app's listening port is whatever your application binds to. EigenCloud templates default to 3000 but your app may use any port. Do NOT set EIGEN_MACHINE_TYPE_PUBLIC — it is injected automatically from --instance-type.

Path A: Deploy pre-built image

ecloud compute app deploy \
  --name <app-name> \
  --image-ref <registry>/<image>:<tag> \
  --instance-type g1-standard-4t \
  --env-file .env \
  --log-visibility public \
  --skip-profile \
  --verbose

On success, stdout contains the app ID (0x followed by 40 hex chars) and a dashboard URL. Save the app ID — all subsequent commands need it.

Important: The --name flag sets the CLI lookup name only, NOT the display name on the verify dashboard. To set the dashboard profile (name, description, website), run ecloud compute app profile set after deploy — see Gate 4.

Path B: Verifiable build (from git source)

The platform clones the repo, builds inside the TEE, and records the build hash onchain for provenance verification.

ecloud compute build submit \
  --repo https://github.com/org/repo \
  --commit <full-40-char-sha> \
  --dockerfile Dockerfile \
  --context . \
  --json

This blocks and streams build logs by default. Use --no-follow to exit immediately after submission.

If --no-follow was used, poll for completion:

ecloud compute build status <build-id> --json

On build failure: ecloud compute build logs <build-id> --tail 50

Then deploy with the verifiable flag:

ecloud compute app deploy \
  --name <app-name> \
  --verifiable \
  --repo https://github.com/org/repo \
  --commit <sha> \
  --instance-type g1-standard-4t \
  --env-file .env \
  --skip-profile \
  --verbose

Additional flags for complex builds:

• Multi-stage with dependencies: --build-dependencies sha256:...
• TLS via Caddy: --build-caddyfile Caddyfile

Deploy output parsing

Gate 3: Verify deployment

Deploy returns before the app is fully running. Wait for it to settle.

Wait for running status

Use app status --wait — do NOT tight-loop app info. A bare ecloud compute app info <app-id> is a one-shot fetch with no pacing; calling it in a shell loop (or a hardcoded sleep) hammers the API and trips server rate limits. status --wait blocks using the CLI's internal watch loop, which paces requests and backs off on 429/502/503/504.

# Blocks until the app reaches a terminal status or the timeout elapses.
ecloud compute app status <app-id> --wait

# Bound the wait (default 600s) and/or get machine-readable output:
ECLOUD_WATCH_TIMEOUT_SECONDS=180 ecloud compute app status <app-id> --wait
ecloud compute app status <app-id> --json   # one-shot: {"appId","status"}

--json emits {"appId":"0x...","status":"Running"}. Status is one of: Running, Deploying, Stopped, Terminated, Failed, Unknown.

• If status --wait returns Running → proceed to health check.
• If it times out (prints a recovery hint) → check ecloud compute app info <app-id> once for details and ecloud compute app logs <app-id>.
• If Failed → check logs: ecloud compute app logs <app-id>

Use app info <app-id> (one-shot, not in a loop) only when you need richer details — IP, EVM/Solana addresses, release info:

• IP: — public IP address (direct, no load balancer)
• EVM Address: — TEE-derived EVM wallet (deterministic per app ID)
• Solana Address: — TEE-derived Solana wallet (deterministic per app ID)

Health check

The app's listening port is exposed directly on the public IP. Check whichever port your app binds to (templates default to 3000).

curl -s -o /dev/null -w "%{http_code}" http://<IP>:<APP_PORT>/

Verify provenance (verifiable builds only)

ecloud compute build verify <image-digest-or-build-id-or-commit> --json

Exit 0 + JSON with provenance data = verified. No builds found = image was not built through the verifiable build pipeline.

Gate 4: Post-deploy setup

Set app profile (dashboard display name)

The verify dashboard shows "(unnamed)" until you set a profile:

ecloud compute app profile set <app-id> \
  --name "MyApp" \
  --description "What the app does" \
  --website "https://myapp.com" \
  --x-url "https://x.com/myapp"

Constraints: Profile name cannot contain spaces. Use hyphens or camelCase (e.g., CitiBike-MPP not Citi Bike MPP).

Dashboard URLs:

• Sepolia: https://verify-sepolia.eigencloud.xyz/app/<app-id>
• Mainnet: https://verify.eigencloud.xyz/app/<app-id>

Verifiable builds (recommended for production)

Without --verifiable, the dashboard shows Build: - and Provenance: -, undermining the trust story. To upgrade an existing dev-image deploy to a verifiable build:

ecloud compute app upgrade <app-id> \
  --verifiable \
  --repo https://github.com/org/repo \
  --commit <full-40-char-sha> \
  --build-dockerfile Dockerfile

The repo must be public. After upgrade, verify provenance:

ecloud compute app releases <app-id> --full
ecloud compute build verify <image-digest-or-commit> --json

Upgrade

ecloud compute app upgrade <app-id> \
  --image-ref <registry>/<image>:<new-tag> \
  --env-file .env \
  --verbose

For verifiable upgrade:

ecloud compute app upgrade <app-id> \
  --verifiable \
  --repo https://github.com/org/repo \
  --commit <new-sha> \
  --verbose

After upgrade, re-run Gate 3 (app status <app-id> --wait until Running, then health check).

App ID and derived keys persist across upgrades.

Rollback

No native rollback command exists. Manual procedure:

1. Find previous release:

ecloud compute app releases <app-id> --json

The releases array is ordered by creation time. Previous release = second-to-last entry. Extract registryUrl and imageDigest.

2. Upgrade to previous image:

ecloud compute app upgrade <app-id> \
  --image-ref <registryUrl>@<imageDigest> \
  --verbose

3. Verify: re-run Gate 3.

If upgrade fails (app stuck or crashed):

ecloud compute app terminate <app-id> --force
ecloud compute app deploy --name <name> --image-ref <old-image> --instance-type <type> --verbose

This creates a new app ID. Derived keys will be different. Only do this as a last resort.

Lifecycle commands

ecloud compute app stop <app-id>              # pause instance, stops billing
ecloud compute app start <app-id>             # resume paused instance
ecloud compute app terminate <app-id> --force # permanent delete, no confirmation
ecloud compute app list                       # show active apps
ecloud compute app list --all                 # include terminated
ecloud compute app logs <app-id> --watch      # stream live logs
ecloud compute app info <app-id> --watch      # auto-refresh every 5s
ecloud compute app info <app-id> --address-count 5  # show more derived addresses

Error recovery

Internal notes

• TEE hostname inside the container is tee-<app-id> (lowercase hex, e.g. tee-0x5940e21020adb5bd2d1fdda4d498edc0eb1f60df). This appears in structured logs.

• Networking: the app binds to 0.0.0.0:<port> inside the TEE. That port is exposed directly on the public IP — no load balancer or reverse proxy unless you add Caddy for TLS.

• TLS: requires running ecloud compute app configure tls, setting a DNS A record pointing to the instance IP, then deploying/upgrading. Let's Encrypt rate limit: 5 certs/week per domain. Use ACME staging for first deploy to avoid hitting limits.

• KMS: single KMS node in GCP during Mainnet Alpha. Threshold KMS is in development. Keys are derived deterministically after the KMS verifies TEE attestation + onchain whitelisted code.

• EVM derivation path: m/44'/60'/0'/0/0 (and incrementing). Solana: m/44'/501'/0'/0'.

• App releases JSON schema includes: appId, imageDigest (sha256), registryUrl, publicEnv, encryptedEnv, upgradeByTime (unix timestamp), createdAt, createdAtBlock.

• TEE attestation is internal-only (as of April 2026). The TDX attestation JWT exists inside the container at /run/container_launcher/attestation_verifier_claims_token but is consumed by KMS at boot and never surfaced to external callers. HTTP response headers contain no attestation proof. The verify dashboard "Attestations" section may show "Loading..." with no data. Public runtime attestations are on the platform roadmap but not yet shipped.

• Mainnet provisioning is slower than sepolia. Sepolia apps are typically reachable within 30-60 seconds. Mainnet apps may show Running status with memory usage but have no network connectivity for 5+ minutes. This is a known discrepancy.

• tee-0x hostname appears regardless of instance type. Log hostnames show tee-<app-id> even on vTPM (g1-micro-1v) instances, not just TDX instances. Do not use the hostname to infer attestation type.

For full CLI flag details, run ecloud <command> --help.