matter.json

matter.json sits at the root of your project. The matter command reads it, and matter extension deploy sends what it declares (pages, setup, routines, processes and supported Matter versions) with each deployment, where the server checks it.

{
  "extension": "<extension id, written by matter extension create>",
  "minMatterVersion": "0.4.0",
  "build": "npm run build",
  "deploy": { "dir": "dist" },
  "dev": { "command": "npm run dev", "url": "http://localhost:5173", "worker": "npm run dev:worker" },
  "types": "src/matter-extension.d.ts",
  "pages": [
    {
      "label": "Today",
      "path": "/today",
      "badge": {
        "table": "Actions",
        "index": "by_sender_status",
        "eq": { "Sender": "$viewer", "Status": "proposed" }
      }
    },
    { "label": "Settings", "path": "/settings", "roles": ["owner", "admin"] }
  ],
  "setup": "/setup",
  "worker": "worker.mjs",
  "tools": "tools.mjs",
  "routines": {
    "research": {
      "scope": "member",
      "title": "Find prospects",
      "prompt": "routines/research.md",
      "schedule": "0 9 * * 1-5",
      "needs": ["browser"],
      "backend": "codex",
      "model": "gpt-6.1-sol"
    }
  }
}

Project fields

These tell the matter command how to work with your project. They aren’t part of the deployment.

Field	What it is
`extension`	The extension’s id. `matter extension create` writes it. Commands use it unless you pass `--extension <id>`.
`build`	A shell command `matter extension deploy` runs first, in the project folder.
`deploy.dir`	The folder to deploy, relative to the project. The default is the project itself, less what `.gitignore` and `.matterignore` leave out. A `dir` is deployed whole, even if git ignores it.
`dev.command`	The command `matter extension dev` starts, such as `npm run dev`.
`dev.url`	The address your dev server answers on.
`dev.worker`	The command `matter extension dev` runs your dev worker with, such as `npm run dev:worker`.
`types`	Where `matter extension types` writes the extension’s types. The default is `matter-extension.d.ts` beside `matter.json`.
`signingKey`	The key `matter extension deploy` signs with, by name or fingerprint, for a project the team signs with one key. The default is your own.

Matter versions

Field	What it is
`minMatterVersion`	Required. The oldest Matter that can run the extension, like `"0.4.0"`. `matter extension create` writes the version you’re on.
`maxMatterVersion`	Optional. The newest Matter the extension is known to run on. Rarely needed.

A computer outside the range shows “Update Matter to use App”, or that the extension doesn’t support this version yet, instead of opening it. See Matter versions.

Pages

pages lists the extension’s entries in the sidebar, in order. At most 30.

Field	What it is
`label`	The entry’s name, up to 60 characters.
`path`	A route of your extension, starting with `/`. Each page’s path is different. A route under a page’s path, like `/deals/123` under `/deals`, belongs to that page.
`roles`	Optional. Limits the page to these workspace roles: `owner`, `admin`, `member`, `guest`.
`badge`	Optional. A live count shown on the entry.

A badge counts rows of a table in the extension’s space, through one of its indexes:

table and index name them.
eq gives a value for each match field of the index: text, a number or true/false. "$viewer" means the member looking.

matter extension deploy warns you if a badge names a table or index that doesn’t exist.

Setup

setup is the route that the Set up button opens, for an extension whose member routines need input from each member. Build that page with matter.setup.

With "setup": null, or no setup, Set up creates the member’s routines directly.

Processes

worker, tools and run name JavaScript entry files (.js, .mjs or .cjs) inside the deployed folder. matter extension deploy stops if one is missing.

Field	What it is
`worker`	A Node process that runs on a member’s computer once they’ve opened the extension there.
`tools`	An MCP server (stdio) that the extension’s routine runs get.
`run`	A local HTTP server behind the extension’s pages. With it, Matter forwards page requests to your server instead of serving files.

See Worker, tools and run server.

Routines

routines is an object keyed by routine name: lowercase letters, digits, - and _. At most 30.

Field	What it is
`scope`	`member` (the default): one routine for each member who sets the extension up, on the computer they choose. `extension`: one routine for the whole extension, on the extension’s runner computer.
`title`	The routine’s name in Matter, up to 120 characters.
`prompt`	A `.md` or `.txt` file in the project, whose text becomes the routine’s prompt, or the prompt itself. Up to 65,536 characters.
`schedule`	A cron expression, such as `0 9 * * 1-5`. Leave it out for a routine that only runs on demand.
`needs`	What the runs need on the computer: `browser`, `computer`, or both.
`concurrency`	How many runs may go at once, from 1 to 10. The default is 1. Further runs wait their turn.
`backend` and `model`	The model the prompt is written for. `backend` is `codex` or `claude_agent_sdk`, and `model` names one of its models.
`thinking`	Optional, with a model: an effort name such as `low`, `medium` or `high`.
`speed`	Optional, with a model: `default` or `fast`.

A member’s own choice of model for the routine wins over the extension’s. If their computer isn’t signed in to the extension’s model, the run uses the member’s default model and is told why.

A run that needs computer fails on a computer where Computer Use is off, with a message saying to turn it on in Settings. See Routines and setup for running them from your pages.

Limits

The manifest, with its prompts, is at most 256 KB.
A deployment is at most 100 MB, and can’t contain symlinks.