Chataway Developers
Concepts

Storage zones

Decide what agents may see of your app's own storage — internal, read-only or the user's — what sealed files are, and the honest rule that zones protect integrity, not secrets.

Your app keeps files in its own storage, one folder per project. With app API 4, agents can see that storage too: an agent run on the storage root, another app you hand a file to, and — as far as Chataway can control it — the user's chat agent. Storage zones say which parts they may read or change.

Zones never limit your own code. Your panel's fs calls on storage and a local app's ctx.storage see everything.

#Declare zones

plugin.json
json
{
  "requires": { "hostApi": 4 },
  "storage": {
    "default": "internal",
    "zones": [
      { "path": "exports/", "zone": "user" },
      { "path": "templates/", "zone": "readonly" },
      { "path": "cache/", "zone": "internal" }
    ]
  }
}
ZoneAgent runsOther appsThe user's chat agent
internalCan't see itA plugin-file: path into it is refused, unless your app handed that file outKept out of it (best effort)
readonlyRead, not writeCan be handed the fileNot limited
userRead and writeCan be handed the fileNot limited
FieldRules
storage.defaultinternal or user: the zone of every path no zone names. Omitted: internal for requires.hostApi ≥ 4. (Versions at app API 3 behave as user, as before.)
storage.zones[]Up to 20. path is a relative folder ending with /. The longest matching prefix wins, so exports/private/ can be internal inside a user exports/. Paths match the way macOS and Windows compare names (case and Unicode look-alikes fold): DB/x is in the db/ zone.
zones[].sealedtrue only on internal zones, and only for apps with server code. See Sealed files.

storage needs requires.hostApi ≥ 4.

#The user's work is the user's

Put what the user made — exports, documents, anything they'd expect to keep — in a user zone. Those files stay exportable and agents can work on them. Use internal for your app's own data: caches, indexes, state. Reviewers check this.

#Files you hand out stay valid

Zones govern browsing by path. A file your app gave away — returned from a tool, kept with files:return, attached with chat.compose — was shared by your app, so its ref keeps working wherever it went, even if it sits in an internal zone. Chataway records each file you hand out and lets those refs through.

#Sealed files

An internal zone with "sealed": true is encrypted at rest. Apps with server code (local apps and verified local apps) write and read it with:

ts
await ctx.storage.writeSealed('db/session.json', JSON.stringify(state));
const state = JSON.parse((await ctx.storage.readSealed('db/session.json')).toString('utf8')); // a Buffer

Both work only on paths inside a sealed zone. The files are AES-256-GCM, with a key for your app derived from Chataway's secrets vault; a file sealed by another app, or changed on disk, doesn't open. Reading the file from disk gives ciphertext. A cloud app has no code on the Mac to hold a key, so sealed in a cloud app is the error storage.sealed-cloud.

#The user's chat agent

Chataway also asks the user's own chat agent to leave your internal zones alone. This is a guardrail, not a wall:

  • Claude Code chats are started with rules that deny reading and editing files in those folders.
  • Chataway's own chat gets the same rules, and also refuses file reads, writes and searches inside them, and shell commands that name them.
  • Other providers get nothing. And any shell can read the user's own files.

It covers every app that is on in the project. A version below app API 4 has no zones: all of its storage is the user's.

#Zones protect integrity, not secrets

Everything in your app's storage is on the user's Mac, in a folder the user owns. Zones keep agents from changing your internals by accident or because a document told them to. They don't hide anything from the person who owns the computer, or from a program they run. Sealed files are harder to read, but your app has to decrypt them on that same Mac.

So keep secrets where only you can reach them:

  • Prompts and logic you don't want copied run on your server, behind your MCP tools. Call them from your panel or your tools; don't ship them in your bundle or your storage.
  • API keys never go in the bundle or storage. Use connected accounts for the user's access to your service, and your server for your own keys.
  • Proprietary data stays on your server. Send the user results, not the data set.

#In the mock host

The mock host gives your panel a storage root (seed it with fs: { storage: { … } }). It doesn't apply zones — zones are about agents, and the mock's fake agent runs are only a stand-in. Test zones with chataway dev in Chataway.