---
title: "Repository setup"
description: "Give cloud threads a repeatable environment with versioned setup, verification, and preview commands."
canonical_url: "https://hoplite.sh/docs/agent-ready"
markdown_url: "https://hoplite.sh/docs/agent-ready.md"
---

# Repository setup
URL: /docs/agent-ready
LLM index: /llms.txt
Description: Give cloud threads a repeatable environment with versioned setup, verification, and preview commands.
Related: /docs/sandboxes/scripts, /docs/sandboxes/environment-variables, /docs/agent/instructions

# Repository setup

Give Hoplite the commands your project needs to install dependencies, verify changes, and start a preview. Commit them in `.hoplite/settings.json` on the revision your threads start from. Hoplite reads this configuration when preparing the workspace; project-level overrides take precedence over the file.

## Define setup and preview commands

For a pnpm repository with `dev` and `test` scripts:

```json title=".hoplite/settings.json"
{
  "version": 1,
  "ports": { "preview": 3000 },
  "scripts": {
    "setup": { "enabled": true, "command": "pnpm install --frozen-lockfile" },
    "run": { "enabled": true, "command": "pnpm dev --host 0.0.0.0" },
    "check": { "enabled": true, "command": "pnpm test" }
  }
}
```

Replace these commands with your repository's scripts. The example's `--host` option assumes your dev server accepts it. Match `ports.preview` to the port the server actually listens on.

Setup runs non-interactively before agent execution. Include runtime installation, private registry authentication, and database setup if the repository requires them. The `run` command starts managed previews; `check` makes a verification command available to the agent.

See the [configuration reference](/docs/sandboxes/scripts) for archive hooks, diagnostics, additional ports, and disabling inherited commands.

## Add secrets

Under **Settings → Project → Environment**, add the variables needed by setup, tests, and the application. Values are injected into sandbox commands and cannot be read back from settings after saving. They are accessible to code executing in that sandbox; see [secret scope](/docs/sandboxes/environment-variables).

## Verify the configuration

Start a cloud thread from the revision containing the file. Check the setup entry in its timeline, then ask the agent to run the configured check and start a preview.

Open the Preview panel and verify that the intended app is serving. A listening port alone does not establish that the application or its dependencies are healthy.

If the wrong command runs, inspect **Settings → Project → Environment** for an override. If setup fails, expand its timeline entry for the log output. If the preview crashes, use its exit reason and run-log tail. [Troubleshooting](/docs/workspace/troubleshooting) covers these cases.

## Configure agent context

[Project instructions](/docs/agent/instructions) apply to every run. [Repository skills](/docs/agent/skills) are discovered from `.agents/skills` and `.claude/skills` and loaded when relevant. Keep executable setup in scripts so its success or failure is visible in the workspace lifecycle.

## Sitemap

Sitemap discovery is not enabled for this deployment.