---
title: "Project settings"
description: "Every project-scoped setting, and how repo-file config and Hoplite overrides resolve"
canonical_url: "https://hoplite.sh/docs/workspace/project-settings"
markdown_url: "https://hoplite.sh/docs/workspace/project-settings.md"
---

# Project settings
URL: /docs/workspace/project-settings
LLM index: /llms.txt
Description: Every project-scoped setting, and how repo-file config and Hoplite overrides resolve
Related: /docs/sandboxes/scripts, /docs/sandboxes/environment-variables, /docs/agent/mcp, /docs/agent/models

# Project settings

A **project** binds a repository and base branch; everything else — environment variables, scripts, model defaults — hangs off it. Project settings live under **Settings → Project**, and scripts and MCP servers can also ship in the repository itself via [`.hoplite/settings.json`](/docs/sandboxes/scripts).

## Settings pages

| Page | What's there |
| --- | --- |
| **Repository** | Name, description, repository and base branch |
| **Environment** | Preview port, [setup/run/archive scripts](/docs/sandboxes/scripts), [environment variables](/docs/sandboxes/environment-variables) |
| **Sandbox** | CPU and memory policy, plus the [Docker Compose workspace runtime](/docs/sandboxes) for projects that need a Compose stack |
| **MCP** | [MCP servers](/docs/agent/mcp) that extend the agent's tool catalog |
| **Agents** | [Model default](/docs/agent/models), reasoning effort, speed, instructions, and skills |
| **Danger zone** | Delete the project |

## How scripts and settings resolve

Scripts have two layers: the repo file and a Hoplite override layer editable under **Settings → Project → Environment**. Resolution order:

| Priority | Layer | Behavior |
| --- | --- | --- |
| 1 | **Hoplite override** | Wins if set, including `enabled: false` to disable a script |
| 2 | **Repo file** (`.hoplite/settings.json`) | Applies when the override is `null` |
| 3 | **Defaults** | `setup`, `run`, and `archive` exist with empty commands if neither layer defines them |

The agent can inspect and change this configuration too:

| Tool | What it does |
| --- | --- |
| `project_settings_get` | Prints exactly how each script and setting resolves across the two layers (repo file vs. Hoplite overrides) |
| `project_settings_update` | Proposes changes to project settings — always requires your approval |

## Scripts

Each script is `{ "enabled": boolean, "command": string | null }`; `enabled` defaults to `true`. See [Project scripts](/docs/sandboxes/scripts) for the full file reference.

| Script | When it runs |
| --- | --- |
| `setup` | After the repo is cloned, before the agent starts working — install dependencies, run migrations, seed data |
| `run` | When a [preview](/docs/sandboxes/previews) starts — your dev server command |
| `archive` | When a thread is archived — cleanup or state capture |
| `check` | Optional — a verification command (tests, typecheck) the agent can run |
| `diagnostics` | Optional — runs after each agent edit; `{FILE}` in the command is replaced with the edited file's path |

## Ports

| Setting | Default | Behavior |
| --- | --- | --- |
| `ports.preview` | `3000` | The port `preview_start` waits on and proxies |
| `ports.additional` | — | Names extra ports (e.g. an API server) so they're easy to reference |

Port numbers must be between 3000 and 9999.

## Sandbox runtime

**Settings → Project → Sandbox** holds the CPU and memory policy — effective ceilings for [resource scaling](/docs/sandboxes/resources) — and the **Docker Compose** option. Enabling Docker Compose starts new workspaces for the project in an isolated Modal VM runtime with a private Docker daemon; existing workspaces keep the runtime they already have. The daemon is not exposed directly to agents or project commands.

## MCP servers

Attach [MCP servers](/docs/agent/mcp) either under **Settings → Project → MCP** or through the `mcpServers` array in `.hoplite/settings.json`, so the config ships with the code. Both accept the same shape.

## Sitemap

See the full [sitemap](/docs/sitemap.md) for all pages.
Well-known sitemap: [/docs/.well-known/sitemap.md](/docs/.well-known/sitemap.md).