eph

Ephemeral services per workspace. Like .env files, but for services.

When you work on multiple projects, or multiple checkouts of the same project, you need local services like Postgres, Redis, or MinIO without shared data or fixed Docker ports. eph gives each workspace its own namespaced services, starts them on demand, and assigns host ports for direct containers automatically:

~/projects/app/      ->  eph-a1b2c3d4e5f60718-postgres (localhost:54321)
~/projects/app-v2/   ->  eph-e5f60718293a4b5c-postgres (localhost:54322)

You describe the services in a .eph file, run eph up, and load the resolved connection strings into your shell with eval "$(eph env)".

Install

Install the latest release binary (the script verifies a SHA-256 checksum before installing):

# Linux / macOS
curl -sSfL https://github.com/ghraw/attunehq/doteph/main/scripts/install.sh | bash

# Windows (PowerShell)
irm https://github.com/ghraw/attunehq/doteph/main/scripts/install.ps1 | iex

Pass -v X.Y.Z (shell) or set $env:Version (PowerShell) to pin a version, or download a tar.gz directly from the releases page. Prebuilt binaries cover macOS (x86_64, arm64), Linux glibc and musl (x86_64, arm64), and Windows (x86_64).

Set EPH_REPO (an owner/repo, default attunehq/doteph) or EPH_BASE_URL (replaces the GitHub download base entirely, with no release tag appended after it) to install from a fork or a mirror; eph update honors the same two variables.

Once installed, keep it current with the built-in updater, which downloads the latest release, verifies its SHA-256 checksum, and swaps the binary in place:

eph update           # install the latest release
eph update --check   # just report whether one is available

Or build from a source checkout:

cargo install --path .
# or
make install

eph runs natively on Linux, macOS, and Windows. Docker-backed services use the local Docker daemon and each platform's path conventions. The shell-based features (run= services, lifecycle hooks, and shell health checks) run through the platform shell (sh -c on Unix, cmd /C on Windows), so a command string written for sh may need a cmd-compatible form; to keep writing POSIX command strings on Windows, run eph inside WSL.

Quick taste

Describe your services in a .eph file:

[postgres]
image=postgres:16-alpine
port=5432
env.POSTGRES_USER=dev
env.POSTGRES_PASSWORD=dev
env.POSTGRES_DB=myapp
healthcheck=pg_isready -U dev

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

Then run the loop:

eph up                 # start services (waits until healthy)
eval "$(eph env)"      # load connection strings into your shell
eph down               # stop when you are done

Your own app fits in the same file as a run= service with port=auto, so eph allocates its port, injects the resolved environment, and (with eph dev) runs the whole stack as one foreground command. Tag services with roles (role=dep, role=app) to bring up one tier at a time, for example prewarming databases in a Claude Code SessionStart hook without starting your app.

Documentation

The full guide lives at attunehq.github.io/doteph, and the same pages are readable in-repo:

• User Guide: a guided path from install to full understanding: getting started, concepts, the .eph format, services, running your app, shell integration, recipes, troubleshooting, and a complete command reference. New here? Start with Getting Started.
• For Agents and Scripts: a terse quick reference for AI coding agents and automation. Run eph skills install to drop that guidance into a repo as a skill your agent discovers automatically.
• Developer Guide: architecture, building and testing, and a tour of the internals, for working on eph itself.
• Contributing: working style, pull requests, releases.

License

eph is licensed under the MIT License, Copyright (c) 2026 Attune, Inc.

The repository also vendors third-party Rust coding-guidance skills under .agents/skills/ (notably the MIT-licensed rust-skills pack). See NOTICE for attribution and the licenses of vendored and externally sourced material.