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 ports colliding, data getting mixed up, or containers running all the time. eph gives each workspace its own isolated services, started on demand, with host ports assigned automatically:

~/projects/app/      ->  eph-a1b2c3d4-postgres (localhost:54321)
~/projects/app-v2/   ->  eph-e5f6g7h8-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 (verifies a SHA-256 checksum before installing):

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

# Windows (PowerShell)
irm https://raw.githubusercontent.com/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 are published for macOS (x86_64, arm64), Linux glibc and musl (x86_64, arm64), and Windows (x86_64).

Or build from a source checkout:

cargo install --path .
# or
make install

eph runs natively on Linux, macOS, and Windows. The Docker-backed services (image=, dockerfile=, compose=) behave identically everywhere. The shell-based features (run= services, post-start/pre-stop hooks, and shell health checks) run through the platform shell: sh -c on Unix and cmd /C on Windows. The feature works natively on Windows, but a command string written for sh (pipes, $VAR, &&, POSIX tools) 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, then:

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

Getting Started walks through writing the .eph file from scratch.

Documentation

• User Guide - install, concepts, the .eph format, defining services, shell integration, recipes, troubleshooting, and a full 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 (see the command reference).
• 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.