For Agents and Scripts

A terse, scannable reference for AI coding agents and automation working in a repo that uses eph. Everything here is also explained, with rationale, in the rest of the user guide. If you are an agent, you can act from this page alone.

What eph is

A CLI that starts per-workspace dev services (Postgres, Redis, and so on) from a .eph file in the project root. Containers are namespaced by a hash of the workspace path; host ports are auto-assigned. It is .env for services.

Detect and inspect

test -f .eph && echo "this project uses eph"   # a workspace has a .eph file
eph check        # validate the file, list services + env vars (no Docker)
eph info         # workspace id, container prefix, paths (no Docker)
eph status       # what is currently running, with ports

Core loop

eph up                       # start all services (idempotent, waits for health)
eph env -f json              # machine-readable resolved env vars (stdout)
eval "$(eph env)"            # load resolved env into the shell
eph down                     # stop (keep containers + data)
eph down --rm                # stop and remove containers (keep volume data)
eph clean                    # remove containers + named volumes (DATA LOSS) + state

Prefer eph env -f json for parsing:

env_json=$(eph env -f json) || exit $?
DATABASE_URL=$(printf '%s' "$env_json" | jq -r .DATABASE_URL)

Prewarm dependency services on session start

If the .eph file defines roles (a roles_order plus a role= on every service), you can bring up just the dependency tier without starting the first-party app. This is the recommended agent integration: a Claude Code SessionStart hook that prewarms the databases and caches, injects their connection env, and leaves the app alone (starting it could bind preview ports or trigger side effects the agent did not ask for).

The hook runs eph up --role dep (substitute the file’s actual dependency role name), then appends eph env to the file named by $CLAUDE_ENV_FILE, which Claude Code sources so later Bash tool calls inherit DATABASE_URL and friends:

#!/usr/bin/env bash
# SessionStart hook: prewarm dependency services and inject their env.
eph up --role dep >/dev/null 2>&1 || exit 0
if [ -n "$CLAUDE_ENV_FILE" ] && resolved_env=$(eph env); then
  printf '%s\n' "$resolved_env" >> "$CLAUDE_ENV_FILE"
fi

Wire it in .claude/settings.json (project scope, so everyone opening the repo or a worktree gets it):

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [ { "type": "command", "command": ".claude/hooks/eph-prewarm.sh" } ]
      }
    ]
  }
}

Notes:

• eph up is idempotent, so a later eph up or eph dev reuses the prewarmed dependency services instead of restarting them. eph dev on exit leaves the tier it adopted running, warm for the next command.
• --role dep brings up the dependency role and its dependency closure only, never the app. Add --skip-hooks to prewarm without running post-start seeding; the plain form above runs it.
• eph env succeeds only when every top-level interpolation resolves. Keep exported prewarm variables dependent only on services in the selected closure; put app-only values in the app’s env.* or load the full environment after the app starts. The command substitution above discards partial output.
• There is no eph hooks install: roles are user-defined names, so substitute your own. For a personal, cross-repo version put the same block in ~/.claude/settings.json instead.
• Optional: a SessionEnd hook running eph down --role dep stops the tier when a session ends. The default is to leave it warm for reuse.

See Recipes for the full write-up.

Command cheat sheet

To persist this guidance as a skill your agent discovers automatically on every checkout, run eph skills install and commit the written files. It bundles a using-eph skill into .claude/skills/ and .agents/skills/. eph skills check reports missing or drifted copies; eph skills install --force writes the copies embedded in the installed binary.

Output is on stdout; logs on stderr. Unknown service or format names are errors.

.eph file cheat sheet

INI-with-.env. Top-level KEY=VALUE are shell env vars; [name] sections are services. Comments are own-line only (#); a # after a value is part of the value, so the example below contains no inline comments. Do not add them.

[postgres]
image=postgres:16-alpine
port=5432
env.POSTGRES_USER=dev
volume=pgdata:/var/lib/postgresql/data
healthcheck=pg_isready -U dev
post-start=npm run db:migrate

[env]
DATABASE_URL=postgres://dev@localhost:${postgres.port}/app

Line by line: image= is the source (one of image/dockerfile/compose/run); port= is a container port published on a random host port; env.X is passed to the service runtime; volume=name:/path is a per-workspace named volume; healthcheck for an image service runs without a shell (whitespace-split, docker exec); post-start runs on the host via the platform shell (sh -c on Unix, cmd /C on Windows) after every service is healthy; [env] switches back to top-level variables (see below); the trailing DATABASE_URL= is a shell env var emitted by eph env, with ${postgres.port} filled in at runtime.

Sections do not end at blank lines. A bare KEY=VALUE line directly after a service section is a parse error, not a silent trailing variable. Top-level variables (what eph env prints) only parse in two places: above the first section, or inside a reserved [env] section (which may repeat). env.KEY= inside a service section is a different thing entirely: it sets a variable for that service, not your shell. Writing an UPPERCASE key straight into a service section, meaning it for the shell, is the single most common mistake when generating a .eph file: eph check rejects it and names both fixes (env.KEY= for the service, [env] for the shell).

Service sources (exactly one per section; a second one is a parse error)

Properties

Every property above except the four marked repeatable is single-valued: a second occurrence is a parse error, as is an unknown property (the error lists every known one), an invalid or duplicate service/port name, or an empty value (everything except env.<KEY>=, where empty is legal).

Interpolation (resolved against running services)

Unknown services, unknown properties, missing named ports, and ambiguous bare ports are parse errors. A valid reference to a stopped service fails closed at runtime: hooks, eph run, and service startup do not receive a raw placeholder. eph env unsets affected shell variables and fails; JSON omits them and fails. Compose aliases use expose.<alias>=<compose-service>:<port> and resolve as ${svc.port.<alias>}.

Resolved values are host-facing (${svc.port} is the host’s loopback port). That is correct for a hook, eph run, or a run= process, all of which execute on the host, but usually wrong for one container reaching another: a container’s own env.X=...${sibling.port} resolves to a localhost:PORT string that, from inside that container, points back at itself. Reach a sibling container from inside another container via host.docker.internal or a shared Docker network, not through this interpolation.

Behaviors that matter

• Idempotent up reconciles configuration. A resource is reused or restarted only when its canonical runtime fingerprint still matches. Source, immutable image, port, resolved environment, volume, health, build, and command drift removes the old backend and recreates it. Dockerfile sources build through Docker’s cache on every up. Reused services rerun declared health checks; failed starts are removed. Hooks still run on every up.
• Ports are random and change per create. Never hardcode; always go through eph env.
• Image health checks have no shell: one whitespace-split command, no pipes / && / $VAR / quoted spaces. The binary must exist in the image.
• Unresolved runtime references fail closed. Hooks, services, health checks, and eph run never receive a raw eph placeholder.
• Isolation by path: two checkouts = different containers, volumes, ports.
• compose is thin but tracked (by project label): down and down --rm both fully tear it down. Compose services cannot declare .eph volumes, and clean does not remove volumes defined inside the Compose file.
• No eph init: author .eph by hand.
• Windows runs natively: run=, hooks, and shell health checks go through cmd /C (vs sh -c on Unix), so command strings may need a cmd-compatible form. WSL keeps POSIX command strings working.
• State survives crashes. state.json is saved after each service starts (not once at the end), so a failed eph up still leaves eph down able to find and stop whatever did start. A corrupt state.json is quarantined to state.json.corrupt with a warning rather than blocking the command. eph up/down/clean on one workspace serialize against each other via an OS lock that a crashed process can never leave stuck.

Safe defaults for automation

• Validate before acting: eph check.
• Start and load in CI in the same step: eph up && eval "$(eph env)" && <cmd>.
• Tear down in an always-run step: eph clean.
• Treat .eph as possibly containing dev credentials; do not print it to logs or commit one with real secrets.