Getting Started

This guide walks you through setting up and running the full local federation stack for the first time.

Prerequisites

Before starting, ensure the following are installed and running:

Tool	Minimum Version	Install
Docker Desktop	29.x+ (with Compose v5)	brew install --cask docker
Docker Compose	v5.0+ (plugin, not standalone)	Bundled with Docker Desktop
Node.js	22.4.1+ (see per-repo)	fnm install <version>
fnm or nvm	Any	brew install fnm
Yarn	1.22.x	npm install -g yarn
Python 3	3.x	Pre-installed on macOS (Xcode CLT)
Git	2.x+	Bundled with Xcode CLT
envsubst	Any	brew install gettext

Docker Desktop Must Be Running

The fed CLI runs preflight checks before starting any services. If Docker Desktop is not running, it will exit immediately. Start it with open -a Docker or launch from Applications.

Clone the Repositories

From the cred-local-workspace root, clone the service repos:

git clone git@github.com:credinvest/cred-api-commercial.git
git clone git@github.com:credinvest/cred-model-api.git
git clone git@github.com:credinvest/cred-filter-api.git
git clone git@github.com:credinvest/cred-agent-ai.git
git clone git@github.com:credinvest/cred-mcp.git

Optional (not part of federation):

git clone git@github.com:credinvest/cred-web-commercial.git
git clone git@github.com:credinvest/cred-ios-commercial.git

Note

cred-auth and cred-wiki are not part of the local federation stack. Clone them separately only if working on auth or documentation.

Workspace Layout

The default layout is flat -- repos as direct children of the workspace root:

cred-local-workspace/
├── fed                         # CLI entrypoint
├── fed.toml                    # Stack configuration
├── cred-api-commercial/
├── cred-model-api/
├── cred-filter-api/
├── cred-agent-ai/
├── cred-mcp/
├── cred-web-commercial/        # Optional
└── cred-ios-commercial/        # Optional

If your layout differs (for example, repos grouped under api/, web/, mobile/), create a .local-workspace.env file at the workspace root with path overrides:

# Example: grouped layout
COMMERCIAL_API_DIR=api/cred-api-commercial
MODEL_API_DIR=api/cred-model-api
FILTER_API_DIR=api/cred-filter-api
AGENT_AI_DIR=api/cred-agent-ai
MCP_DIR=api/cred-mcp/graphql-mcp-server

Copy from .local-workspace.env.example as a starting point. If using the flat layout, you do not need this file.

Set Up Environment Files

Each backend service needs a .env file. These are gitignored and must be created manually.

File	Required?	Key Contents
cred-api-commercial/.env	Yes	JWT_SECRET, CRED_MODEL_API_TOKEN, DATABASE_URL, REDISCLOUD_URL
cred-model-api/.env	Yes	MODEL_API_DATABASE_URL, API_TOKEN, ES_CLOUD_ID, ES_API_KEY
cred-filter-api/.env	Only if running filter-api	COMMERCIAL_JWT_SECRET, COMMERCIAL_API_DATABASE_URL, ES credentials
cred-agent-ai/.env	Only if running agent-ai	JWT_SECRET, ANTHROPIC_API_KEY, DATABASE_URL
cred-mcp/graphql-mcp-server/.env	Only if running MCP	APOLLO_MCP_ENDPOINT, APOLLO_GRAPH_REF, APOLLO_KEY

How to get the values:

1. Pull from Cloud Run (recommended): cd cred-api-commercial && ./source-cloudrun-variables.sh (requires gcloud auth login)
2. Copy from .env.example in each repo and fill in values (ask a team lead for secrets)
3. Pull manually via gcloud:

   gcloud run services describe cred-api-commercial-dev \
     --region us-central1 \
     --format 'yaml(spec.template.spec.containers[0].env)'
   

PgBouncer search_path workaround

The model-api .env must include KNEX_SEARCH_PATH=public,credentity,pg_catalog for local dev. Without this, queries through PgBouncer intermittently fail with relation "X" does not exist. See the Troubleshooting page for details.

Verify Shared Secrets

The fed CLI injects secrets across services automatically, but the base values must exist in the commercial API's .env:

• JWT_SECRET -- the JWT HMAC key shared across all services
• CRED_MODEL_API_TOKEN -- must match API_TOKEN in the model-api .env

First Run

Start the full federation stack:

./fed start

On first run, the fed script bootstraps a Python virtual environment at federation/.venv and installs its dependencies. Then it runs:

1. Preflight checks -- Docker running, directories exist, .env files present, required keys set
2. Service startup -- in dependency order with health checks between each service
3. Database bootstrap -- FDW setup, migrations, seeding, credentity bootstrap

The first startup takes 5-10 minutes due to Docker image builds and database initialization. Subsequent runs are faster because the fed CLI skips tasks that have already completed (using skip_check idempotency guards).

Common Flags

Flag	Effect
--skip <service>	Skip an optional service. Use multiple times: --skip filter-api --skip agent-ai
--only <service>	Start only a specific service plus its transitive dependencies
--clean	Tear down containers and anonymous volumes first (fixes stale node_modules)
-v	Verbose output -- shows detailed health check polling and environment resolution

Examples:

# Skip optional services for faster startup
./fed start --skip filter-api --skip mcp --skip agent-ai

# Start only commercial-api (also starts model-api as a dependency)
./fed start --only commercial-api

# Full clean restart (removes volumes -- forces re-bootstrap)
./fed start --clean

Verify the Stack

Check the health of all services:

./fed status

You can also verify individual services with curl:

# Apollo Router (federated endpoint)
curl -s http://localhost:4000/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ __typename }"}' | jq .

# Commercial API (direct)
curl -s http://localhost:8000/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ __typename }"}' | jq .

# Model API (direct)
curl -s http://localhost:3000/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ __typename }"}' | jq .

View Logs

Tail logs across all services:

./fed logs

Dump current logs to the run-output/ directory:

./fed logs --dump

Client Codegen After Startup

Once the stack is running, regenerate client-side types for frontends:

Web Frontend

cd cred-web-commercial
bun run gql:local       # Regenerate types against local router
bun run dev:local       # Start dev server pointing at localhost:4000

iOS App

cd cred-ios-commercial
./cred graphql sync local    # Regenerate types against local router
./cred build                 # Build with DebugLocal scheme (localhost)

Stopping the Stack

Stop all services in reverse dependency order:

./fed stop

This runs docker compose down on each service. Database data persists across restarts (unless you use --clean on the next start).

Quick Reference

Task	Command
Start full stack	./fed start
Start minimal stack	./fed start --skip filter-api --skip mcp --skip agent-ai
Start single service	./fed start --only commercial-api
Clean restart	./fed start --clean
Check health	./fed status
View logs	./fed logs
Stop all services	./fed stop
Verbose mode	./fed -v start