formio/uag repository overview

⁠Form.io Universal Agent Gateway (UAG)

The UAG is a server that sits in front of one Form.io⁠ project and lets AI agents work with its forms. It turns each form tagged uag into context a model can use, validates every value an agent sends with the form's own rules, and forwards every write to Form.io with the caller's own permissions.

Also published as @formio/uag⁠ on npm and listed in the official MCP Registry⁠ as io.form/formio-uag.

⁠What it enables

Conversation to a validated submission. An agent collects data through natural language and produces a deterministic, schema-valid Form.io submission — no bespoke parsing, and the form's own validation still applies.

Agentic workflows. Applications send submissions to the UAG instead of the Form.io project URL. The UAG forwards each one to Form.io, which saves it and runs the form's own actions, and an Agent: Run task action on the form runs one of its tasks before or after the save: review steps, enrichment, triage, and similar automation driven by a form submission. A task's results are saved as an update through the UAG, which can start the next task.

⁠Quick start

Against a Form.io Open Source server:

docker run -d --name formio-uag -p 3200:3200 \
  -e PROJECT=https://forms.example.com \
  -e ADMIN_KEY=your-admin-key \
  -e JWT_SECRET=your-jwt-secret \
  -e LOGIN_FORM=https://forms.example.com/user/login \
  --restart unless-stopped \
  formio/uag

Against a project on Form.io's hosted service, use PROJECT_KEY in place of ADMIN_KEY, and set no license:

docker run -d --name formio-uag -p 3200:3200 \
  -e PROJECT=https://myproject.form.io \
  -e PROJECT_KEY=your-project-api-key \
  -e JWT_SECRET=your-jwt-secret \
  --restart unless-stopped \
  formio/uag

Against a self-hosted Form.io Enterprise project, add a Form.io license that includes the UAG, in LICENSE_KEY, whose endpoint allowlist includes PROJECT's host; for an offline license, also set LICENSE_REMOTE=true:

docker run -d --name formio-uag -p 3200:3200 \
  -e PROJECT=https://forms.example.com/myproject \
  -e PROJECT_KEY=your-project-api-key \
  -e LICENSE_KEY=your-license \
  -e JWT_SECRET=your-jwt-secret \
  --restart unless-stopped \
  formio/uag

Docker Compose is the recommended path for anything beyond a single container. The README's Quickstart⁠ runs the UAG beside a Form.io Open Source server in one Compose file. The repository's custom module sample⁠ is a fuller stack to start from: Form.io Open Source, MongoDB and the UAG with a module of its own, and the engine setups⁠ add engines to a stack like it.

⁠Connecting an agent

The MCP endpoint is http://<host>:<port>/mcp, served over Streamable HTTP (default port 3200).

A local client (your own server, or a script) exchanges ADMIN_KEY or PROJECT_KEY for a token at /auth/token with the client_credentials grant, which needs no other setting. Remote clients that connect in, such as claude.ai and Claude Desktop connectors, sign in through OAuth: they need the UAG public over HTTPS, MCP_OAUTH=true and MONGO, which needs a license that includes the UAG. Behind a reverse proxy, set TRUST_PROXY so the OAuth discovery documents name the public URL, or set BASE_URL.

Engine servers (formio/uag-engines) run their own MCP client and connect outward to the UAG for research, so the UAG does not need to be publicly reachable for them — only reachable from the engine server, such as over a private Docker network.

⁠Agent API and engines

Besides MCP, the UAG serves an HTTP Agent API for a form's tasks: POST {form}/agent/extract, {form}/agent/decide and {form}/agent/generate, under the form's URL on the UAG (for example https://uag.example.com/supportrequest/agent/decide), which read no stored submission, save nothing and take the same credentials as the form's submissions; and GET /agent/capabilities at the UAG's root, which lists the enabled engines. The operations, and the Run task action, need an engine; with none enabled the operations return 503. The image bundles the official engines, and UAG_ENGINES names the ones to enable:

With the quick-start settings in an uag.env file (on a self-hosted project, with a LICENSE_KEY that includes the UAG):

docker run -d --name formio-uag -p 3200:3200 \
  --env-file uag.env \
  -e UAG_ENGINES=jev,claude \
  -e TYPESAFE_API_KEY=your-typesafe-key \
  -e CLAUDE_API_KEY=your-claude-key \
  formio/uag

The Agent API and Run task are Agentic Formflow. A project on Form.io's hosted service runs it with real engines and no license. On a self-hosted project, Open Source or Enterprise, real engines need a license in LICENSE_KEY that includes the UAG for the project's endpoint: an online license whose key has the uagServer scope, or an offline license with the uag option (with LICENSE_REMOTE=true). UAG_LICENSE still works, but is deprecated. Conversation forms need no license, and run on Form.io Open Source: the MCP tools, and a form's chat ({form}/agent/chat, which Formio.createChat in @formio/uag-js embeds in a page) with any agent engine. The stub engines (stub-decision, stub-agent) run without one, for trying the API out. Unlicensed requests answer 403 with code: "license_required", and GET /agent/capabilities reports the edition and formflow.reason. See the licensing documentation⁠.

Callers send the signed-in user's Form.io token (x-jwt-token), a portal team member's remote token (x-remote-token) or a UAG bearer token, and Form.io's permissions apply; servers may send x-token / x-admin-key instead, which are refused from browsers. A form that sets uagAnonymous: "true" and lets Anonymous create submissions also answers visitors with no credential, within the anonymous rate limits. jev and claude send submission data to their provider's hosted API. Field properties, routing and the Run task action are covered in the Agent API⁠ and Workflows⁠ documentation.

⁠Configuration

To customize the image, mount a module⁠ at /app/module (forms, MCP tools, actions, settings), and folders of plugins⁠ under /app/plugins, each with an index.mjs (-v ./my-plugins:/app/plugins/my-plugins:ro; or name a file or folder with UAG_PLUGINS; off loads none), for converters and other plugins. Add-ons such as formio/uag-documents fill such a folder through a volume. Full list of variables: https://github.com/formio/uag/blob/main/demo/content/developers/deployment.md#environment-variables⁠.

Treat every key, secret, and license as sensitive: supply them through an .env file or your platform's secret store rather than inline in a committed file.

⁠Caching behaviour worth knowing

Forms and resources are cached and refreshed on the PROJECT_TTL interval, so a change to a form can take up to that long to appear to an agent. Set PROJECT_TTL=0 to disable refreshing entirely, in which case a restart is the only way to pick up changes.

⁠Links

• Documentation: https://github.com/formio/uag/blob/main/demo/content/developers/index.md⁠ · Source: https://github.com/formio/uag⁠
• Demos of conversation forms, agentic workflows and Agentic Formflow (source): https://github.com/formio/uag/tree/main/demo⁠
• Engine server image, for running engines in their own container: https://hub.docker.com/r/formio/uag-engines⁠
• AI Document add-on, which runs beside this image and fills its plugins folder with the AI Document module and the document extras of @formio/uag-extras: https://hub.docker.com/r/formio/uag-documents⁠ (formio/uag-documents:2, whose major version is the UAG's); see https://github.com/formio/uag/blob/main/demo/content/developers/ai-document.md#run-it-with-docker⁠. Its Docker Hub page has the deployment kit, a Compose file and .env template that run both, served from the package at https://cdn.jsdelivr.net/npm/@formio/uag-extras@2/deploy/docker-compose.yml⁠
• MCP server for building and managing Form.io forms from a coding agent: https://hub.docker.com/r/formio/mcp⁠
• Agentic Coding Plugin, so your coding agent can tag forms, deploy the UAG and wire applications to it: https://github.com/formio/ai⁠ (npx skills add formio/ai)
• License: MIT