using-eph

---

name: using-eph description: Use when working in a repository that uses eph for ephemeral dev services (a .eph file exists, or eph is on PATH). Covers the local loop: start per-workspace services with eph up, load their connection details with eph env, and tear them down with eph down / eph clean. Also covers detecting an eph workspace, reading the .eph file, and the auto-assigned ports that mean you must never hardcode a connection string.

Using eph

eph is "dotenv for services": a CLI that starts the dev services a project needs (Postgres, Redis, MinIO, ...) from a .eph file in the project root. Containers are namespaced by a hash of the workspace path and host ports are assigned randomly, so two checkouts never collide. Your job as an agent working in such a repo is to bring those services up, wire your tools at the ports eph actually assigned, and tear them down when you are done.

Detect an eph workspace

A workspace is any directory with a .eph file (eph searches upward from the current directory, like git).

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

eph check and eph info never touch Docker, so they are always safe to run first to learn the shape of the workspace.

The core loop

eph up                   # start all services: pre-start, pull/build, wait for health, post-start
eval "$(eph env)"        # load resolved connection env vars into your shell
# ... do your work against the running services ...
eph down                 # stop services, keep containers + data for a fast restart

• eph up [SERVICE...] starts all services, or just the named ones. It is idempotent: a running service is reused, a stopped container is restarted, and an absent one is created fresh.
• eph up blocks until each service passes its health check, so when it returns the services are ready (one exception below for services with no health check).
• An unknown service name is an error.

Reading the environment (never hardcode ports)

Host ports are random and change every time a container is created, so the only correct way to reach a service is through eph env. Do not read a port out of the .eph file: that is the container port, not the published host port.

eval "$(eph env)"                        # bash / zsh / sh
eph env -f fish | source                 # fish
eph env -f json | jq -r .DATABASE_URL    # machine-readable, best for scripts

eph env prints only the top-level KEY=VALUE variables from the .eph file, with ${service.port} style interpolations filled in from running services. A reference to a stopped service is left unresolved, so run eph up first.

Tearing down

Three deliberately distinct levels, from lightest to heaviest:

Command	Effect
eph down	Stop services; keep containers and volume data for a fast restart.
eph down --rm (alias -r)	Also remove the containers; named-volume data is kept. The next up recreates them.
eph clean	Full reset: remove containers, remove per-workspace named volumes (deletes that data), and delete saved state.

compose services are always fully torn down (--rm is a no-op for them); clean removes only the named volumes declared in the .eph file, not Compose-internal ones.

Reading the .eph file

It is INI-with-.env: top-level KEY=VALUE lines are shell env vars, and [name] sections are services. Comments must be on their own line (#); a # after a value is part of the value, so do not add inline comments.

[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

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

• A service names exactly one source: image=, dockerfile= (+ context=), compose= (+ expose.<name>=), or run= (a host process via sh -c).
• port= is a container port published on a random host port; ${svc.port} in a top-level variable resolves to the assigned host port at eph env time.
• For a run= service (a first-party app eph launches), port=auto / port.<name>=auto make eph allocate a free host port and inject it into the process; reference the service's own assigned port as ${svc.port} in its env.X (e.g. env.PORT=${web.port}). eph keeps the port stable across restarts and re-launches the app on a fresh port if it dies on a port conflict. Still never hardcode it — read it via eph env / ${svc.port}.
• env.X= is set inside the container; the trailing DATABASE_URL= is a shell env var emitted by eph env.
• volume=name:/path is a per-workspace named volume; healthcheck for an image service runs with no shell (whitespace-split, docker exec); the lifecycle hooks run on the host via sh -c with eph's resolved environment injected (see below).

Lifecycle hooks see eph's environment

Four hooks bracket a service, in order: pre-start (before it is created), post-start (after it is healthy), pre-stop (before it stops), post-stop (after it has stopped). All run with the same variables eph env emits already in their environment, so a database migration or codegen step just works:

[api]
run=./bin/server
pre-start=go generate ./...                     # runs before the server boots
post-start=psql "$DATABASE_URL" -f schema.sql   # DATABASE_URL is already set
pre-stop=./scripts/backup.sh
post-stop=rm -rf .cache/scratch                 # cleanup eph cannot do itself

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

Each hook receives, layered in this order (later wins):

1. the resolved top-level .eph variables (exactly what eph env prints),
2. EPH_* metadata: EPH_WORKSPACE_ID, EPH_WORKSPACE_ROOT, EPH_CONTAINER_PREFIX, and per service EPH_<SERVICE>_HOST, EPH_<SERVICE>_PORT, EPH_<SERVICE>_PORT_<NAME> (for named ports), EPH_<SERVICE>_CONTAINER (service names upper-cased, - -> _),
3. the owning service's own env.X= values.

pre-start runs just before its own service is created, so it cannot see that service's own port, but it does see any service already up (backing services start before run= apps). Use it for prep the service depends on, like codegen. post-start hooks run only after every service in the up is healthy, so a hook may reference any other service's port (${redis.port} resolves even if redis started after the service whose hook needs it). post-stop runs after its service has stopped and sees the same pre-teardown environment as pre-stop.

pre-start and post-start run on every eph up (fresh create or restart); a failing pre-start aborts the up before its service starts and a failing post-start aborts the up. A failing pre-stop aborts the down / clean and leaves the service running so you can fix and retry; a failing post-stop aborts the rest of teardown, but its service is already stopped. Write hooks to be idempotent (a migration that no-ops when already applied, an INSERT ... ON CONFLICT seed). For one-off, non-idempotent work, use eph run instead.

Pass --skip-hooks to skip hooks for one invocation: eph up --skip-hooks starts services without pre-start/post-start; eph down --skip-hooks / eph clean --skip-hooks tear down without pre-stop/post-stop (the escape hatch when a broken hook is wedging teardown).

Running one-off commands with the environment: eph run

eph run <cmd>... runs a command in the workspace root with the resolved environment (the eph env variables plus the EPH_* metadata) already set, so you do not have to eval "$(eph env)" first:

eph run psql "$DATABASE_URL"        # NOTE: $DATABASE_URL is expanded by YOUR shell
eph run ./scripts/seed.sh           # the script sees DATABASE_URL, EPH_* itself
eph run sh -c 'psql "$DATABASE_URL" < dump.sql'   # use sh -c for shell features

The command is executed directly, not through a shell, so eph does not expand $VAR in the arguments; wrap it in sh -c '...' when you need shell expansion of eph's injected variables, piping, or globbing. eph run exits with the command's own exit code. Use it for repeatable operations (seeding, resets, ad-hoc queries) -- unlike post-start, it runs every time you invoke it.

Claude Desktop preview servers: eph dev

eph dev runs the whole stack in the foreground for a Claude Desktop preview server (.claude/launch.json), which launches one command and watches its port but has no setup or teardown hook. eph dev fills both: it runs pre-start hooks (e.g. codegen), brings every service up, foregrounds a run= app with eph's own stdin, stdout, and stderr wired through to it, runs post-start (seeding), and on stop tears the stack down -- eph down by default, or eph clean with --clean (each running pre-stop then post-stop).

// .claude/launch.json -- point the preview server at eph dev
{
  "version": "0.0.1",
  "configurations": [
    { "name": "web", "runtimeExecutable": "eph", "runtimeArgs": ["dev"], "port": 3000, "autoPort": true }
  ]
}

• Model the app as a run= service with port=auto. The app runs on its own internal port; eph dev opens the $PORT the preview server injects (its autoPort) as a forwarding gate to the app, but only after post-start hooks finish. Since the preview watches $PORT, it does not see the app as ready until seeding is done, not the instant the server can answer a health check. Do not also give the app a fixed port.
• With no SERVICE the sole run= service is foregrounded; eph dev <service> picks one when the .eph defines several.
• Teardown defaults to eph down (keeps data for a fast relaunch, since Claude restarts the server during a session). Use eph dev --clean (runtimeArgs: ["dev", "--clean"]) for a pristine reset on every launch.
• A hard kill (not a normal stop) skips teardown and leaves services up, recoverable with eph down. If the app crashes on its own, eph dev leaves services up for inspection (eph logs <service>) and exits non-zero.
• eph must be on the app's PATH; the desktop app may not inherit your shell PATH, so use an absolute path in runtimeExecutable if it cannot find eph.

Inspecting logs: eph logs

eph logs                 # all services interleaved, each line tagged [name]
eph logs -f              # follow all services at once; Ctrl-C to stop
eph logs <service>       # one service, raw (untagged)
eph logs -f <service>    # follow one service
eph logs -n 50 <service> # last 50 lines

Works for every service type: run= services read from a captured log file, while image= / dockerfile= / compose= services proxy docker logs / docker compose logs. With no service, every service is streamed concurrently and interleaved (compose-style), each line prefixed by a color-coded [name] tag; a single eph logs <service> is untagged and pipe-friendly. Logs show even for a stopped service, so a run= service that died on startup still leaves a trace -- check eph logs <service> when a service is missing from eph status.

Behaviors that matter

• Ports are random and change per create. Never hardcode a host port; always go through eph env.
• Idempotent up. A running service is reused and a stopped one restarted, but pre-start and post-start hooks run on every eph up regardless. Write them to be idempotent (migrations that no-op when applied, codegen that overwrites in place), or move one-off work to eph run. A failing pre-start aborts the up before its service starts; a failing post-start aborts the up.
• Image health checks have no shell: one whitespace-split command, no pipes, &&, $VAR, or quoted spaces, and the binary must exist in the image.
• A service with no health check is given a fixed short wait, so it may need a moment to accept connections after eph up returns; retry your first connect.
• Isolation by path: two checkouts are different containers, volumes, and ports. There is no eph init (author .eph by hand).
• Output is on stdout; logs go to stderr. eph env output is clean for eval and piping. Add -v / --verbose for debug logging on stderr.

Safe defaults for automation

1. Validate before acting: eph check.
2. Start and load in the same step so the env is fresh: eph up && eval "$(eph env)" && <your command>.
3. Tear down in an always-run step (even on failure): eph clean.
4. Treat .eph as possibly holding dev credentials: do not print it to logs or commit one with real secrets.