Configure Teambook Desktop

Global Workspace connection

Inspect, establish, or remove the Desktop-wide Workspace connection independently from directory project links.

Important behavior

• Workspace connection state is global to Desktop; teambook project commands manage only the current directory's resource scope.
• Status keeps persisted server and identity details visible when the configured Workspace is unavailable.
• Disconnect is offline: it does not contact the configured server, deletes the native credential, and atomically resets workspace_state.json.

Local project and Workspace link

Inspect the current directory's effective Workspace resource scope, initialize project configuration, or link it to one Workspace project.

Important behavior

• Workspace authentication is managed separately in the desktop app.
• A connected directory with no project link uses the Workspace-wide catalog; an invalid config or project link stays local-only.
• Linking resolves only projects visible to the connected user and rejects ambiguous names.
• Unlinking removes only the local association; it never deletes resources.
• Notebook and resource scope comes from the nearest .teambook/project.json in the current directory or an ancestor; changes take effect when a notebook is reopened.
• Use project resources for one effective inventory of models, prompts, subagents, skills, renderers, cells, tools, MCP servers, and remotes. It uses the same scope as project status and fetches the live Workspace catalog when connected.

Opening notebooks from the terminal

Create or open a project-scoped .tb notebook in Teambook Desktop.

Important behavior

• With no path, the command creates Untitled.tb in the current directory, using the first free numbered name when needed.
• A missing path is created as an ordinary .tb file before Desktop opens it; an omitted .tb extension is added automatically.
• The notebook inherits .teambook/project.json from the nearest ancestor directory. The CLI hands the file to Desktop and never launches a sidecar itself.
• Notebook settings use the project's store default when configured; otherwise documents are embedded in the notebook .tb file. Within a project, the user may select the shared .teambook/store.sqlite project store.
• Store contents are never attached, scanned, or uploaded automatically. Values returned explicitly by model store tools or JavaScript ctx.store.query become ordinary saved cell results.
• If Teambook Desktop is unavailable or launch fails, a newly created file is removed.

Runnable models

Install runnable model definitions and choose global or project defaults independently from provider authentication.

Portable model source

[provider]
name = "Acme AI"
api_base_url = "https://api.acme.example/v1"
client_type = "openai_responses"
api_key_env = "ACME_API_KEY"

[model]
name = "Acme Agent"
external_id = "agent-v1"
provider = "acme"

[[model.capabilities]]
name = "tools"
label = "Include tools"
type = "boolean"
default = { value = false }

Important behavior

• When Desktop is connected, list and show include the current directory's read-only Workspace-wide catalog or its linked-project catalog. Local definitions take precedence.
• The first agent model in a scope becomes its default. Direct HTTP processors are limited to Model calls and cannot become a notebook default.
• Global HTTP processors display a secret-free security review. Interactive installs require confirmation; automation must pass --allow-http-execution. Project processors follow the current project configuration policy without a descriptor-specific prompt.
• Updating a global HTTP processor repeats the review only when its endpoint, transmitted inputs, authentication identity, execution contract, or user-supplied meter rates change.
• Project HTTP descriptors are passive catalog entries: loading or reloading them does not resolve credentials or make a network request. Network activity starts only when a compatible Model call runs.
• HTTP execution remains POST-only with a relative path, one bounded request/response, no retry, same-origin redirects, direct public DNS resolution, and loopback-only plaintext development URLs.
• HTTP processor timeout_seconds defaults to 60 and is capped at 600 seconds; the effective timeout is shown during review and included in the approval fingerprint.
• Meter rates on global or project descriptors are labeled user-supplied. Managed and Workspace catalog rates remain read-only managed metadata.
• The default command can select a usable read-only managed model without copying its definition into user configuration.
• The creator command selects a model for notebook-local cell generation. Project selection overrides global selection; when neither is set, the notebook model is used. Reopen the notebook after changing it.
• Deleting the active default requires --replacement naming another model already installed in the same scope.
• client_type, when set, must be openai_responses, openai_codex_responses, openai_chat, anthropic, or gemini.
• Capabilities are optional. Each capability that is present requires name, label, and type; enum capabilities also require string options.
• Credentials are managed separately with teambook auth. Model deletion never deletes stored credentials, and secret values never enter TOML, JSON config, or notebook files.
• To diagnose a missing Desktop model, run teambook catalog status for the managed ChatGPT subscription projection, then teambook model list and teambook model show <id> for the effective merged catalog and origin. Use teambook auth key status <id> for a user-installed model's credential; check managed subscription authentication with teambook auth status openai. Run them from the notebook directory with the same binary as Desktop.

Provider authentication

Connect OAuth-backed providers and manage native API-key credentials without displaying secret values.

Important behavior

• ChatGPT subscription login uses OAuth and is available on macOS. Its credential remains in Keychain, and catalog refresh failure never rolls back a valid login.
• The managed catalog is fetched independently from assets.teambook.ai. Logout removes only the credential and leaves the last valid catalog cache in place.
• API keys are stored in the operating system credential service. The --project flag selects models in the current project configuration; it does not write secret values to project files.
• API-key status reports native, environment, or missing without displaying a secret value. A configured native reference falls back to the model's environment variable when the native item is absent.
• Use --stdin to avoid interactive input. Never pass an API-key value as a command-line argument.

Managed model registry

Refresh and inspect the read-only Teambook-managed ChatGPT subscription model layer.

Important behavior

• Desktop checks the TOML registry at startup with a six-hour TTL. An invalid or unavailable refresh never replaces the last valid cache.
• The registry comes only from https://assets.teambook.ai/models. The sidecar validates the pinned provider authentication, endpoint, transport, and supported capability/tool routes.
• User model entries take precedence by provider-qualified identity. An explicit user default remains stable; otherwise the managed recommended default is effective without rewriting config.json.
• ChatGPT OAuth credentials are stored separately. Registry outages do not roll back a valid login, and logout leaves the registry cache in place.

Pre-defined cells

Add and manage YAML definitions for reusable notebook cells.

cell.yaml source

version: 1
key: example
name: Example
description: Run an example command.
installation: |-
  Install the tools and credentials required by this definition.
spec:
  form:
    fields:
      - name: value
        label: Value
        control: text
  cells:
    - key: run
      type: llm
      input:
        src: "Explain {{value}} with a short example."
      settings:
        model_id: openai/gpt-5.6-luna
        output_schema:
          type: object
          properties:
            lesson: {type: string}
          required: [lesson]
        hooks:
          on_success:
            - kind: javascript
              code: |
                export function run(event) {
                  if (!event.value?.lesson) throw new Error("lesson is required");
                  return {...event.value, reviewed: true};
                }
            - {kind: store.append, namespace: grammar_log, source: current}
            - {kind: file.write, path: "data/lessons/{{$today}}-{{value}}.json", source: current}
usage: |-
  # Example

  Explain when to use this cell, what good input looks like, and how to interpret its output.

Important behavior

• Add parses one YAML document and writes a versioned JSON envelope into global config.json or the current project's .teambook/project.json. Notebook startup never scans cell.yaml files.
• The optional installation field contains Markdown setup instructions available through cell show. The optional usage field is Markdown guidance shown in Cell info and supplied to models; installation instructions are not projected there.
• Scope defaults to global; pass --scope=project for the current project. Project definitions override global definitions with the same key.
• No pre-defined cells are embedded in the binary. Placed workflow cells retain their persisted definition snapshot if an installed definition changes or is removed.
• Use cell.yaml inside a package folder matching the key, or pass any .yaml/.yml file explicitly. Omit spec.form for one optional textarea exposed as {{input}}; use form: {fields: []} for no input controls. A textarea form field can customize its label, name, default, and required validation.
• The version 1 editor schema is at https://assets.teambook.ai/schemas/cell-v1.schema.json after registry publication; the checked-in schema and editor association example are in asset_registry/static/cells/README.md.
• Every cell type uses input.src for primary content: LLM prompt, Terminal command, JavaScript module, API URL, Query SQL, or Markdown text. Inline strings and package-relative source files share that field; single-line filenames ending in the type's extension (md/txt, sh/bash/zsh, js/mjs/cjs, url, sql) load from the YAML directory. API HTTP(S) URLs always stay inline. File contents are embedded and snapshots stay portable; direct JSON and conversational definitions require inline src. Legacy prompt/command/source/url/query/text remain readable but cannot coexist with src.
• The complete per-type YAML reference is docs/public/reusable-cell-yaml.md, including LLM, Terminal, JavaScript, API, Query, forms, files, hooks, and compatibility rules.
• Editing a YAML source has no effect until it is added again with --force. Reopen affected notebooks after add, delete, or direct JSON config edits; already-placed cells retain their snapshots.
• Cell installation validates and stores the definition, but it does not install or verify referenced models or tools. Install those dependencies separately in the configuration seen by Desktop.
• Every definition places one visible workflow cell with one to eight ordered LLM, Terminal, JavaScript, API, or Query stages. Use {{$stages.<earlier-key>}} to pass an earlier stage's canonical output forward; self and forward references are rejected.
• Use {{$stages.key}} for earlier stage text: LLM response, Terminal transcript, Query CSV, API body, JavaScript string or serialized JSON. Parse JSON or CSV explicitly in JavaScript. Typed selectors are unsupported in text fields.
• Terminal stages declare output_files: [audio.mp3]. Consumers bind input_files: {recording.mp3: "{{$stages.download.output_files['audio.mp3']}}"}. API input.body_file: recording.mp3 streams that file; explicit Content-Type wins. LLM attachments, JavaScript files.get, and Terminal relative paths use the same run-owned bindings.
• API settings.response_format is auto, json, or text. Complete usable responses, including 404/500, continue to later stages. Transport errors, incomplete bodies, and required validation failures stop execution.
• File stages receive private working directories; Terminal settings.cwd must be omitted. Literal relative paths only, with no traversal or symlinks. Each run owns fresh snapshots (32 generated files / 20 MiB total); success, failure, and cancellation release bytes while retaining metadata. Abandoned owned directories are cleaned when their process is gone. No generated artifact can be reused by a later run.
• The five-stage download → transcribe → extract transcript → correct names → summarize example is asset_registry/static/cells/summarize-youtube/cell.yaml. Install yt-dlp/ffmpeg and the referenced models; bind a stored Deepgram credential using the existing credential flow. Existing execution timeouts apply.
• Forms support text, textarea, url, url_or_file, and file-only file controls. Textarea Enter inserts a newline; Cmd/Ctrl+Enter runs the workflow. An LLM or JavaScript stage can declare a fixed ws:/remote: file or a form file in files; one desktop-picked file grant can feed multiple stages without being persisted. The existing api_body_file_field and llm_attachment_file_field URL-or-file shortcuts remain available per stage.
• Only the final stage can select a renderer. The workflow output and @@ reference value come from that stage; SQLite stage records retain intermediate and partial results.
• Templates may use {{$today}}, {{$now}}, {{$notebook_title}}, {{$notebook_dir}}, and {{$cell_id}} with the same destination-specific quoting rules as form fields. Form values remain literal, and \{{$today}} renders the token verbatim.
• A definition's final stage may declare JavaScript, store.append, and file.write hooks under settings.hooks.on_success. JavaScript hooks observe, replace, or reject the final workflow output before effects run. cell.run declarations and instance hook edits are unsupported.
• JavaScript hooks export run(event). Returning `undefined` leaves the current value unchanged, returning a compatible JSON value replaces it, and throwing or rejecting fails the cell. Explicit `null` is a replacement value, not a no-op. They run in the pinned sandbox without files, network, process, environment, or store access.
• Effect sources may be current, text, structured, or structured.<path>. Hook paths may use {{$today}}, {{$now}}, {{$notebook_title}}, {{$notebook_dir}}, {{$cell_id}} and form fields.
• Form names such as today, stages, and variables are ordinary inputs. Built-in runtime variables use the separate $ namespace.
• An LLM cell's settings.model_id must be the exact provider-qualified ID reported by teambook model list (for example openai/gpt-5.6-luna), not only the provider's external model ID (gpt-5.6-luna). Tool names must likewise match installed entries from teambook config tool list.
• A Query stage or an LLM stage enabling query_dataset may declare spec.requires.dataset with engine and an npm-compatible version range (for example duckdb and >=1.5.0 <1.6.0). Legacy minimum_version retains its inclusive comparison; declare exactly one version key. The notebook's own selection must satisfy it; the Cell never selects or replaces an engine.
• A direct Query notebook cell uses that same notebook-level dataset selection without a model. Its SQL runs read-only over explicitly attached CSV, TSV, Parquet, or JSON-lines files, with a 1–1000 row limit and 64 KiB CSV result cap. The selected external ADBC driver must remain checksum-verified and ready when each catalog or query starts.
• An LLM cell may declare settings.output_schema, a bounded JSON Schema object; the run stores the validated value as result.structured and @@cell.field references can read it.
• Public definitions are asset_registry/static/cells/download-youtube-audio/cell.yaml, asset_registry/static/cells/transcribe-with-deepgram/cell.yaml, asset_registry/static/cells/summarize/cell.yaml, and asset_registry/static/cells/public-taxi-stops/cell.yaml. DispatchOps demo cells live separately under demo_company/cells/. Summarize URLs require the fetch_url web tool and its JINA_READER_API_KEY secret; local files do not.

Run one cell

Execute one independent cell or reusable workflow from the terminal without creating a notebook. The invocation uses the selected local/project configuration and the same execution and permission behavior as Desktop.

Version 1 request example

{
  "version": 1,
  "values": {"question": "Summarize this fixture"},
  "form_files": {"trip_index": "fixtures/trips.csv"}
}

Important behavior

• Exactly one target is required: a positional file path or installed name, --source FILE.yaml, --definition KEY, or --type TYPE. Existing local paths take precedence over installed names; invalid files fail without falling back. Explicit flags force the requested lookup. --request - reads JSON from stdin; --cwd defaults to the caller's current directory and scopes relative paths.
• For workflows, piped or redirected stdin is read automatically as plain UTF-8 text when no --text or --request is supplied. For example: printf 'hello\n' | tb cell run echo.yaml. --stdin remains an explicit option; from a terminal it reads until EOF. Without an input option, terminal stdin produces a usage error instead of waiting for input.
• Plain text populates the definition's single text, textarea, url, or url_or_file field, preserving whitespace and newlines. Explicit --text or --request takes precedence over incoming stdin; input options are mutually exclusive. Multi-field forms and built-ins use --request; JSON stdin always requires --request -.
• Built-ins take canonical input/settings plus LLM or JavaScript files. Definitions take values, form_files, and optional stage_credential_refs; --source uses the current YAML file only for this invocation.
• --json prints one versioned result envelope. --output writes the same envelope to a new file. Exit codes are 0 success, 1 runtime failure, 2 invalid request, 3 interaction required, and 130 cancellation.
• Routine progress is silent by default. --verbose reports cell and workflow stage transitions, stage completion times, and named credential sources once per change on stderr, including with --json; stdout remains the result. Credential values and streamed output are never included in progress lines. Errors, warnings, and interactive questions retain their normal reporting.
• Tool confirmations and questions require an interactive terminal unless --non-interactive is selected. Existing work before a question is not rolled back.

Web tools

Add GET-only HTTP tool definitions and manage their OS-keychain secrets.

Example definition

{
  "key": "fetch_url",
  "name": "fetch_url",
  "description": "Fetches a markdown rendering of a web page. Use whenever asked about the content at a URL.",
  "parameters": {
    "type": "object",
    "properties": {
      "url": { "type": "string", "description": "The URL of the page to fetch" }
    },
    "required": ["url"]
  },
  "request": {
    "url_template": "https://r.jina.ai/{{raw:url}}",
    "headers": [{ "name": "Accept", "value": "text/plain" }],
    "auth": { "type": "bearer", "secret": "JINA_READER_API_KEY" }
  },
  "response": { "max_bytes": 1048576 },
  "settings": { "timeout_seconds": 30 },
  "confirmation_mode": "never"
}

Important behavior

• Definitions are installed beside the global configuration file and never contain credential values.
• Add the public Jina Reader definition with teambook config tool add asset_registry/static/tools/fetch-url/tool.json, then store its credential with teambook config tool secret set JINA_READER_API_KEY.
• Secret values are shared globally by name and stored under the isolated ai.teambook.desktop.web-tools service.
• Authenticated definitions must use HTTPS. Requests connect without environment proxies and apply the public-address filter during every DNS lookup, including redirect hops, so DNS rebinding cannot reach private services.
• Malformed installed definitions become notebook startup warnings instead of preventing startup.

Named workflow credentials

Reuse API-stage credentials by name across environment, local project, machine, and the connected Workspace. Secret values stay in native storage or the Workspace and are read only for authorized execution.

API-stage requirement

auth:
  type: api_key_header
  header: Authorization
  value: "{{ secrets.DEEPGRAM_AUTHORIZATION }}"

Important behavior

• Names use [A-Z_][A-Z0-9_]*, at most 128 characters, without case conversion. Unqualified lookup uses env → project → machine → org. Explicit scope uses only that source. A defined empty value, locked store, denied access, or network failure stops the run before HTTP; only absence falls through.
• Project credentials use the canonical root discovered through .teambook/project.json as their native-store identity. Different clones and worktrees have independent project credentials. A missing project or disconnected Workspace is skipped automatically and errors when selected explicitly.
• Environment means the executing Teambook process environment; restart Desktop after changing it. Machine/project values use ai.teambook.desktop.workflow-secrets, isolated from providers, web tools, and API-cell bindings.
• Workspace credentials are team secrets set in Settings → Secrets. The single-name execution export endpoint requires a connected Workspace admin; ordinary members cannot export them. Invalid or mismatched project links fail closed. A saved stage binding remains authoritative until explicitly cleared in the workflow credential controls.
• The complete header value comes from the credential, including Token/Bearer prefixes if required. References work only in API authentication and headers marked secret, never prompts, commands, bodies, URLs, or ordinary headers. Last-run credential_sources reports scope without values.

Remote file locations

Configure S3-compatible buckets that notebooks read files from by name.

Location definition source

{
  "key": "team-files",
  "label": "Team files",
  "provider": "s3",
  "bucket": "example-team-files",
  "endpoint": "https://0123456789abcdef0123456789abcdef.r2.cloudflarestorage.com",
  "region": "auto",
  "prefix": "shared/",
  "virtual_hosted_style": false,
  "auth": {
    "type": "access_key",
    "access_key_id": "EXAMPLE_ACCESS_KEY_ID",
    "secret": "TEAM_FILES_SECRET_ACCESS_KEY"
  }
}

Important behavior

• Definitions are stored in global config.json or the current project's .teambook/project.json under remotes, and never contain credential values. Project entries override global entries with the same key.
• Store the secret access key with teambook config remote secret set <SECRET_KEY>. Values live in the isolated ai.teambook.desktop.remotes credential service and are shared by name across locations.
• List reports a location's secret as set, MISSING when the credential store has no such secret, or unknown when the store itself cannot be read - a machine without a keyring can still configure and inspect locations, since the secret is only needed to read an object.
• Notebook files reference objects as remote:<key>/<object key>. The notebook never stores endpoints, buckets, or credentials, so a shared notebook reads whichever bucket the reader's location points at. Omit auth for public buckets.
• One provider value, s3, covers AWS S3, Cloudflare R2, DigitalOcean Spaces, MinIO, and other S3-compatible endpoints. Leave virtual_hosted_style false for R2, Spaces, and MinIO.
• Endpoints must be https; http is accepted only for localhost or a loopback address, for development servers. Set region when no endpoint is given; with an endpoint it defaults to auto.
• Reads are read-only: there is no write, listing, or bucket browsing. Each request carries a 3-second connect and 8-second request timeout, retried at most twice, so an unreachable bucket fails inside the run deadline.
• Malformed installed definitions become notebook startup warnings instead of preventing startup. Reopen affected notebooks after add, delete, or direct JSON config edits.

Notebook dataset configurations

Install a portable SQL-domain definition and bind it to an external ADBC driver.

dataset.yaml source

version: 1
key: duckdb-local
name: Local DuckDB
description: Analyze attached datasets with an installed DuckDB.
engine: duckdb
engine_version: ">=1.5.0 <1.6.0"
driver: duckdb
entrypoint: duckdb_adbc_init
mode: local_attachments
profile: duckdb-attachments-v1
requires:
  parameter_binding: true
  native_formats: [csv, tsv, parquet, ndjson]
guidance: |-
  Use DuckDB SQL for the tables in the supplied catalog.

Important behavior

• Source definitions use YAML, with optional SQL-domain text in guidance. Legacy Markdown sources must be converted before reinstalling; previously installed normalized definitions remain valid.
• The normalized definition is portable. Absolute library paths, hashes, manifest details, and verification evidence stay in a separate machine-local installation record and never enter project config or a .tb notebook.
• Guidance is inert text, and add installs no engine. Teambook's bundled worker loads either --driver-library or the definition's standard ADBC manifest name in a disposable process.
• Definitions are limited to 256 KiB and SQL-domain guidance to 16 KiB. Unknown fields, duplicate YAML keys, malformed version ranges, conflicting bindings, and unsupported execution profiles fail installation.
• Project definitions override global definitions with the same key. Editing dataset.yaml has no effect until add is run again; --force atomically replaces future-run definition and verification state.
• Verification records protocol, ADBC API, driver, engine, profile, and library identities. Changed or missing external drivers fail closed and never select another engine silently.
• An installed configuration is eligible for model-authored queries only when its exact engine/profile verification reports an approved safe execution contract. Interoperability fixtures are not advertised as notebook-safe.
• The public asset_registry/static/adapters/duckdb-attachments-v1/dataset.yaml definition uses native CSV, TSV, Parquet, and NDJSON readers. It accepts one read-only DuckDB query through bound query(?) wrappers. Dynamic PIVOT is unsupported; provide an explicit IN value list.
• Selecting a configuration never grants file access by itself. A run receives only the cell's existing tabular attachments plus the notebook declarations in its accepted snapshot, and no configuration authorizes remote uploads.
• The Data sources tab can declare up to 32 named datasets from local: paths relative to the notebook or project: paths relative to the detected project root. Every Query cell sees all declarations; an LLM cell sees all declarations when query_dataset is enabled. Sources are bound directly without copying, hashing, or an aggregate byte limit. LLM source resolution and worker startup wait until the first query_dataset call. remote: is reserved but unsupported until an engine can bind it directly.
• A null or absent selection means no dataset engine is selected; users must explicitly choose an installed configuration in the Data sources tab.

Prompts

Create reusable system prompts that appear in the desktop prompt picker.

Prompt source

[prompt]
id = "brief"
name = "Brief"
content = "Summarize the request and recommend the next action."

Important behavior

• When Desktop is connected, list and show include the current directory's read-only Workspace-wide catalog or its linked-project catalog.
• Prompt content is literal; environment-reference syntax is not expanded.
• Hosted share levels are intentionally not accepted because desktop prompt configuration stays local and is never synced to Workspace.
• Prompt ids and names share one case-insensitive namespace within a scope. Add and update reject collisions unless --force atomically replaces the conflicting local prompt.
• A project prompt shadows a global or Workspace prompt with the same identity.

Subagents

Define reusable worker roles with optional model overrides and execution options.

Subagent source

[subagent]
id = "reviewer"
name = "Reviewer"
description = "Reviews a proposed change"
model = "acme/agent-v1"
system_prompt = "Review carefully and report actionable findings."

[subagent.options]
temperature = 0.1

Important behavior

• When Desktop is connected, list and show include the current directory's read-only Workspace-wide catalog or its linked-project catalog.
• The model override is optional; when omitted, the worker uses the notebook's selected model.
• Prompt templates and structured fields belong to Cells, not subagent definitions.
• Subagent ids and names share one case-insensitive namespace within a scope. Add and update reject collisions unless --force atomically replaces the conflicting local subagent.
• Project definitions shadow global and Workspace definitions with the same id or name.

Agent Skills

Install complete Agent Skills directories containing SKILL.md plus optional scripts, references, and assets.

SKILL.md inside a matching directory

---
name: review-helper
description: Review a proposed change using the team checklist
license: MIT
---

Read `references/checklist.md`, inspect the proposed change, and report actionable findings.

Important behavior

• The directory name must match the lowercase hyphenated name in SKILL.md.
• Install and update copy the complete directory atomically and reject symlinks.
• Built-in skills are read-only; project skills shadow global and built-in skills by name.

Renderers

Install trusted web-component modules that render structured notebook responses.

Local renderer source

[renderer]
key = "orgchart"
label = "Org Chart"
content_type = "application/vnd.acme.orgchart+json"
custom_element_tag = "acme-orgchart"
custom_classes = "orgchart"
output_instruction = "Emit an org-chart JSON object without a Markdown fence."

[renderer.script]
path = "./orgchart.js"

Important behavior

• Renderer modules execute code. Install only sources you trust.
• content_type is required. When accepts is omitted, the renderer accepts that content type exactly.
• output_instruction optionally tells the model how to produce compatible content; otherwise guidance is derived from the selected content descriptor.
• A remote script requires an HTTPS url and SRI hash. A local script may include an SRI hash to pin its bytes; project renderers may instead use an HTTPS manifest with name, tag, sha256, and optional output_instruction.
• Local script paths resolve relative to the TOML source, are stored as absolute paths, and are verified at install and startup when pinned.
• Renderer list includes invalid user-owned entries from raw global or project config with their scope; show includes the validation warning. When a stale entry shares a key with a valid renderer, use --global or --project to inspect the intended scope before deleting it.
• Renderer code runs in a sandboxed opaque-origin frame. Local scripts use credential-free, content-addressed URLs with SRI and never receive the sidecar auth token.
• Renderer identity and executable location come only from global or project config. Project renderers cannot replace global renderer keys.

MCP servers

Configure local or remote MCP servers, connect OAuth servers, inspect their tools, and explicitly choose which tools runs may use.

Important behavior

• Servers live in global config.json, connection state lives in mcp_state.json beside it, and tokens live only in the operating system credential service.
• Remote servers expose no tools until you explicitly allow them.
• Restart the desktop app after MCP configuration changes.