---
title: "Project scripts"
description: ".hoplite/settings.json — setup, run, and archive scripts, ports, and override precedence"
canonical_url: "https://hoplite.sh/docs/sandboxes/scripts"
markdown_url: "https://hoplite.sh/docs/sandboxes/scripts.md"
---

# Project scripts
URL: /docs/sandboxes/scripts
LLM index: /llms.txt
Description: .hoplite/settings.json — setup, run, and archive scripts, ports, and override precedence
Related: /docs/sandboxes/previews, /docs/sandboxes/environment-variables, /docs/integrations/mcp

# Project scripts

Commit a `.hoplite/settings.json` to your repository to tell Hoplite how to set up and run your project. The agent uses these scripts through its `sandbox_setup` and `preview_start` tools — a project with working scripts gets a working dev server on the first try.

## The file

```json title=".hoplite/settings.json"
{
  "version": 1,
  "ports": {
    "preview": 3000,
    "additional": { "api": 8787 }
  },
  "scripts": {
    "setup": { "enabled": true, "command": "pnpm install && pnpm db:migrate" },
    "run": { "enabled": true, "command": "pnpm dev" },
    "archive": { "enabled": true, "command": "pnpm db:snapshot" }
  },
  "mcpServers": []
}
```

## Scripts

Each script is `{ "enabled": boolean, "command": string | null }`. `enabled` defaults to `true`.

| 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 |

<Callout type="tip" title="Make scripts self-sufficient">
Scripts run non-interactively in a fresh environment. Anything they need — package manager, language runtime, database — should either be declared in the repo (lockfiles, `.node-version`, etc.) or installed by the setup script itself.
</Callout>

## Ports

`ports.preview` (default `3000`) is 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.

## Override precedence

Projects have a second settings layer in Hoplite itself, editable under **Settings → Project → Environment** — or by the agent via `project_settings_update` (always with your approval):

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's `project_settings_get` tool prints exactly how each script resolves across the two layers, so "why did setup run that?" is always answerable.

## MCP servers

The `mcpServers` array attaches [MCP servers](/docs/integrations/mcp) to the project from the repo file — the same shapes the Connections settings page accepts.

## Sitemap

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