@dhzh/foundry

An AI-native local developer runtime for tools, skills, agents, and workflows.

Foundry is distributed as a CLI package. It starts a local Hono server and serves the bundled React Web UI from dist/web/.

The Web UI is built with Astryx and provides the local Foundry administration shell, including the Settings surface.

Requirements

• Node.js ^24.18.0
• pnpm ^11.9.0

Setup

pnpm install

Development

Start both the CLI API server and the Rsbuild Web UI:

pnpm run dev

This runs both development processes. The CLI listens on http://127.0.0.1:7777 and provides the API only. The Rsbuild Web UI opens at http://localhost:3000; its /api/* requests are proxied to the CLI without changing the request path. Press Ctrl-C to stop both processes.

The individual processes are also available when needed:

pnpm run dev:cli
pnpm run dev:web

dev:cli sets FOUNDRY_DEV=true, so it only serves the API and does not require Web UI assets. dev:web provides the Web UI and proxies API requests to the CLI development server. To serve the Web UI from the CLI instead, build the package and run the production executable.

Commands

Run these commands from the repository root:

pnpm run build          # Build the CLI and Web UI
pnpm run build:cli      # Build only dist/cli/
pnpm run build:web      # Build only dist/web/
pnpm run dev             # Run the CLI API and Web UI development servers
pnpm run dev:cli        # Run the CLI from source in watch mode
pnpm run dev:web        # Start the Rsbuild Web UI development server
pnpm run lint           # Run ESLint

Run A Production Build

Build the package and launch the executable wrapper:

pnpm run build
node bin/index.js

To use the published package without cloning the repository:

pnpm dlx @dhzh/foundry

The foundry executable listens on 127.0.0.1:7777 and prints a clickable local URL when it starts.

Settings

The Settings capability is available through the Web UI and the module-level CLI command:

Current registered settings are ui.theme and ui.pointer.

foundry settings list
foundry settings get ui.theme
foundry settings set ui.theme dark
foundry settings reset ui.theme

Use --raw when only command values or boolean mutation results are needed. The installable foundry-settings Skill is the automation wrapper for this CLI surface.

Web UI

The private web workspace uses:

• Rsbuild 2
• React 19
• React Compiler through @rsbuild/plugin-react
• Astryx components and the neutral theme
• TypeScript with bundler module resolution

The Web entrypoint is packages/web/src/index.tsx, which imports the global Astryx reset and theme styles from packages/web/src/index.css. The root component lives in packages/web/src/app.tsx.

Rsbuild is configured in packages/web/rsbuild.config.ts. Production assets are written directly to the repository-level dist/web/ directory so the CLI can serve them next to its bundled output.

Project Layout

Path	Role
specs/plans/	Numbered implementation plan directories and task conventions
src/cli/	CLI entrypoint, environment configuration, and Hono API/static server
src/cli/env.ts	Development environment flags used by the CLI server
src/modules/settings/	Settings registry, repository, service, routes, and CLI command
skills/foundry-settings/	Installable Skill wrapping the Settings CLI command
packages/web/	Rsbuild + React Web UI workspace
packages/web/src/index.tsx	Browser entrypoint
packages/web/src/app.tsx	Root React component
packages/web/src/index.css	Astryx reset and theme imports
packages/web/rsbuild.config.ts	React Compiler and Web build configuration
bin/index.js	Published foundry executable wrapper
dist/cli/	Bundled CLI output generated by tsdown
dist/web/	Web UI production output served by the CLI

Implementation Plans

See specs/plans/README.md for the canonical plan location, naming, numbering, and content conventions.

Learn More

• Rsbuild documentation
• Rspack documentation
• Run pnpm exec astryx docs for Astryx component and token guidance
• Repository guidelines for agents