<!-- Source: https://console.uubright.com/docs/plugins/ -->
# Plugin settings, secrets and forms

A plugin enabled in a [workspace](https://console.uubright.com/docs/workspaces/) can declare its settings, its
secrets and its MCP servers in a small manifest. uuBright Console then shows a
settings page for it, keeps its secrets write-only, runs its servers for the
agent, and shows the forms those servers ask you to fill in. None of this needs
a change to uuBright Console itself. Plugins without the manifest load exactly
as before.

## The manifest

The manifest is `.claude-plugin/uubright.json`, next to Claude Code's
`plugin.json`. It is a separate file, so the plugin still loads in plain Claude
Code.

```json
{
  "contract": 1,
  "name": "hello",
  "servers": {
    "hello": {
      "command": "node",
      "args": ["${PLUGIN_ROOT}/server.mjs"],
      "env": { "HELLO_GREETING": "${config.greeting}" },
      "secrets": ["api_key"]
    }
  },
  "config": {
    "fields": {
      "greeting": { "type": "string", "title": "Greeting", "default": "Hi", "maxLength": 40 },
      "max_usd": { "type": "number", "title": "Most a job may cost (USD)", "minimum": 0, "maximum": 100, "default": 10 },
      "api_key": { "type": "string", "title": "Hello API key", "secret": true, "pattern": "^hk_[A-Za-z0-9]{32}$" }
    }
  }
}
```

- **`contract`** is the contract version. This console supports `1`. A plugin
  that needs a version this console doesn't know is refused by `enable-plugin`
  with the reason ("hello needs plugin contract 2; this console supports 1.
  Update uuBright Console."). An enabled plugin that moves to an unknown version
  is skipped when a task starts, with the same reason in the task's feed.
- **`name`** must equal `plugin.json`'s `name`. Unknown top-level keys are
  refused so that typos fail loudly. Keys that start with `x-` are the plugin's
  own.
- **`servers.<id>`** is an MCP server the console runs for the agent: `command`,
  `args`, `env`, `cwd` (`workspace`, the default, or `plugin`), `secrets` and
  `timeoutSeconds`. `${PLUGIN_ROOT}` and `${config.<field>}` are filled in.
  Numbers and switches are written as text (`10`, `true`), multi-selects as a
  comma-separated list. A secret field may appear **only** in `secrets`: in
  `command`, `args` or `env` it is refused. HTTP servers (`url`, `headers`) are
  not supported in this version.
- **`config.fields`** uses the same field types as forms (below), plus `secret`,
  `pattern` (a regular expression checked on save) and `restart: "task"`.
  `config.scope` is `workspace` (the default) or `host`, which shares one set of
  values among the workspaces that enable the plugin.
- **`starters`** are the plugin's cards on New chat (below).
- **`auth`**, **`views`** and **`agents`** are accepted but not used yet;
  settings say so.

## Starters

`starters` lists the cards a plugin adds to [New chat](https://console.uubright.com/docs/chat-mode/#new-chat)
and to the New task form. Without it, each of the plugin's `commands/*.md`
becomes a card, as before; with it, only these cards show.

```json
"starters": [
  {
    "id": "short",
    "title": "Make a Short",
    "description": "A beat script and storyboard for a 60-second video.",
    "prompt": "A Short on {topic}, {seconds} seconds.",
    "form": {
      "type": "object",
      "required": ["topic"],
      "properties": {
        "topic": { "type": "string", "title": "Topic", "maxLength": 300 },
        "seconds": { "type": "string", "title": "Length", "enum": ["30", "60"], "default": "60" }
      }
    },
    "image": "art/short.png",
    "accent": "#e8734a",
    "icon": "🎬"
  }
]
```

- **`id`** (letters, digits, `-`, `_`), **`title`** (at most 80 characters) and
  **`prompt`** are required. **`description`** is shown in two lines on the card.
- **`form`** uses the [form field types](#forms). Choosing the card opens the
  form; the answers fill the prompt's `{field}` placeholders as plain text, once,
  so an answer that contains `{other}` stays as typed. Every placeholder must be
  a field of the form. Without a form, the prompt goes into the message box as
  written.
- **`command`** names one of the plugin's `commands/*.md`. The filled prompt is
  then its arguments: `/plugin:command <prompt>` for Claude Code, and the
  command's text with `$ARGUMENTS` replaced for Codex.
- **`image`** is a picture for the top of the card, shown at 16:9 on a computer and
  as a small 16:10 thumbnail on a phone, cropped to fill: a path inside the
  plugin to a PNG, WebP, JPEG or SVG file of at most 300 KB. Use a picture that still reads when cropped, about 960×540. Paths with
  `..`, absolute paths and hidden files are refused, and a file whose real path
  leaves the plugin folder isn't served. An SVG is shown only as an image, so
  its scripts never run.
- **`accent`** (`#rgb` or `#rrggbb`) and **`icon`** (a single emoji) draw the
  card when there is no image, or until it loads.

A starter that can't work, for example one with no prompt, a form outside the
supported fields, or a placeholder the form lacks, is left out. An unknown key,
or a bad image, accent or icon, is ignored. Either way the rest of the cards
still show, the plugin's servers still load, and the server log says what was
wrong. Up to 20 starters are read; New chat shows the first 8.


**Workspace settings** lists each enabled contract plugin with its settings. A
plugin whose server needs a secret that isn't set shows **Needs setup**.

- **Secrets** are entered in a masked field and are write-only. The page shows
  only "Set on Oct 24 · Replace · Remove", never the value, on the phone and
  through the relay as well. On the server you can also run
  `npm run workspace -- plugin-secret w-... hello api_key --stdin` (the value is
  read from standard input) or `--remove`.
- **Raising a limit**, that is a number going up or a switch turning on, is saved
  only after you confirm a dialog that names the old and new values ("Raise
  “Most a job may cost (USD)” from 10 to 25?"). The server refuses such a change
  without that confirmation.
- Changes apply to tasks started afterwards, including a stopped task you resume.
  Running tasks keep the settings they started with.
- Disabling the plugin wipes its secrets.

Settings and secrets are kept in the data folder, in
`plugins/<workspace>/<plugin>/config.json` and `secrets.json` (mode 0600), or
`plugins/_host/<plugin>/` for host-scope plugins. Tasks can't reach the data
folder in [This Mac mode](https://console.uubright.com/docs/local-mode/); see [Security](https://console.uubright.com/docs/security/) for host
mode.

## How the servers run

The runner starts a contract plugin's servers itself, through its **plugin
broker**. The agent, Claude Code or Codex, gets a small stdio shim for each server
whose only setting is the broker's socket path, so its tools keep their usual
names (`mcp__plugin_hello_hello__…`). Claude Code then runs with
`--strict-mcp-config`, so it doesn't also start the plugin's own `.mcp.json`
copy. For Codex the copy is left out of `thread/start.config` and of an `own`
login's `config.toml`. Because of `--strict-mcp-config`, a Claude task in a workspace with a contract
plugin also skips your own MCP servers (from `~/.claude.json` and installed
plugins), on a server as on This Mac. Workspace settings says so under
[What your tasks already have](https://console.uubright.com/docs/workspaces/#what-your-tasks-already-have).

- A server's environment holds the runner's `PATH`, `HOME`, locale and temp
  folder, the manifest's `env`, and `CLAUDE_PLUGIN_ROOT`. It doesn't inherit the
  runner's or the agent's credentials.
- Secrets arrive on **file descriptor 3**, never in the environment, the command
  line or an MCP config. `UUBRIGHT_SECRETS_FD=3` says the channel exists. The
  server reads one line, `{"secrets": {"api_key": "…"}}`. The server is the
  runner's child, not the agent's, so the agent can't read it from `/proc`.
- The runner gets the secrets from the control plane **once per start**, before it
  starts the agent. Its link token is in its environment, where a host task's
  agent could read it, so the token alone gets nothing: any later request for
  plugin setup or secrets is refused, and a form the runner reports must come
  from a plugin server it registered at that setup. To pick up a changed setting
  or secret, start the task again.
- Every value delivered this way, and its base64 and URL-encoded forms, is
  replaced by `[redacted]` in everything that leaves the runner: tool results the
  agent receives, the server's stderr (logged in the task feed), and all task
  events. A tool result that contained a secret is noted in the feed.
- Redaction covers what leaves the runner, not the task's files. A server that
  writes its secret into the workspace (a config file, a log) puts it where the
  agent can read it; the agent's reply is redacted on its way out, but the agent
  itself has the value. Keep secrets in memory, or outside the workspace.
- A server that doesn't answer `initialize` within 30 seconds is stopped, and
  servers still running when the task stops get SIGTERM, then SIGKILL.
- A server with an unset secret isn't started; the agent's call fails with
  "hello (hello) needs setup: Hello API key." and the feed says so once.

A plugin server that reads its key from fd 3 when `UUBRIGHT_SECRETS_FD` is set,
and from its own file otherwise, works both in uuBright Console and in plain
Claude Code.

## Forms

A plugin server can ask you for input with MCP **elicitation**. The broker is
the server's MCP client, so this works the same with Claude Code and Codex, and
**your answer goes to the server, never to the agent**. A server can therefore
treat your **Send** on a form ("Apply cleanup: 3 bundles, 1,204 messages?") as
proof that you saw that exact preview: a prompt-injected agent can't produce it.
Both protocol shapes are supported: the server's `elicitation/create` request,
and the 2026-07-28 `input_required` result, after which the broker retries the
call with your answer.

The form shows in the task's chat and in **Needs you**. On a phone, **Fill in
form** opens it as a full-screen sheet; closing the sheet leaves the card open.
Every form has the same header, drawn by the console: the plugin and server
name and "asks". **Send** checks the fields first; **Decline** and **Not now**
answer without content.

Supported fields: text (with `minLength`, `maxLength` and the formats email,
URI, date and date-time), numbers and whole numbers (`minimum`, `maximum`),
switches, single choice (`enum`, or `oneOf` with titles; four options or fewer
show as chips, more as a list) and multiple choice (`type: array` with
`minItems` and `maxItems`). `title`, `description`, `default` and `required`
are honoured. Text in a form is never turned into a link. At most 20 fields, 50
options and 10,000 characters per text field; a message of at most 1,000
characters; at most three open forms per task. A form outside this set is
answered `cancel` and the feed says "hello asked for a form uuBright Console
can't show".

A **link form** (URL mode) shows the full address with its domain highlighted,
and warns about look-alike (punycode) characters and plain `http`. **Open**
opens it in your browser and answers the server; the page is never fetched by
the console. When the server reports the sign-in finished, the card says so.

A form lasts as long as the tool call that asked. When the call ends, the agent
cancels it, or the task stops, the card turns into "Expired: the tool call ended
before an answer". For answers that may take hours, a plugin should ask with a
decision card instead. Forms push a notification like questions do. Answers are
kept in the task's history, so form fields must never hold secrets: use a secret
setting or a link form for those.

## API

- `GET /api/workspaces/:id/plugins`: each enabled plugin as `legacy`,
  `contract` (with its fields, values, `set` and `updatedAt` for secrets, and
  `needsSetup`) or `refused` (with the reason).
- `PUT /api/workspaces/:id/plugins/:name/config` with
  `{"values": {"max_usd": 25}, "confirmed": ["max_usd"]}`. `null` clears a value.
  A raise that isn't in `confirmed` gets `409` with `raises: [{field, title, from,
  to}]`.
- `PUT /api/workspaces/:id/plugins/:name/secrets/:field` with `{"value": "…"}`,
  `DELETE` to remove it, `GET` for `{"set", "updatedAt"}`. No route returns a value.
- `GET /api/workspaces/:id/plugins/:name/assets/<path>`: a starter's image, only
  for a path its manifest declares, with its content type and
  `X-Content-Type-Options: nosniff`. `?as=json` returns `{"type", "data"}` with the
  bytes in base64, which is how the app loads it, also through the relay.
- `POST /api/sessions/:id/forms/:formId` with `{"action": "accept", "content": {…}}`,
  or `decline` or `cancel` without content. The answer is checked against the form.

Paired devices may use these routes. Agents can't: they hold no owner or device
token.

## Not in this version

Plugin views (MCP Apps `ui://` resources), general OAuth descriptors (`auth`),
HTTP plugin servers and the `deliver: "env"`
fallback come later. In Docker mode, named workspaces and their plugins aren't
available yet.

SciMigo Studio is moving to its own app; this applies to a Studio workspace that already
exists. SciMigo Studio has a dedicated device sign-in path while the general `auth`
contract is unfinished. Its control plane keeps the refresh token in a mode-0600
file under the selected execution host's data directory, scoped to the Studio
workspace. The connector receives only short-lived access tokens over its fd-3
broker channel. The broker never puts one in an agent environment, MCP config,
prompt, transcript or URL. Sign-in, refresh and revocation call only
`https://api.scimigo.com` without following redirects. The browser opens the
fixed `https://scimigo.com/device` page and displays the code separately.
The host keeps a mode-0600 hash of each runner's broker capability so a
control-plane restart can continue refreshing that runner without storing the
capability itself. Restarting or stopping a task clears its previous verifier.

This device sign-in path is enabled only in This Mac mode, whose task sandbox
protects the app data directory. Remote host mode cannot yet isolate saved
refresh tokens from tasks and refuses Studio sign-in.

The separately published Studio connector uses an Ed25519-signed release
manifest and exact SHA-256 archive digest. Local startup pins the public
release repository's stable manifest URL and Ed25519 public key; a developer
override must set `CCR_CLOUD_STUDIO_RELEASE_MANIFEST_URL` and
`CCR_CLOUD_STUDIO_RELEASE_PUBLIC_KEY` (base64 SPKI) together. The verified
connector is installed outside core data and the app bundle; local tasks may
read but not edit it. Missing or unreachable releases leave Studio visible,
with a retry control in Workspace settings. Release signing requires a private
key supplied to the connector repository's builder on fd 3.
