Quick Start

This walks through a first run end-to-end: install the CLI, initialize a platform, inspect what was generated, and start services locally. Every step reflects what the CLI actually does today.

1. Install

Install the Foundry CLI (see Installation) and verify:

foundry --help

2. Initialize a platform

foundry init

foundry init detects the directory state. In a fresh directory it launches an interactive wizard: it scans the filesystem for existing components, offers to add them to the manifest, and prompts for the cloud provider and IaC tool. It then writes:

• foundry.json — the platform manifest (schemaVersion 0.5.0)
• .foundry/ — workspace config, including workspace.yml
• .gitignore — legacy blanket .foundry/ ignores are removed (only config.yml is gitignored, via a nested .foundry/.gitignore)

Discovered backends are scaffolded with deploy.strategy: "service", frontends with "static", and packages get no deploy block. Adjust any of this in foundry.json afterward.

3. Review the manifest

A v0.5.0+ service groups its concerns into structured blocks — scope, stack, and deploy:

{
  "$schema": "https://raw.githubusercontent.com/FoundryMedia/foundry/release/foundry.schema.json",
  "schemaVersion": "0.5.0",
  "name": "my-platform",
  "repository": "my-platform",
  "ci": { "iac": "opentofu", "iacDir": "ci/iac", "provider": "aws" },
  "services": {
    "api": {
      "scope": "internal",
      "stack": { "type": "backend", "framework": "spring-boot" },
      "deploy": { "strategy": "service" }
    },
    "web": {
      "scope": "public",
      "stack": { "type": "frontend", "framework": "nextjs" },
      "deploy": { "strategy": "static" }
    }
  }
}

See Services for every field and Deploy Strategies for the strategy enum.

4. Sync the workspace

After editing the manifest or moving directories, reconcile intent (manifest) against reality (filesystem):

foundry sync

This rewrites .foundry/workspace.yml — a path map of where each service actually lives — and reports drift (undeclared directories, missing services, framework mismatches). See foundry sync.

5. Run locally

foundry run dev

run dev launches every enabled service (and its sidecars) in a unified Services UI. Filter to a subset with --filter, and run database migrations first with --migrate-db:

foundry run dev --filter api,web
foundry run dev --migrate-db

Multi-repo note

A service that lives in a different repository declares repository (owner/repo) and an optional path. Omit both and the service is treated as monorepo (apps/{type}/{name}). In practice the central multi-repo manifest lives in foundry-ops/platform.json. See Multi-repo: repository & path.