Foundry

Foundry is a local control plane for AI development tools. It provides a CLI-managed web interface for saving model Providers, applying them to installed agent Runtimes, and moving user-owned configuration between Foundry installations.

Foundry currently supports OpenAI Codex and Claude Code. The Dashboard, Skills, MCPs, and Prompts screens are present as placeholders; their management workflows are not connected to the Local Web UI yet.

Requirements

• Node.js 24.18.0 or newer within the Node 24 release line
• pnpm 11.22.0 or newer within the pnpm 11 release line for repository development

Quick Start

Start the latest published Local Web UI without installing Foundry globally:

pnpm dlx @dhzh/foundry@latest ui

Foundry listens only on 127.0.0.1, uses port 54321 by default, and opens the interface in the default browser. Stop it with Ctrl+C.

# Use another port.
pnpm dlx @dhzh/foundry@latest ui --port 61234

# Start without opening a browser.
pnpm dlx @dhzh/foundry@latest ui --no-open

# Show command help or the installed version.
pnpm dlx @dhzh/foundry@latest ui --help
pnpm dlx @dhzh/foundry@latest --version

Running foundry without a subcommand prints help and does not start a server.

Current Capabilities

Providers

A Provider is a saved model-service connection scoped to one Runtime. Foundry can:

• create, edit, copy, list, and soft-delete Codex and Claude Code Providers;
• store Runtime-specific endpoints, API keys, model selections, and optional presentation details;
• test a saved connection against the Provider's model-listing endpoint;
• apply or reapply a Provider directly from its card; and
• prevent deletion while the Provider is assigned to a Runtime.

Codex Providers use the Responses protocol and support a default model, optional review model, and optional API key. Claude Code Providers use the Messages protocol and support authentication-header selection, role models, subagent settings, model capabilities, and selected Claude Code feature flags.

Runtimes

Foundry detects the codex and claude executables from PATH, reads their version, and manages these user-level configuration files:

Before applying a saved Provider or Official Default, Foundry shows the proposed field-level changes. Applying a preview:

• preserves fields outside Foundry's managed field set;
• rejects the apply if the file changed after the preview was created;
• writes through a temporary file and atomically replaces the target;
• keeps the latest configuration backup beside the file with a .foundry-backup suffix; and
• records the selected Provider or Official Default as the Runtime Assignment.

Official Default removes Foundry-managed active selection fields while preserving unrelated configuration, saved Provider tables, and official account credentials. Foundry does not infer Runtime Assignments from configuration files changed outside the application.

Settings

Application Settings currently contain a persisted Color Mode: System, Light, or Dark. The Settings page also owns Foundry data import and export.

Local Web Routes

The Local Web UI uses hash routing, so browser navigation does not require server-side route fallbacks.

The browser title also reports Foundry Server health as Checking..., Healthy, or Unhealthy.

Data Import and Export

The Settings page exports all current Exportable Data as one timestamped .foundry file. The file is a ZIP-backed binary container intended for Foundry rather than manual editing; it is not encrypted.

Provider database IDs, timestamps, and deletion metadata are omitted so the destination database can generate them. Deleted Providers, Runtime Assignments, and other machine-specific operational state are not exported.

Each package contains a manifest with its format, creation time, Foundry version, and per-module path, media type, overwrite policy, byte size, and SHA-256 checksum. Import validates the container and manifest before processing modules. Supported modules are atomic but independent: one module can fail or be unsupported without rolling back another module that imported successfully.

Because Provider API keys are stored in the export, keep .foundry files private and store them securely.

Local Data and Safety

Foundry stores Provider records, Runtime Assignments, and Application Settings in one foundry.sqlite database in the operating system's application-data directory. The directory is resolved with env-paths; on macOS the default database location is ~/Library/Application Support/foundry/foundry.sqlite.

Provider API keys are stored in this local database. Access to the machine and its user account should therefore be treated as access to those credentials.

Database migrations run automatically when the server starts. Before applying pending migrations to an existing database, Foundry creates an online SQLite backup under the adjacent backups/ directory and retains the newest migration backup. A database migrated by a newer or incompatible Foundry version is rejected instead of being silently changed.

The HTTP server is loopback-only and has no remote-listening mode or authentication layer. It should not be exposed through a reverse proxy or port-forwarding setup.

HTTP API

The Local Web UI uses relative /api requests. The server currently exposes:

JSON success and business-result responses use a shared envelope:

{
  "status": "SUCCESS",
  "data": true,
  "message": "Service is healthy."
}

message is optional. Request validation failures use HTTP 400; domain outcomes also carry a machine-readable status such as PROVIDER_NOT_FOUND or RUNTIME_CONFIGURATION_CHANGED. The export endpoint instead returns application/octet-stream with an attachment filename. Import requests are limited to 256 MiB.

The API is an internal local contract shared by the server and Local Web UI. It is not currently documented as a stable remote integration API.

Development

Install dependencies from the repository root:

pnpm install

Start the Hono server on http://127.0.0.1:54321:

pnpm dev:server

In another terminal, start the React app on http://localhost:12345:

pnpm dev:app

Rsbuild proxies /api to the Hono development server. Other useful commands are:

Run the full verification set before release:

pnpm test
pnpm lint
pnpm typecheck
pnpm --filter @dhzh/foundry-app typecheck
pnpm build

Pushing a v* tag triggers separate GitHub Actions workflows that create the GitHub release and publish @dhzh/foundry to npm with provenance.

Repository Layout

• src/cli/ - Citty CLI and the foundry ui command.
• src/server/ - Loopback Hono server, persistence, HTTP handlers, Runtime configuration, static assets, and shutdown lifecycle.
• app/ - Private React, Rsbuild, Tailwind CSS, shadcn/ui, and TanStack Query workspace for the Local Web UI.
• packages/api-contract/ - Private shared runtime constants and TypeScript HTTP contracts; bundled into the published output.
• drizzle/ - Forward-only SQLite migrations bundled with the package.
• test/ - Node-side Vitest coverage for the CLI, server, persistence, and contracts.
• app/test/ - Vitest Browser Mode coverage using Playwright and Chromium.
• docs/adr/ - Architecture decision records for routing, server state, persistence, credentials, Runtime management, and export format.
• docs/design/ and docs/research/ - Detailed feature behavior and supporting technical research.
• src/main/ - Earlier Skill and Prompt subsystem code that is not wired into the current CLI, server, or Local Web UI entrypoints.

The published package contains the CLI, the minimal library entrypoint, bundled migrations, and the built Local Web UI. The private app and API-contract workspaces are not published as separate packages.

Open Source Inspiration

Foundry is inspired by open-source projects that explore better ways to manage local AI development tools:

• CC Switch - Inspiration for Provider management and local agent Runtime configuration workflows.

License

Foundry is licensed under the Apache License 2.0.