Server
pip install -e ".[server]", then wireforge serve --workspace <dir> [--host 127.0.0.1] [--port 8000] [--token T].
Every subdirectory of the workspace with a project.yaml is a project; its id is the directory name. The OpenAPI
document is served at /openapi.json (wireforge serve --workspace <dir> --openapi openapi.json writes it); the UI
types are generated from it. Code: wireforge.server (storage.py, app.py).
Storage
- The files are the single source of truth and stay git-friendly: the server keeps no copy, every request reads the
files, so edits made by hand, by
git checkoutor by the CLI are visible immediately. - Entry and value edits go through the service layer (
wireforge.service): comments, styles and the canonical layout are kept, so GUI edits produce minimal diffs (docs/CLI.md). - Optimistic locking: every file has an ETag (sha256 of its bytes) and every project an ETag over all its files.
File writes need
If-Match: <file ETag>(*creates a new file); entry/value edits needIf-Match: <project ETag>. A missingIf-Matchis428, a stale one412(reload and retry). Writes of one project are serialized by a lock, so of several concurrent writers with the same ETag exactly one wins. - External changes:
GET /api/projects/{id}/wait?etag=E&timeout=Slong-polls until the project ETag differs fromE(200with the new ETags) or the timeout passes (304); clients reload the changed files. - Authentication: with
--token Tevery/apiroute except/api/healthneedsAuthorization: Bearer T(401otherwise). With--oidc-issuer/--oidc-audienceit needs a JWT of that issuer instead (signature from the issuer's JWKS,iss,aud,exp/nbfwith 60 s skew;401otherwise,503when the issuer cannot be reached); thesubandemailclaims live only for the request and are never stored. The JWKS is cached in memory for--oidc-jwks-cache-seconds(default 3600). See Deployment and operation for the limits.
Routes
| Route | Meaning | CLI equivalent |
|---|---|---|
GET /api/projects, POST /api/projects |
list projects / create a project, empty or from a template |
ls, wireforge init |
GET /api/templates |
the templates and published protocols a new project can start from (kind) |
wireforge init --list |
GET /api/projects/{id} |
entries per section, files, ETags, validation result | wireforge validate |
GET /api/projects/{id}/state, GET .../wait |
ETags; wait for a change | - |
POST /api/projects/{id}/validate |
validation result | wireforge validate |
GET/PUT /api/projects/{id}/files/{path} |
read/replace a file (text + ETag) | editor |
GET/PUT/DELETE /api/projects/{id}/entries/{section}/{name} |
read/create-or-update/delete an entry | wireforge get/upsert/remove |
GET/PUT/DELETE /api/projects/{id}/value?pointer=P |
read/set/delete any element | wireforge get/set/remove |
GET /api/projects/{id}/generate[?tests=false][&language=c] |
zip of the generated C++ (or C99) code (see below) | wireforge generate --tests [--language c] |
GET /api/projects/{id}/preview[?language=c] |
generated C++ (or C99) files as text (nothing written) | wireforge generate [--language c] |
GET /api/projects/{id}/analyze?profile=P&export=markdown\|csv\|json |
layout report (data) and ICD export (text) | wireforge analyze |
POST /api/projects/{id}/requirements/import |
take a baseline of high-level requirements (JSON with the base64 file; needs If-Match) |
wireforge reqs-import |
POST /api/projects/{id}/requirements/lock |
number the low-level requirements (needs If-Match) |
wireforge reqs-lock |
GET /api/projects/{id}/docs |
the requirements, design, test and traceability documents as a zip (?strict=true fails like wireforge docs --strict) |
wireforge docs |
GET /api/projects/{id}/wireshark |
the Wireshark Lua dissector plugin (<project>.lua) |
wireforge wireshark |
POST /api/compat {old, new, interfaces?} |
compatibility of two projects of the workspace | wireforge compat |
POST /api/projects/{id}/encode {message, value, interface?, profile?} |
payload and frame as hex | wireforge encode |
POST /api/projects/{id}/decode {hex, message? \| interface, profile?} |
decoded payload or frame | wireforge decode |
GET /api/projects/{id}/history |
git commits that changed the project | git log |
POST /api/projects/{id}/compat {revision, interfaces?} |
the project at a git revision vs the working copy | wireforge compat |
Edit bodies accept dry_run (return the diff, write nothing) and strict (refuse results with validation errors).
Responses carry the service Result (ok, issues, data, text) plus the new etag.
Downloaded code
The zip of generate is self-contained: <project>/include/<project>/ (generated headers, or with language=c the
C99 sources and headers, and, unless tests=false, generated_tests/), <project>/runtime/include/wireforge/ (the runtime), <project>/model/ (the
project definition with its user_includes directories) and a README. The CMake paths of the test project are
relative inside the zip, so cmake -S include/<project>/generated_tests -B build && cmake --build build && ctest
--test-dir build works after unpacking; quality/run_generated_tests.sh does exactly that for example 02.
Custom checksums: the reference codec (golden vectors, playground) loads the project's plugins/*.py file that defines
PLUGINS. The server runs that Python code, so it must only serve workspaces whose content is trusted.
Deployment and operation
The server is a team tool for a trusted network, not a hardened multi-tenant service. Before exposing it:
- Bind address.
wireforge servelistens on127.0.0.1by default. The Docker image listens on0.0.0.0without a token; anyone who reaches the port can read and change every project. Outside a single-user machine start it with a token:docker run -p 8000:8000 -v "$PWD/projects:/workspace" wireforge wireforge serve --workspace /workspace --host 0.0.0.0 --token "$WIREFORGE_TOKEN". - Shared token or OIDC, no roles.
--tokenis a single bearer secret compared in constant time; rotate it by restarting the server with a new value.--oidc-issuer URL --oidc-audience Ainstead requires a JWT signed by that issuer (pip install "wireforge[server,oidc]"). The two options exclude each other. Either way there are no roles, per-project permissions or audit log (git history is the audit trail): every authenticated caller may read and write every project. - TLS. The server speaks plain HTTP. Put it behind a reverse proxy that terminates TLS and limits request sizes (imports and file writes carry whole documents).
- Token in the UI URL. The web UI reads the token from
?token=<T>, so it can end up in browser history and proxy logs; prefer a proxy that adds theAuthorizationheader, or treat the token as low value and rotate it. - What the API can write. File writes are limited to
.yaml/.ymlfiles inside a project directory (paths that leave it, including through symbolic links, are refused); include directories and headers must be relative without... The API cannot create Python files. - Code that runs on the server. Custom checksum plugins (
plugins/*.py) are imported by the reference codec (encode, decode, playground, golden vectors). They can only come from the file system, so whoever may write the workspace directory (volume, git checkout) may run code in the server process: give that access only to trusted people. - Code that runs in your build. A custom checksum's C++ implementation (
impl,include) anduser_includesheaders are compiled into the generated code and its tests. Review them like any other source in the repository. - MCP server.
wireforge mcptalks over stdio to one local client;run_testsconfigures, builds and runs the generated test project with the local toolchain. Point it only at trusted workspaces (docs/MCP.md). - Importers. Excel files are parsed with openpyxl; for files from outside the team, install
defusedxmlas openpyxl recommends. - Backups and history. The server keeps no state of its own and does not commit: the workspace directory is everything. Keep it in git and back it up like any repository.