---
title: "Overview & schema"
description: "How .trevize/settings.json configures a repository for Trevize — where it lives, how it's read, and its top-level keys."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.trevize.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview & schema

A repository tells Trevize how to set itself up, run, and preview through a
single versioned file: **`.trevize/settings.json`**. It lives in your repo, so
the configuration travels with your code and applies to every sandbox Trevize
creates for a [session](/concepts/sessions), [task](/concepts/tasks), or
[automation](/concepts/automations).

## Where it lives

Put the file at **`.trevize/settings.json`** in the root of your repository.

> **Legacy path**
>
> The older `.tervezo/settings.json` path is still honored as a fallback (with a
> deprecation warning), but **`.trevize/`** is canonical — prefer it for new
> repositories.

When a sandbox is created, Trevize reads this file for the repository and uses it
to run lifecycle hooks, start preview processes, and provision resources.

## Top-level keys

```json
{
  "$schema": "https://trevize.dev/schemas/settings.json",
  "workspaceId": "your-workspace-id",
  "projectId": "your-org/your-repo",
  "hooks": {},
  "preview": {},
  "resources": {}
}
```

| Key            | Purpose                                                                                     |
| -------------- | ------------------------------------------------------------------------------------------- |
| `$schema`      | Points at the JSON schema so editors can offer autocomplete and validation. Optional.       |
| `workspaceId`  | Identifies the Trevize workspace this project belongs to (used by the [MCP](/integrations/mcp) integration). |
| `projectId`    | Your `org/repo` identifier (can be auto-detected from the git remote).                       |
| `hooks`        | Commands to run at sandbox lifecycle points. See [Hooks](/configuration/hooks).              |
| `preview`      | Preview targets and processes that serve your app. See [Preview](/configuration/preview).    |
| `resources`    | Managed resources (e.g. a database) mapped into the sandbox. See [Resources](/configuration/resources). |

All keys are optional — include only what your repository needs. `hooks`,
`preview`, and `resources` are the parts that shape what happens inside a sandbox.

## Next

- **Hooks** — Run install/setup commands when the sandbox is ready.
[Configure hooks](/configuration/hooks).
- **Preview** — Serve your app so reviewers get a live preview.
[Configure preview](/configuration/preview).
- **Resources** — Wire a database branch into the sandbox.
[Configure resources](/configuration/resources).
- **Annotated example** — A complete, walked-through `settings.json`.
[See the example](/configuration/example).

For a field-by-field table, see the
[`settings.json` reference](/reference/settings-reference).

Source: https://docs.trevize.dev/configuration/settings-json/index.mdx