Configure Teambook Desktop

Local project and Workspace link

Initialize project-scoped configuration and link the current local project to a Workspace project whose shared resources should be available in desktop.

Important behavior

• Workspace authentication is managed separately in the desktop app.
• Linking resolves only projects visible to the connected user and rejects ambiguous names.
• Unlinking removes only the local association; it never deletes resources.

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

• The first model in a scope becomes its default. Later additions and updates require --default to change the default.
• 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.

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.

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

• 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

• The model override is optional; when omitted, the worker uses the notebook's selected model.
• Prompt templates and structured fields belong to smart 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"

[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.
• A remote script requires an HTTPS url and SRI hash. Project renderers may instead use an HTTPS manifest with name, tag, and sha256.
• Local script paths resolve relative to the TOML source and are stored as absolute paths.
• Built-in renderer keys are immutable, and 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.