tc.json reference
tc.json is optional. Most folders deploy without it, because detection works out how to build and run them. Add it to override detection, to add cron or worker services, to declare integrations and buckets, or to explain to approvers why the app needs access. Put it in the root of the folder you deploy.
Example
{
"name": "vendors",
"services": {
"web": { "type": "web" },
"sync": { "type": "cron", "command": "node sync.js", "schedule": "0 2 * * *" }
},
"integrations": { "graph": ["sites.selected:Procurement:read"] },
"storage": { "buckets": { "exports": "app-public" } },
"purpose": "Nightly copy of the Procurement site's Vendors list into Postgres so Finance can join vendors with spend data."
}
Top-level fields
| Field | Type | Description |
|---|---|---|
name | string | Project name used by the CLI when --project isn't given |
type | web | api | static | Service type of the primary service |
path | string | Subfolder holding the primary service's source; must stay inside the folder |
build | string | Build command, for example npm run build |
start | string | Start command for container services |
out | string | Static output folder after the build, for example dist |
port | integer | Port the app listens on (1–65535). Default 8080; $PORT is set to it |
services | object | Named services; see below |
integrations | object | Integration scopes the app needs; see below |
storage | object | Buckets to create on deploy; see below |
purpose | string | One line for approvers: why the app needs its integrations |
access | object | { "groups": [...] }. Parsed but not applied: set access in the console, with tc access set or with MCP set_access |
Top-level service fields (type, path, build, start, out, port) describe the primary service. They take precedence over the primary entry in services.
services
A map of service name to service config. A project has one primary service (web, api or static) and any number of cron and worker services.
| Field | Applies to | Description |
|---|---|---|
type | all | web, api, static, cron or worker |
path | all | Subfolder with this service's source |
build | primary | Build command |
start | container services | Start command |
out | static | Output folder to publish |
port | web, api | Listening port |
command | cron, worker | What to run, for example node sync.js. Defaults to start |
schedule | cron | Five-field cron expression in UTC, for example 0 7 * * 1 |
Rules:
- Cron and worker service names are 1–20 characters: lowercase letters, digits and dashes, starting with a letter.
- Every cron and worker service needs a
command(orstart); every cron service needs a validschedule. - More than one
web/api/staticservice is refused. Deploy a second web service as its own project for now. - A cron or worker whose
pathis the primary service's folder (nopathwhen the primary has none) reuses the primary service's image; any otherpathis built on its own. Give it its ownpathwith apackage.json,requirements.txtorDockerfilewhen the primary service is a static site.
integrations
Maps an integration name from your organization's catalog to a list of scopes:
{
"integrations": {
"salesforce": ["Case:read", "Account:read"],
"erp": ["ar.aging:read", "ar.invoices:read"],
"graph": ["mail.send:owner"],
"teams": ["notify:role:approver", "notify:Finance - Accounting"]
}
}
You don't have to list everything: the deploy also scans your code for SDK calls. Declaring scopes makes the request precise and lets you ask for access before the code that uses it exists. Scope formats differ per integration; see Integrations.
storage
Buckets the app uses, created on deploy if missing. A deploy never deletes a bucket.
{
"storage": {
"buckets": {
"receipts": { "visibility": "private", "readRoles": ["approver"] },
"exports": "app-public"
}
}
}
| Form | Meaning |
|---|---|
"name": "private" or "app-public" | A bucket with that visibility |
"name": { "visibility": ..., "readRoles": [...] } | Visibility (default private) and the app roles that can read every file in a private bucket |
Bucket names are 3–63 characters of lowercase letters, digits and dashes, without --. There is no internet-public option. See Storage.
purpose
One line, shown to approvers on every access request the deploy files. Write it for a person who doesn't know the app: what it does and for whom. MCP deploy requires a purpose (in the tool call or here) when something needs approval.
Validation errors
tc.json is validated on deploy and the build fails with a clear message, for example:
| Message | Fix |
|---|---|
tc.json is not valid JSON: … | Fix the JSON syntax |
services.sync is a cron service and needs a "schedule", e.g. "0 2 * * *" (UTC). | Add schedule |
services.sync (cron) needs a "command", e.g. "node sync.js". | Add command |
tc.json defines more than one web/api/static service; … | Keep one primary service |
tc.json "path" must stay inside the folder. | Use a relative subfolder |
storage.buckets.x: visibility is "private" or "app-public" (there is no internet-public option). | Fix the visibility |