Skip to main content

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​

tc.json
{
"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​

FieldTypeDescription
namestringProject name used by the CLI when --project isn't given
typeweb | api | staticService type of the primary service
pathstringSubfolder holding the primary service's source; must stay inside the folder
buildstringBuild command, for example npm run build
startstringStart command for container services
outstringStatic output folder after the build, for example dist
portintegerPort the app listens on (1–65535). Default 8080; $PORT is set to it
servicesobjectNamed services; see below
integrationsobjectIntegration scopes the app needs; see below
storageobjectBuckets to create on deploy; see below
purposestringOne line for approvers: why the app needs its integrations
accessobject{ "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.

FieldApplies toDescription
typeallweb, api, static, cron or worker
pathallSubfolder with this service's source
buildprimaryBuild command
startcontainer servicesStart command
outstaticOutput folder to publish
portweb, apiListening port
commandcron, workerWhat to run, for example node sync.js. Defaults to start
schedulecronFive-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 (or start); every cron service needs a valid schedule.
  • More than one web/api/static service is refused. Deploy a second web service as its own project for now.
  • A cron or worker whose path is the primary service's folder (no path when the primary has none) reuses the primary service's image; any other path is built on its own. Give it its own path with a package.json, requirements.txt or Dockerfile when the primary service is a static site.

See Cron and worker services.

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"
}
}
}
FormMeaning
"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:

MessageFix
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
Was this page helpful?