A complete reference for .trevize/settings.json.
For explanations and examples, see the Configuration guides.
Top-level
| Field | Type | Required | Description |
|---|---|---|---|
$schema |
string | no | JSON schema URL, for editor autocomplete and validation. |
workspaceId |
string | no | The Trevize workspace this project belongs to (used by the MCP server). |
projectId |
string | no | The org/repo identifier. Can be auto-detected from the git remote. |
hooks |
object | no | Lifecycle hook commands. See hooks. |
preview |
object | no | Preview targets and processes. See preview. |
resources |
object | no | Managed resource declarations. See resources. |
The file is read from .trevize/settings.json (canonical) or the legacy
.tervezo/settings.json (deprecated fallback).
hooks
Commands run at sandbox lifecycle points. See Hooks.
| Field | Type | Required | Description |
|---|---|---|---|
hooks.SandboxReady |
array of { command } |
no | Commands run in order once the sandbox is ready. |
…[].command |
string | yes | The shell command to run. |
SandboxReady is currently the only supported hook event.
preview
Declares how to serve your app. See Preview.
| Field | Type | Required | Description |
|---|---|---|---|
preview.targets |
map of name → target | yes | Named preview targets. |
preview.defaultTarget |
string | no | Target to launch by default. Must exist in targets. |
Target
A target uses either a processes array or the single-process
command + port shorthand.
| Field | Type | Required | Description |
|---|---|---|---|
processes |
array of process | conditional | Processes for a multi-process target. |
defaultProcess |
string | no | Process shown by default. Must match a process name. |
command |
string | conditional | Shorthand: command for a single-process target. |
port |
number | conditional | Shorthand: port for a single-process target (1–65535). |
cwd |
string | no | Working directory shared by all processes in the target. |
env |
map of string → string | no | Literal env vars shared by all processes. |
secretEnv |
map of string → string | no | Secret env vars (var → workspace secret key) for all processes. |
Process
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | yes | Unique name within the target (e.g. web, api). |
command |
string | yes | Shell command to start the process. |
port |
number | yes | Port the process listens on (1–65535). |
cwd |
string | no | Working directory, relative to the sandbox home. |
env |
map of string → string | no | Literal env vars (merged on top of the target’s env). |
secretEnv |
map of string → string | no | Secret env vars, resolved from workspace secrets. |
Interpolation variables
env values may reference ${VAR}:
| Variable | Description |
|---|---|
${PREVIEW_URL} |
The preview’s base URL. |
${PREVIEW_HOST} |
The preview’s host. |
${PREVIEW_URL_<PROCESS>} |
A specific process’s URL (uppercase process name). |
${PREVIEW_HOST_<PROCESS>} |
A specific process’s host. |
| resource variables | e.g. ${NEON_DATABASE_URL} — see resources. |
resources
Declares managed resources to provision per run. See Resources.
| Field | Type | Required | Description |
|---|---|---|---|
resources.<id> |
object | no | Keyed by integration id (neon, supabase). |
resources.<id>.env |
map of string → string | no | Maps <your app's variable> → <the variable Trevize provides>. |
Provided variables
| Resource | Injected variables |
|---|---|
neon |
NEON_DATABASE_URL, NEON_BRANCH_ID |
supabase |
SUPABASE_DATABASE_URL, SUPABASE_BRANCH_ID, SUPABASE_BRANCH_REF |