Get a stack running

fed runs native applications and Docker dependencies from one config file. Start with the included demo, join a repository that already uses fed, or add a small fed.yaml to your own project.

Install fed

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

# With Homebrew
brew install service-federation/tap/fed

# Current main branch from source
cargo install --git https://github.com/service-federation/fed --locked

Run fed doctor to check Docker, Compose, and Git. The CLI works without a Service Federation Cloud account.

Try the included demo

The demo runs PostgreSQL in Docker, applies a schema migration, then starts a native Python API. It lets you test the complete path before changing one of your projects.

git clone https://github.com/service-federation/fed.git
cd fed/docs/demo

fed start
curl http://localhost:18480/health
fed status
fed stop
fed clean

fed start resolves parameters, starts the database, polls its health check, runs the migration, and starts the API. fed clean removes the demo's managed resources when you are done.

Join a repository that already uses fed

If the repository contains fed.yaml, the normal setup is short:

git clone <repository>
cd <repository>
fed doctor
fed start

In a Git worktree, enable isolation before any other fed command:

fed isolate enable
fed start

Run project tasks through fed, such as fed test:integration. They receive the ports and credentials allocated to the current checkout. Read Worktrees and coding agents before running several copies of a project at once.

Add fed to your project

Create fed.yaml in the project root. This example runs PostgreSQL in Docker and a Node API on the host:

parameters:
  API_PORT: { type: port, default: 8080 }
  DB_PORT: { type: port, default: 5432 }
  DB_PASSWORD: { type: secret }

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

  api:
    process: npm start
    depends_on: [database]
    environment:
      PORT: "{{API_PORT}}"
      DATABASE_URL: "postgres://postgres:{{DB_PASSWORD}}@localhost:{{DB_PORT}}/app"
    healthcheck:
      http_get: 'http://localhost:{{API_PORT}}/health'
    startup_message: "API ready: http://localhost:{{API_PORT}}"

entrypoint: api
fed validate
fed start
fed logs api
fed stop

fed init can generate a starter file. Every host port that may vary must be a type: port parameter. A literal port inside a command or URL cannot be remapped for another worktree.

Use an existing Compose file

You can keep infrastructure in compose.yaml and run the application on the host. Include the file once; fed adds every Compose service and its dependency edges:

compose:
  - ./compose.yaml

services:
  api:
    process: npm run dev
    depends_on: [postgres]

entrypoint: api

Read Use fed with Docker Compose for parameterized ports and isolation limits.

Know what a health check means

fed polls a configured health check before starting dependents. If the service remains alive but the check does not pass before its timeout, fed currently warns and continues with the service in Running state. It does not treat that timeout alone as a failed fed start.

If a CI job needs a hard readiness gate, make the following script or test perform its own final probe. The health-check reference covers the exact behavior.

Choose the next guide

fed --help is the source of truth for the version installed on your machine.

Next: Worktrees and coding agents →