matter.json

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

{
  "app": "<app id, written by matter app 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-app.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
app	The app’s id. matter app create writes it. Commands use it unless you pass --app <id>.
build	A shell command matter app 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 app dev starts, such as npm run dev.
dev.url	The address your dev server answers on.
dev.worker	The command matter app dev runs your dev worker with, such as npm run dev:worker.
types	Where matter app types writes the app’s types. The default is matter-app.d.ts beside matter.json.
signingKey	The key matter app 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 app, like "0.4.0". matter app create writes the version you’re on.
maxMatterVersion	Optional. The newest Matter the app is known to run on. Rarely needed.

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

Pages

pages lists the app’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 app, 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 app’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 app 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 app 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 app 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 app there.
tools	An MCP server (stdio) that the app’s routine runs get.
run	A local HTTP server behind the app’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 app up, on the computer they choose. app: one routine for the whole app, on the app’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 app’s. If their computer isn’t signed in to the app’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.