Security & privacy
What a Chataway app can and cannot do, what it learns about users, and how to keep your app's data use minimal and honest.
Chataway runs next to people's source code, credentials and client work. The platform is designed so that installing an app is a small, understandable decision — and your app's reputation depends on keeping it that way.
Most of this page is about store apps (cloud apps). Code that runs on the Mac — your own local apps and apps installed from GitHub — has a different, more powerful trust model; it's summarised below and detailed in Isolation & permissions.
#What a store app can do
| A store app can… | How |
|---|---|
| Offer tools to the agent | Declared in contributes.tools, served by your MCP server |
| Receive files the user or agent passes to it | files:receive, per-owner consent, accept / maxBytes enforced |
| Have Chataway transform those files | host:media, fixed operations only |
| Return files into its own storage | files:return |
| Offer files for the project | Galleries of returned files have Save to project; project:write is for asking to save directly, always behind a card |
| Ask the user for approval or input | confirm, elicitation (form cards) |
| Act as the user on your service | A connected account's token, for tools that declare account |
| Show a UI | A sandboxed panel, network limited to remote.domains |
| Keep settings | Declared settings, stored by Chataway |
| Use the user's AI | models (app API 4): a tier hint, never a model id or key; metered per day, with a limit the user sets |
| Work on files in place | folders (app API 4): folders the user grants (each one you declare), or one file they open with the app |
| Run a small agent | agent (app API 4): file tools on the granted roots, no shell, no web, started by a click, visible in Activity |
| Start chats | chats (app API 4): chats tagged with the app, created from a click |
#What a store app cannot do
- Run code on the Mac. No executables, no background processes, no shell. The only code is your panel's JavaScript, in a sandboxed iframe.
- Read the project or the disk. No paths, no
project:read. Only files explicitly handed over reach you, and — withfolders— the folders the user granted, limited to your file types..envfiles, keys and.git/are never visible, even inside a granted folder, and symbolic links can't lead out of it. Hidden files and folders and agent instruction files (CLAUDE.md,AGENTS.md…) can't be changed from an app. A folder grant holds only in the workspace it was given in, and switching the app off or uninstalling it forgets its grants. Secret-file and zone checks compare names the way macOS and Windows do (case and Unicode look-alikes fold). - See which model, key or path is used. Model calls take a tier and return a label; files move as refs and roots, never absolute paths.
- Talk to arbitrary hosts. The panel's CSP and Chataway's downloads are limited to your declared domains.
- See the conversation. Your server sees tool calls and their arguments — not the chat, not the user's other messages, not other apps' tools.
- Act without a gesture. Anything with consequences waits for the user on a card. The agent can't approve your cards; only the user can. In the panel, the methods that speak or act for the user —
chat.send,chat.create,chat.open,folders.request,fs.trash,agent.run— work only inside the user's click or key press in that panel (a click elsewhere in Chataway doesn't count), one call of each kind per click, and fail closed otherwise. A message a store app sends is shown to the user before it goes, until they allow that app to send. - Run agents nobody started. An agent run starts from a click, uses only file tools on its roots (and your tools, if you ask), shows in Activity, and the user can stop it.
- Hold secrets on the Mac. No
secrets, no client secrets. Tokens stay in Chataway's vault. - Impersonate. Cards are drawn by Chataway with your icon and name — never another app's, never Chataway's.
These limits are enforced three times: by the validator, by the store on upload, and by the desktop installer.
#Storage zones protect integrity, not secrets
Storage zones keep agents from reading or changing your app's internal files. They don't hide anything from the person who owns the Mac: everything in your bundle and your storage is on their disk, and their own shell can read it. Keep prompts you don't want copied, API keys and proprietary logic on your server.
#Local apps and apps from GitHub
Local apps run their own code on the Mac, so the store's guarantees above don't apply to them. What users get instead is honesty about where the code came from:
| Where it came from | What it may do | Label |
|---|---|---|
| The user's own app project or linked folder | Everything Chataway may do, unless they switch on Run isolated | DEV |
| GitHub or npm | Its declared grants, enforced in its own process — read its own folder and storage, write only its storage, reach only network.domains, start programs only with exec | Unverified · Isolated |
| A hosted MCP server added by URL | Its tools run on that service, under the user's account | Connector |
Three rules hold for all of them:
execmeans full access to the Mac — programs it starts inherit Chataway's macOS privacy permissions (screen recording, mouse and keyboard, if granted). Chataway says so on the install screen, isolated or not. More- Nothing silent. Installs are pinned to a commit; updates show a diff and wider access needs consent again; a GitHub app is off in every project until the user turns it on.
- The user's own agent can read it first (Check with my agent), and Chataway can revoke a repository's bad commits on every Mac.
Connectors ask before every tool call that isn't marked read-only, unless the user turns that off. See Connectors.
#What you learn about users
On every call your server receives:
| Header | Value |
|---|---|
Authorization | Bearer <token> — only for tools that declare account. Identifies the user on your service. |
X-Chataway-Project | An opaque pseudonym for the project |
X-Chataway-Chat | An opaque pseudonym for the chat (tool calls) |
The pseudonyms are an HMAC over your app id and Chataway's internal id, keyed with a secret generated on the user's Mac. They're stable — the same project always has the same pseudonym for your app on that Mac — so you can use them to keep per-project state. But:
- two apps get different pseudonyms for the same project, so apps can't correlate users with each other,
- they can't be reversed into Chataway ids,
- they differ between the user's Macs (the key never leaves the machine) — for anything that must follow the user, use your own account id,
- they don't prove a request came from Chataway (anyone can send headers) — authenticate with the account token, and treat pseudonyms as untrusted partition keys.
You never receive the user's Chataway account, email, device, IP-derived location beyond what any HTTPS request reveals, file paths, or project names.
#Data minimization
Reviewers read your listing, your permissions and your privacy policy (linked from your homepage) next to your manifest. Keep them consistent:
- Collect only what the tool needs. If a tool takes a title, don't also ask the agent for "context".
- Process and forget. Delete received files once you've done the job, unless keeping them is the point (an upload tool).
- Say it on the card. If data leaves the user's control — uploaded publicly, sent to a third party — say so in the
confirmbody. - No training on user content without an explicit, separate opt-in on your own service.
- No selling or sharing of data received through Chataway.
#Securing your server
- HTTPS only, with a valid certificate.
mcpUrlmust behttps. - Authenticate every call that touches user data with the account token. Return
401for bad tokens. - Validate arguments — they're written by an AI agent following a user's request, possibly one crafted by a malicious document the agent read. Treat them like any untrusted input.
- Be careful with what your results say. Tool results are read by the agent. Don't echo untrusted third-party content in a way that reads like instructions to it.
- Rate-limit per user on your side too.
- Ask the user's AI for the user's work. Sampling uses your app's daily limit on their computer. Don't put secrets or prompts you'd mind them reading in sampling requests — they run on the user's provider, under the user's account.
- Keep your domain list short. Every domain you add widens what your panel can reach, and needs review.
#Reporting a vulnerability
Found a security issue in Chataway or the app platform? Tell us privately from the developer dashboard rather than in public.
Users can report an app from its store page; reports go to the review team, who can suspend a listing or yank a version — which disables it on every Mac within the hour.