Plugin settings, secrets and forms
A plugin enabled in a workspace 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.
{
"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 supports1. A plugin that needs a version this console doesn't know is refused byenable-pluginwith 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 equalplugin.json'sname. Unknown top-level keys are refused so that typos fail loudly. Keys that start withx-are the plugin's own. - **
servers.<id>** is an MCP server the console runs for the agent:command,args,env,cwd(workspace, the default, orplugin),secretsandtimeoutSeconds.${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 insecrets: incommand,argsorenvit is refused. HTTP servers (url,headers) are not supported in this version. - **
config.fields** uses the same field types as forms (below), plussecret,pattern(a regular expression checked on save) andrestart: "task".config.scopeisworkspace(the default) orhost, which shares one set of values among the workspaces that enable the plugin. - **
starters** are the plugin's cards on New chat (below). - **
auth,viewsandagents** are accepted but not used yet; settings say so.
#Starters
starters lists the cards a plugin adds to 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.
"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) andpromptare required.description** is shown in two lines on the card. - **
form** uses the form field types. 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'scommands/*.md. The filled prompt is then its arguments:/plugin:command <prompt>for Claude Code, and the command's text with$ARGUMENTSreplaced 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** (#rgbor#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; see 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.
- A server's environment holds the runner's
PATH,HOME, locale and temp folder, the manifest'senv, andCLAUDE_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=3says 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
initializewithin 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 aslegacy,contract(with its fields, values,setandupdatedAtfor secrets, andneedsSetup) orrefused(with the reason).PUT /api/workspaces/:id/plugins/:name/configwith{"values": {"max_usd": 25}, "confirmed": ["max_usd"]}.nullclears a value. A raise that isn't inconfirmedgets409withraises: [{field, title, from, to}].PUT /api/workspaces/:id/plugins/:name/secrets/:fieldwith{"value": "…"},DELETEto remove it,GETfor{"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 andX-Content-Type-Options: nosniff.?as=jsonreturns{"type", "data"}with the bytes in base64, which is how the app loads it, also through the relay.POST /api/sessions/:id/forms/:formIdwith{"action": "accept", "content": {…}}, ordeclineorcancelwithout 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.