PromptForge

A runtime that executes AI prompt pipelines defined in a single markdown file. The markdown is the program, the model is the CPU. YAML frontmatter for metadata, embedded Lua for logic, prose blocks for model instructions, and a credential-holding gateway that keeps vendor keys off the prompt process. Write a prompt, run it, get a result.

What you get

• 📄 Markdown prompts - frontmatter, one H1, H2 sections that run top to bottom
• 🔧 Lua control - bind tools and models, compute values, write the store, fan out work
• 🌐 Tools that ship - local web_fetch, gateway-backed web_search, semantic capability binding
• 🔌 Inference gateway - OpenAI-shaped chat, bearer auth, catalog at GET /v1/models
• 🛰️ MCP server - run prompts from an agentic harness over streamable HTTP or stdio

Quick example

---
name: greet
description: Greet the named input using a Lua-computed value
promptforge: 1
---

# Greet

```lua
models.default("writer", "A model suited for careful analysis, coding, and general assistance")
```

## Main

```lua
var.greeting = "Hello, " .. args .. "!"
```

Repeat exactly, with no extra words: {{ var.greeting }}

Prose goes to the model. Lua sets up the turn. The response is the run's result.

Quick start

cargo install promptforge-cli promptforge-gateway
promptforge-gateway serve gateway.toml --profile main &
promptforge run prompts/hello.md

Two processes: the gateway holds the vendor credential; the client points at it.

export ANTHROPIC_API_KEY=sk-ant-...
export PROMPTFORGE_GATEWAY_API_KEY=dev-secret
cargo run -p promptforge-gateway -- serve gateway.toml --profile main &

export PROMPTFORGE_GATEWAY_URL=http://127.0.0.1:8081/v1
cargo run -p promptforge-cli -- run prompts/hello.md

Interactive prompt work against an already-running gateway:

cargo run -p promptforge-dev -- prompts/greet.md "world" --watch

Build from source

Every build needs Rust 1.89 or later and Node.js 22. The two web UIs are bundled with esbuild during the Cargo build, so run npm ci once in each ui/ folder after cloning:

git clone git@github.com:cppalliance/promptforge.git
cd promptforge
npm ci --prefix crates/promptforge-workshop-server/ui
npm ci --prefix crates/promptforge-gateway-config-ui/ui

cargo build builds the gateway, the default workspace member. cargo build -p promptforge-workshop builds the desktop app. See the promptforge-gateway README for the feature details.

Ubuntu 22.04

sudo apt install build-essential pkg-config cmake clang libclang-dev
# only for the desktop app (promptforge-workshop):
sudo apt install libwebkit2gtk-4.1-dev libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev

cargo build
cargo build -p promptforge-workshop --no-default-features

macOS

xcode-select --install
brew install cmake node

cargo build
cargo build -p promptforge-workshop --no-default-features

Windows

Install Visual Studio with the "Desktop development with C++" workload, CMake, and Node.js 22. The CUDA toolkit is needed only for the whisper CUDA feature, which the workshop enables by default on Windows.

cargo build
cargo build -p promptforge-workshop

On a machine without the CUDA toolkit, build the desktop app with --no-default-features: speech-to-text then uses its CPU backend and local inference keeps the managed llama-server download.

The first build downloads the tool picker's embedding model (~130MB from Hugging Face, pinned and checksummed). Later builds reuse the cache.

How it works

Parse a promptforge markdown file, bind the tools and models it needs, then execute each H2 section in order. Section Lua prepares state; prose becomes a model turn (with a tool loop when tools are in scope); results land in the store or become the run output.

flowchart LR
  MD[Markdown prompt] --> Parse[Parse and bind]
  Parse --> Sec[H2 sections]
  Sec --> Lua[Lua blocks]
  Lua --> Model[Model turn]
  Model --> Tools[Tools via gateway or local]
  Model --> Store[Store artifacts]
  Store --> Out[Run result]

Loading

Crates

Crate	Description	crates.io
promptforge-core	Parser, executor, Lua runtime, store, gateway client
promptforge-core-support	Shared host-support primitives: untrusted guards, cooperative cancellation, run observation
promptforge-cli	promptforge run command-line binary
promptforge-gateway	Inference gateway with model catalog and credential isolation
llama-cuda-build	Command-line builder of the CUDA llama-server release zip; runs on the GitHub build machine	not published
promptforge-model-client	Gateway model client: OpenAI-shaped completions transport, wire types, model catalog and binding vocabulary
promptforge-gateway-local	Gateway-owned local inference: GGUF provisioning, artifact store, managed llama-server lifecycle
promptforge-gateway-protocol	OpenAI wire protocol and upstream abstraction for the gateway
promptforge-gateway-routing	Routing vocabulary for the gateway: Model/Endpoint table entries and dominion admission queues
promptforge-lua	Sandboxed Lua runtime: the section VM, coroutine protocol, and host surface
promptforge-mcp-server	MCP server for agentic harnesses (Cursor, Claude Code)
promptforge-parser	Prompt document parser: frontmatter, section tree, exact lua fence splitting, ParseError vocabulary
promptforge-progress	Progress vocabulary: operation-scoped weighted trees, process hub, coalesced events, remote import	not published
promptforge-stt	Gateway-owned STT runtime: artifact provisioning, engine lifecycle, /voice, and OpenAI transcription	not published
promptforge-store	Run-scoped virtual filesystem: Store backend contract, MemStore/FileStore backends, shared StoreRef handle
promptforge-tool-picker	Semantic tool resolution via sentence embeddings
promptforge-tools	Runtime-agnostic tool contract: Tool, ToolCatalog, ToolId
promptforge-webfetch	SSRF-safe web fetch tool for model-supplied URLs
promptforge-web-search	Web search tool proxying through the gateway with credential isolation
promptforge-web-search-service	Gateway-side web-search service: Brave provider client, request validation, result post-processing
promptforge-dev	Interactive prompt development with watch mode
promptforge-transcribe	Whisper transcription engine: inference workers, segmentation, silence gating	not published
workshop-agent	Workshop agent-program executor: run_agent drives .lua agent programs over the promptforge substrate	not published
promptforge-workshop-server	Workshop HTTP server: agent sessions, model catalog passthrough, workspace API, and UI assets	not published
promptforge-workshop	Workshop desktop app (Tauri): boots the gateway and opens the window	not published

Documentation

• PromptForge User Guide - full documentation
• User Guide - progressive tutorial for writing prompts
• design-core.md - core design notes

Build the guide locally with mdbook build guide.

Minimum Rust Version

Rust 1.89 or later.

Contributing

Build, format, and test before you open a PR. CI runs cargo fmt --check, clippy -D warnings, and cargo test --workspace.

License

Distributed under the Boost Software License 1.0.