fedService Federation

fed documentation

fed runs your local dev stack — Docker containers, native processes, and Compose services — from one config file. This page gets you from install to a running stack. The rest of the docs are reference.

Install

# macOS / Linux (Homebrew)
brew install service-federation/tap/fed

# Prebuilt binary
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/service-federation/fed/releases/latest/download/fed-installer.sh | sh

# From source
cargo install --git https://github.com/service-federation/fed

First config

Create service-federation.yaml in your project root (or run fed init for a starter config). Adapt it to your app — this example assumes a Node backend in ./backend that reads PORT and serves /health:

parameters:
  API_PORT:
    type: port
    default: 8080
  DB_PORT:
    type: port
    default: 5432

services:
  database:
    image: postgres:15
    ports: ["{{DB_PORT}}:5432"]
    environment:
      POSTGRES_PASSWORD: password
      POSTGRES_DB: app
    healthcheck:
      command: pg_isready -U postgres

  backend:
    process: npm start
    cwd: ./backend
    depends_on: [database]
    environment:
      PORT: '{{API_PORT}}'
      DATABASE_URL: 'postgres://postgres:password@localhost:{{DB_PORT}}/app'
    healthcheck:
      httpGet: 'http://localhost:{{API_PORT}}/health'

entrypoint: backend

Start it

fed start        # Start services (polls healthchecks, backgrounds)
fed status       # What's running
fed logs backend # View logs
fed stop         # Stop all

Once the host runtimes and Docker are installed, that's the whole project-specific workflow for the next teammate: git clone, fed start.

In a repo that already uses fed?

Joining a project that has a service-federation.yaml — or a coding agent dropped into a worktree? Three rules keep you out of trouble:

  1. New worktree? Isolate first. Run fed isolate enable before any other fed command — it persists, and everything after it gets this directory's own ports, containers, and volumes.
  2. Run tasks through fed. fed <script> (like fed test:integration) resolves the ports and DATABASE_URL this directory was actually allocated; the same command run bare hits whichever checkout owns the default ports. The scripts: section of the config lists what's available.
  3. Never fix a port conflict with --replace in a worktree — it kills the other checkout's services. fed isolate enable is the fix.

Isolation has the full story.

Troubleshooting

Services not starting?

fed logs <service> --tail 100

Port conflicts? Pick by cause:

fed isolate enable      # Another checkout owns the ports: give this one its own
fed start --replace     # A stray process squats on the port: kill it and start

In a worktree, always fed isolate enable — --replace would kill the other checkout's services. See Isolation.

Reference

Next: Configuration →