This is the abridged developer documentation for ZenCopy # Configuration > What the settings window offers (for everyone), and fine-grained customization through config files (for power users). ZenCopy works out of the box with nothing configured. This page is for when you want it to fit you better. The first half, about the **settings window**, is for everyone; the second half, about **config files**, is for power users. ## The settings window [Section titled “The settings window”](#the-settings-window) Open it from the tray icon’s menu, or the gear icon on the popup. It has three tabs: **General, AI, and Actions**. ### General [Section titled “General”](#general) * **Popup position** — which corner of the screen results appear in. * **Theme** — light / dark / follow the system. * **Language** — the display language (follows your OS by default). * **Launch at login** — have ZenCopy waiting whenever your computer is on. * **Confirmation before sending** — whether to ask once before images or files go to the AI. ### AI [Section titled “AI”](#ai) This is where you change the AI service (provider, model, API key). The **Test** button tells you right away whether the connection works. The tab also has an **About you** field. It is a place to describe your role and preferences in a few plain sentences, in any language. > Example: “Sales. I mostly write customer emails — polite but not stiff, conclusion first.” With this filled in, every action tailors its results to you. Explanations arrive at your level of knowledge, and drafts come back in your preferred tone. It never affects unrelated tasks, and the text itself never shows up in results. ### Actions [Section titled “Actions”](#actions) The list of “what happens after a double copy”. * The pre-installed actions can be opened and read — they double as worked examples. * A **new action** takes nothing but a name and what you want done. For example: name “3-line summary”, instruction “Summarize this in 3 lines”. * Not confident writing instructions? Jot down roughly what you want and press **Draft with AI** — your configured AI turns it into a well-formed instruction. * **Routing** lets you pick a different action per kind of content (text / image / files). Actions you build can be shared: **Export** writes one as a file, and the receiving side just pastes it into **Import** or picks the file. Prefer to hand the whole job to an AI? Any AI chat can write a ready-to-import action for you — paste this and fill in the blank: ```text Read https://zencopy.app/llms-full.txt — the full ZenCopy documentation, including the action file format, the template variables, and how routing works. Then write a ZenCopy action that does the following: [what you want]. Output one complete action file (Markdown with frontmatter) in a single code block, ready to paste into ZenCopy's Settings → Actions → Import. If the action only makes sense in a specific app or on a specific site, add one sentence telling me which routing rule to set. ``` The code block in the reply goes straight into **Settings → Actions → Import**. For questions the documentation cannot answer (“could ZenCopy even do…?”), [one click packs the relevant source](https://repomix.com/?repo=sincekmori%2Fzencopy\&format=markdown\&removeComments=true\&include=src-tauri%2F**%2Csrc%2F**%2Csite%2Fsrc%2Fcontent%2Fdocs%2Fen%2F**%2CREADME.md\&ignore=**%2FCargo.lock%2Csrc%2Flib%2Fmessages%2Fja.ts%2Csrc%2Flib%2Fmessages%2Fzh-hans.ts%2Csrc%2Flib%2Fmessages%2Fzh-hant.ts%2Csrc%2Flib%2Fmessages%2Fko.ts%2Csrc%2Flib%2Fmessages%2Fes.ts%2Csrc%2Flib%2Fmessages%2Fpt-br.ts%2Csrc%2Flib%2Fmessages%2Ffr.ts%2Csrc%2Flib%2Fmessages%2Fde.ts%2Csrc%2Flib%2Fmessages%2Fit.ts%2Csrc%2Flib%2Fmessages%2Fpl.ts%2Csrc%2Flib%2Fmessages%2Fru.ts%2Csrc%2Flib%2Fmessages%2Fid.ts%2Csrc%2Flib%2Fmessages%2Fvi.ts%2Csrc%2Flib%2Fmessages%2Fth.ts%2Csrc%2Flib%2Fmessages%2Ftr.ts%2Csrc%2Flib%2Fmessages%2Far.ts%2Csrc%2Flib%2Fmessages%2Ffa.ts%2Csrc%2Flib%2Fmessages%2Fhe.ts) — hand the result to the same AI. ## Config files (for power users) [Section titled “Config files (for power users)”](#config-files-for-power-users) From here on, this page is about editing text files directly. **Everything essential is available from the settings window, so feel free to stop reading here.** Files are read from the per-user app config directory. The exact path is also printed to the log at startup: * Windows `%APPDATA%\app.zencopy` * macOS `~/Library/Application Support/app.zencopy` * Linux `~/.config/app.zencopy` Routing defaults are embedded in the app; `routing.json` only ever **overrides** them. Action files are **additive**: they define new actions, and the built-ins are untouchable (a local file claiming a built-in id is ignored). Edits apply on the next trigger — no restart needed. ### `ai-sdk-catalog.json` [Section titled “ai-sdk-catalog.json”](#ai-sdk-catalogjson) Providers plus a **role → model** mapping. The file format’s home is [ai-sdk-catalog](https://github.com/sincekmori/ai-sdk-utils/tree/main/packages/catalog#readme) — every field is documented there (including a `$schema` for editor validation and completion), and [`examples/`](https://github.com/sincekmori/ai-sdk-utils/tree/main/packages/catalog/examples) has configs in three sizes. For ZenCopy-flavored starting points (what the settings UI writes, local Ollama, roles for actions), see [Recipes](/en/recipes/). One requirement is ZenCopy’s own, not the format’s: `roles` must always include **`default`**. Every action runs with it unless the action’s frontmatter names another role, and the connection test in the settings pings it. API keys go straight into this local file (the settings UI writes the same format); they never leave your machine. Environment variables are not read — GUI apps are launched by the OS, not by your shell, so variables exported in `.zshrc` and friends never reach them. The file is schema-validated on every read. A broken edit shows up as a clear message in the popup and the settings editor — nothing fails silently. ### `routing.json` [Section titled “routing.json”](#routingjson) Which action handles which kind of capture: a flat `kind → action` map plus an optional, higher-priority `overrides` list (first match wins). The four kinds are `text`, `rich_text`, `image`, and `files`; out of the box, text routes to Zen and images and files route to Explain. The flat map is editable in-app (Settings → Actions → Routing), so you only need to touch this file for `overrides`. ```json { "text": "zencopy-zen", "rich_text": "zencopy-zen", "image": "zencopy-explain", "files": "zencopy-explain", "overrides": [{ "when": { "app_name": "Slack", "min_chars": 200 }, "action": "summarize" }] } ``` `when` conditions: `kind`, `app_name`, `exec_name`, `window_title`, `url` (all with `*` wildcards), `file_name` (a wildcard every copied file’s name must match, case-insensitively — e.g. `*.pdf`), plus `min_chars` / `max_chars`. For `image` and `files` captures, the content itself is sent to the model (up to 10 MB total per capture). File types are detected from **content**, not names: images, PDFs, and audio are attached as-is, while text files (Markdown, source code, CSV, …) become the capture’s text (`{{ text }}`) and behave exactly as if you had copied their contents. Office documents (Word, Excel, PowerPoint) also become text: what they say is extracted and sent, their layout and images are not. Character encodings are auto-detected, converting legacy formats like Shift\_JIS and UTF-16. Anything else is declined with a clear message. Full paths ride along with the contents so the model can tell files apart and knows where they live. Because binary attachments can cost more than text, the popup asks before sending them (text files run without a prompt) — the confirmation can be turned off in place or in Settings. ### `actions/*.md` [Section titled “actions/\*.md”](#actionsmd) One file = one action: YAML frontmatter + a [Liquid](https://liquidjs.com) prompt body. The same single file is the sharing format — Settings → Actions → Import accepts it as pasted text or a picked file. ```markdown --- id: summarize label: Summarize role: default instructions: You are a concise assistant. --- Summarize in 3 lines, in {{ locale }}: {{ text }} ``` | Frontmatter | Meaning | | -------------- | ---------------------------------------------------------------------------------------------------------------------- | | `id` | Name referenced from `routing.json` (default: file name) — the `zencopy-` prefix is reserved for pre-installed actions | | `label` | Shown in the popup | | `role` | Catalog role to run with (default: `default`) | | `instructions` | System prompt (Liquid template) | Template variables, with example values for a paragraph copied in a browser: | Variable | Example | | -------------------- | -------------------------------------------------- | | `{{ text }}` | The copied text (rich HTML copies become Markdown) | | `{{ markup }}` | The HTML/RTF source of a rich copy | | `{{ format }}` | `html` (or `rtf`; empty for plain copies) | | `{{ file_name }}` | `report.pdf` (the first copied file’s name) | | `{{ file_names }}` | Every copied file’s name, one per line | | `{{ file_paths }}` | Every copied file’s full path, one per line | | `{{ app_name }}` | `Safari` | | `{{ exec_name }}` | `Safari` / `chrome.exe` | | `{{ exec_path }}` | `/Applications/Safari.app/Contents/MacOS/Safari` | | `{{ window_title }}` | `Pricing – Example` | | `{{ url }}` | `https://example.com/pricing` (browsers only) | | `{{ process_id }}` | `8123` | | `{{ now }}` | `2026-07-08 20:15:00` | | `{{ locale }}` | `en` | There is also a ZenCopy-specific `language_name` filter: `{{ locale | language_name }}` expands to “English” rather than “en”, which reads naturally in a prompt. To see the real values, enable **developer mode** in Settings — each capture’s template variables appear in the popup as JSON. Simple actions (a name and an instruction) can also be created from the settings window; what it writes is exactly this file format. #### Advanced templating [Section titled “Advanced templating”](#advanced-templating) Both the `instructions` frontmatter and the body are full [LiquidJS](https://liquidjs.com/tags/overview.html) templates: conditionals, loops, and [filters](https://liquidjs.com/filters/overview.html) all work. A single action can adapt to where the copy came from: ```markdown --- id: context-aware label: Context aware --- {% if url contains "github.com" %} Review this code and point out the single biggest risk: {% elsif app_name == "Slack" %} Summarize this chat thread in 2 lines: {% else %} Explain this in {{ locale }}: {% endif %} {{ text | truncate: 8000 }} ``` ## Logs [Section titled “Logs”](#logs) Structured logs (secrets and copied content redacted) go to the terminal in dev and to a rotating file in release: * Windows `%LOCALAPPDATA%\app.zencopy\logs` * macOS `~/Library/Logs/app.zencopy/` * Linux `~/.local/share/app.zencopy/logs` # FAQ > Costs, privacy, clashes with other apps, and troubleshooting. ## Does it cost money? [Section titled “Does it cost money?”](#does-it-cost-money) ZenCopy itself is free, open-source software (Apache-2.0). There is no account and no subscription. What the AI service charges is between you and that service. With [Google’s free tier](/en/getting-started/#prepare-a-free-ai-key), it is completely free — unless you register a payment method, you cannot be charged. And with an AI that runs entirely on your own computer (Ollama, for example), there is no external service to pay in the first place. ## Where does my copied content go? [Section titled “Where does my copied content go?”](#where-does-my-copied-content-go) Only when you copy twice does the content go **directly to the AI service you configured** — and nowhere else. There is no ZenCopy server, no relay, and no usage tracking (telemetry). Your API key never leaves your machine either. ## Does an ordinary copy trigger anything? [Section titled “Does an ordinary copy trigger anything?”](#does-an-ordinary-copy-trigger-anything) No. A single Ctrl/⌘ + C starts nothing, reads nothing, and sends nothing. Only two copies in quick succession are the signal. Even then, clipboard content marked confidential by other apps (password managers, for example) is ignored. ## How much can I trust the AI’s answers? [Section titled “How much can I trust the AI’s answers?”](#how-much-can-i-trust-the-ais-answers) AI can be fluently wrong. It is genuinely useful for grasping the gist of a text, but for numbers, names, and anything consequential — contracts, medical text — check against the original before acting on it. ## How is this different from other “AI on selection” tools? [Section titled “How is this different from other “AI on selection” tools?”](#how-is-this-different-from-other-ai-on-selection-tools) Most tools in this space are macOS-only, work on selected text only, and are tied to one vendor’s AI or a subscription. ZenCopy runs on **Windows, macOS, and Linux**, handles **text, rich text, images, and files**, and lets **you choose the AI service** (OpenAI / Google / Anthropic / a corporate gateway / local Ollama). [Which action runs is also yours to decide](/en/configuration/#routingjson). No account, no subscription, no telemetry — open-source software. ## Another app also reacts to Ctrl/⌘ + C + C (e.g. DeepL) [Section titled “Another app also reacts to Ctrl/⌘ + C + C (e.g. DeepL)”](#another-app-also-reacts-to-ctrl--c--c-eg-deepl) No app can own the “copy twice” signal at the OS level. If another app is listening for the same signal (DeepL is the well-known one), **both** react and two popups appear. ZenCopy neither intercepts nor blocks any key events, so nothing breaks — that is the whole symptom. Disable the shortcut in whichever app you use less (for DeepL: Settings → General → shortcut for translating). ## The popup never appears (macOS) [Section titled “The popup never appears (macOS)”](#the-popup-never-appears-macos) Almost certainly permissions. Allow **Input Monitoring** for ZenCopy under System Settings → Privacy & Security, then quit and restart the app. (That permission is how the app notices that copy was pressed twice.) ## No result comes back / it says it timed out [Section titled “No result comes back / it says it timed out”](#no-result-comes-back--it-says-it-timed-out) If the response goes silent for 90 seconds, ZenCopy fails the run instead of waiting forever. Check your internet connection and the AI service settings (API key and so on), then press **Retry**. A local AI can take a while to load the first time, which is why the timeout is deliberately generous. ## Where are the logs? [Section titled “Where are the logs?”](#where-are-the-logs) * Windows `%LOCALAPPDATA%\app.zencopy\logs` * macOS `~/Library/Logs/app.zencopy/` * Linux `~/.local/share/app.zencopy/logs` Logs never contain your copied content or API keys. ## What does uninstalling remove? [Section titled “What does uninstalling remove?”](#what-does-uninstalling-remove) * Windows The uninstaller asks with a **Delete application data** checkbox — checking it removes everything: settings, API keys, custom actions, logs, and the webview profile. (One harmless leftover whether or not you check it: if launch-at-login was enabled, a registry entry pointing at nothing may remain — Windows ignores entries whose target does not exist.) * macOS Dropping the app in the Trash does not delete its data — that is the macOS convention, and ZenCopy follows it. For a full wipe, first run **Settings → Reset all settings** (removes all settings including API keys; logs stay for diagnostics, so delete `~/Library/Logs/app.zencopy` by hand for a truly clean slate), then trash the app. * Linux Package managers remove the app only; user data stays — also the Linux convention. For a full wipe, first run **Settings → Reset all settings**, then remove the package or AppImage. The GNOME trigger extension can be removed with `gnome-extensions uninstall copycopy@sincekmori.github.io`. ## Which Linux environments are supported? [Section titled “Which Linux environments are supported?”](#which-linux-environments-are-supported) **GNOME on Wayland, and X11.** On GNOME Wayland, background processes cannot observe keys or the clipboard by design, so ZenCopy (via the [`copycopy`](https://crates.io/crates/copycopy) crate) ships a small GNOME Shell extension that detects the double copy from inside the compositor. It is auto-installed into your user profile on first launch (no sudo) and becomes active after logging out and back in once. On X11, an ordinary passive key listener works, as on Windows. Other Wayland compositors (KDE Plasma, wlroots-based) offer no unprivileged way to observe the trigger and are not supported yet — the app runs, but the trigger stays inert. ## The tray icon does not show up (Linux) [Section titled “The tray icon does not show up (Linux)”](#the-tray-icon-does-not-show-up-linux) ZenCopy’s tray icon uses the AppIndicator protocol. Ubuntu’s GNOME supports it out of the box, but vanilla GNOME (Fedora, for example) shows nothing until the **AppIndicator and KStatusNotifierItem Support** Shell extension is installed. Either way the app itself works — the tray menu is just one way in. # Getting started > From installing to preparing a free AI key to your first copy-twice. If you can use a computer, you can set this up. If you know how to copy, you can use ZenCopy. There is exactly one thing to learn — **your usual copy, pressed twice, quickly**. That alone makes a summary, a translation, an explanation, or a polished rewrite of whatever you selected appear in the corner of your screen. It works the same on top of any app. ## What ZenCopy does for you, every day [Section titled “What ZenCopy does for you, every day”](#what-zencopy-does-for-you-every-day) * Select a long report or article and get **just the key points, in a few lines** * Turn a foreign-language page or chat **into your language, on the spot** * Have unfamiliar terms, error screens, or contract language **explained in plain words** * Hand over a rough draft of an email or essay and get it **cleaned up** The steps are always the same: select, then copy twice. No switching apps, no hunting for a place to paste. ## What you need [Section titled “What you need”](#what-you-need) 1. **A computer** — ZenCopy runs on Windows, macOS, and Linux. (For what counts as supported Linux, see the [FAQ](/en/faq/#which-linux-environments-are-supported).) 2. **A Google account** — you will create one long string called an “API key” to use the AI for free. If that term is new to you, don’t worry: this page walks you through it step by step. ## Install [Section titled “Install”](#install) Download the installer for your OS from [GitHub Releases](https://github.com/sincekmori/zencopy/releases/latest): * Windows Download and run [ZenCopy\_0.6.0\_x64-setup.exe](https://github.com/sincekmori/zencopy/releases/download/v0.6.0/ZenCopy_0.6.0_x64-setup.exe). You may see a “Windows protected your PC” screen. That is a one-time check Windows shows for new apps it does not know yet — choose **More info → Run anyway**. * macOS Open [ZenCopy\_0.6.0\_universal.dmg](https://github.com/sincekmori/zencopy/releases/download/v0.6.0/ZenCopy_0.6.0_universal.dmg) and drag ZenCopy into your **Applications** folder. On first launch, macOS asks once whether to open an app downloaded from the internet — choose **Open**. * Linux Download [ZenCopy\_0.6.0\_amd64.AppImage](https://github.com/sincekmori/zencopy/releases/download/v0.6.0/ZenCopy_0.6.0_amd64.AppImage), make it executable (`chmod +x`), and run it. This is the format with in-app updates. [ZenCopy\_0.6.0\_amd64.deb](https://github.com/sincekmori/zencopy/releases/download/v0.6.0/ZenCopy_0.6.0_amd64.deb) and [ZenCopy-0.6.0-1.x86\_64.rpm](https://github.com/sincekmori/zencopy/releases/download/v0.6.0/ZenCopy-0.6.0-1.x86_64.rpm) packages exist too, but updating those means reinstalling a new release. When a new version comes out, ZenCopy finds it by itself and offers a one-click update. Instructions for building from source live in the [GitHub repository](https://github.com/sincekmori/zencopy). ## Prepare a free AI key [Section titled “Prepare a free AI key”](#prepare-a-free-ai-key) ZenCopy itself is free, but the actual summarizing and translating is done by an external AI — the same kind of AI you may already use through Gemini or ChatGPT. The key that lets your own app use such an AI is an **API key** — one long string. Think of it like a house key: **it is yours alone, and you never show it to anyone**. That is all you need to remember about it. The easiest option is Google’s free key: 1. Open the [API keys page in Google AI Studio](https://aistudio.google.com/api-keys) and sign in with your Google account. 2. Press the **Create API key** button. 3. Copy the long string that appears (it starts with `AIza…`). That is your API key. For personal use the free tier is enough, and it is **completely free: unless you register a payment method, you cannot be charged**. If you ever reach the free tier’s limit, nothing is billed — requests simply pause for a while. One thing worth knowing: **on Google’s free tier, what you send may be used to improve their services** (per Google’s terms). If you handle confidential work documents, switch to a paid setup or pick [another AI or a local one](/en/configuration/). ## First launch [Section titled “First launch”](#first-launch) 1. Starting ZenCopy does not open a window right away. It settles into the small icon area at the edge of your screen (the bottom-right of the taskbar on Windows, the menu bar at the top on a Mac). 2. On the very first launch, a short welcome screen opens. Paste the API key you just copied and press **Start with this key**. **Setup is complete.** 3. What you copy is sent **directly** to the AI service you configured. There is no relay server in between, and no usage tracking. To use an AI other than Google (OpenAI, Anthropic, a corporate gateway, local Ollama, and so on), choose **Set up another way** and pick it in Settings. ### About permissions [Section titled “About permissions”](#about-permissions) * Windows Nothing to set up. It works right after launch. * macOS On macOS, the app needs one permission so it can notice that copy was pressed twice: * **System Settings → Privacy & Security → Input Monitoring** — allow ZenCopy It exists so the app can notice the **signal** — not so it can read your screen. After allowing it, quit ZenCopy once and start it again. * Linux No permission prompts. On GNOME (Wayland), the first launch auto-installs a small GNOME Shell extension into your user profile (`~/.local/share/gnome-shell/extensions/`, no sudo) — only something inside the compositor can detect a double copy there. GNOME loads new extensions at login, so **log out and back in once** after the first launch. Until the extension is active, the welcome and settings screens keep reminding you. On X11 it works right after launch. ## Try it [Section titled “Try it”](#try-it) Once you are set up, you can try it on this very page. Select any paragraph and press **Ctrl/⌘ + C + C** (copy, twice, quickly). The video shows it running on the text of a web page: [Watch the demo video](/demo/zen.en.mp4) ## Everyday use [Section titled “Everyday use”](#everyday-use) 1. Select text in any app and press **Ctrl/⌘ + C + C**. 2. A popup appears in the corner of your screen and the result streams in. 3. The label above the result (“Zen”, “Translate”, …) is a **switcher**. Click it to run a different action on the same copied content. Results you have already seen are kept, so switching back is instant — only **Retry** runs an action again. Press the ☆ next to a label to make that action your new default. 4. From the popup you can **Stop** a running action, **Retry**, or **Copy** the result. Close it with **Esc** or a click outside. 5. Closed a result too soon? **Show App** in the tray menu brings the last one back anytime. Four actions come built in: **Zen** (condense to one sentence), **Explain** (make it understandable), **Translate** (into your language), and **Polish** (clean up a draft). Adding your own takes nothing more than a name and a description of what you want done (see [Configuration](/en/configuration/)). And it is not just text. Screenshots and copied files (images, PDFs, audio, text files) work with the same gesture. Before an image or another binary file is sent, ZenCopy asks you once to confirm. ## Designed to be safe [Section titled “Designed to be safe”](#designed-to-be-safe) * **An ordinary single copy does nothing.** Nothing is read, nothing is sent. * Clipboard content marked confidential by other apps (password managers, for example) is ignored even on a double copy. * Content goes only to the AI service you configured yourself. ## Next [Section titled “Next”](#next) * [Configuration](/en/configuration/): popup position, themes, and building your own actions. * [FAQ](/en/faq/): costs, clashes with other apps, and troubleshooting. # Are you an LLM? > The ZenCopy documentation in plain Markdown for AI readers: llms.txt, llms-small.txt, and llms-full.txt. If you’re an artificial intelligence reading these docs — or a human teaching one about ZenCopy — you don’t have to parse our HTML. The full documentation is served as plain Markdown, in three sizes: * [llms.txt](/llms.txt) — a table of contents with links, the standard entry point * [llms-small.txt](/llms-small.txt) — the docs, abridged for small context windows * [llms-full.txt](/llms-full.txt) — every page in one file These follow the [llms.txt convention](https://llmstxt.org/) and are regenerated on every deploy, so they always match the pages a human sees. Were you asked to write a ZenCopy action? [llms-full.txt](/llms-full.txt) has the action file format, the template variables, and the routing rules — reply with one complete action file in a single code block. # Privacy > What leaves your device, what stays, and who else is involved. ZenCopy is a local desktop app. It has no server, no account, and no telemetry. ## What leaves your device [Section titled “What leaves your device”](#what-leaves-your-device) When you press the trigger (Ctrl/⌘ + C + C), the captured clipboard content is sent directly to the LLM provider *you* configured — nothing else, and nowhere else. What exactly is sent depends on the action that runs: * The rendered prompt, which can embed the capture’s context as [template variables](/en/configuration/#actionsmd): the copied text and markup, the source app’s name and window title, the page URL, the date, and your locale. * For an image or copied files, the content itself is attached (up to 10 MB per capture) — and for files, their full paths. By default the popup asks before sending these. A single normal copy is never captured and never sent. Clipboard content that other apps mark as sensitive (e.g. password managers) is ignored. Separately from captures, checking for updates asks GitHub for release metadata — never any of your content. ## What stays on your device [Section titled “What stays on your device”](#what-stays-on-your-device) * Your API keys (`ai-sdk-catalog.json` in the app config dir — never bundled, never uploaded). * Your settings (theme, language, popup position, …). * Log files. Logs redact secrets and never include copied content or API keys. * Usage statistics (a settings toggle, on by default): which action ran on which kind of capture, plus the model and token counts, so your costs stay computable. Kept in a local file only — never the copied content, never sent anywhere. ## Third parties [Section titled “Third parties”](#third-parties) Your use of an LLM provider is governed by that provider’s own terms and privacy policy. ZenCopy adds no intermediary: your content goes only to the provider you configure, and its use and costs are your own. ## Don’t take our word for it [Section titled “Don’t take our word for it”](#dont-take-our-word-for-it) ZenCopy is open source (Apache-2.0). Every claim on this page can be verified against [the source code](https://github.com/sincekmori/zencopy). # Recipes > Copy-paste ai-sdk-catalog.json setups, from a single provider to roles across several. This page is for **power users** who edit config files directly. If you prefer to stay inside the app’s own screens, you will never need it. Copy-paste starting points for `ai-sdk-catalog.json`. Put the file in the [app config dir](/en/configuration/#config-files-for-power-users); edits apply on the next trigger. ## One provider, one model [Section titled “One provider, one model”](#one-provider-one-model) What the settings UI writes — the whole file for most people: ```json { "$schema": "https://cdn.jsdelivr.net/npm/ai-sdk-catalog/schema.json", "providers": [ { "id": "openai", "vendor": { "apiKey": "sk-…" }, "models": [{ "id": "gpt-5.6-luna" }] } ], "roles": { "default": "openai:gpt-5.6-luna" } } ``` The `$schema` line is optional; editors that understand JSON Schema use it to validate and autocomplete the file as you type. ## Local Ollama — nothing leaves your machine [Section titled “Local Ollama — nothing leaves your machine”](#local-ollama--nothing-leaves-your-machine) ```json { "providers": [ { "id": "ollama", "vendor": { "id": "openai-compatible", "baseURL": "http://localhost:11434/v1" }, "models": [{ "id": "gemma4:e4b" }] } ], "roles": { "default": "ollama:gemma4:e4b" } } ``` Any OpenAI-compatible endpoint works the same way — LM Studio, llama.cpp, a corporate gateway: change the vendor’s `baseURL` (and add `apiKey` next to it if the endpoint wants one). A role is `"provider:model"`, split at the first `:` — which is why `"ollama:gemma4:e4b"` works even though the model id contains a colon. ## Two roles: fast by default, smart on demand [Section titled “Two roles: fast by default, smart on demand”](#two-roles-fast-by-default-smart-on-demand) Roles decouple actions from models. Actions name a role (`role: smart` in the action’s frontmatter); which model that means is decided here — swap it any time without touching actions. ```json { "providers": [ { "id": "google", "vendor": { "apiKey": "AIza…" }, "models": [{ "id": "gemini-3.1-flash-lite" }] }, { "id": "anthropic", "vendor": { "apiKey": "sk-ant-…" }, "models": [{ "id": "claude-opus-4-8" }] } ], "roles": { "default": "google:gemini-3.1-flash-lite", "smart": "anthropic:claude-opus-4-8" } } ``` That is as far as ZenCopy-specific setups go. The file format itself belongs to [ai-sdk-catalog](https://github.com/sincekmori/ai-sdk-utils/tree/main/packages/catalog#readme) — gateways, per-model settings, and the rest are documented there, with ready-made configs at three sizes in [`examples/`](https://github.com/sincekmori/ai-sdk-utils/tree/main/packages/catalog/examples). # Terms > The short version of using free, open-source software responsibly. ZenCopy is free, open-source software distributed under the [Apache License 2.0](https://github.com/sincekmori/zencopy/blob/main/LICENSE). * **No warranty.** ZenCopy is provided *as is*, without warranty of any kind — see sections 7 and 8 of the license for the authoritative wording. * **Your provider, your costs.** ZenCopy calls the LLM provider you configure with your own key. All usage and the resulting costs are yours, including unexpected charges caused by bugs, retries, large inputs, or misconfiguration. * **Your content, your call.** Whatever you copy-copy is sent to that provider. Do not use ZenCopy on data you may not share with it. Each provider’s own terms and privacy policy also apply. * **Verify the output.** AI results can be inaccurate or misleading; check them before you rely on them. See also: [Privacy](/en/privacy/).