---
title: "Make your repo agent-ready"
description: "Scripts, environment variables, and instructions that turn a repo into a place agents work well."
canonical_url: "https://hoplite.sh/docs/agent-ready"
markdown_url: "https://hoplite.sh/docs/agent-ready.md"
---

# Make your repo agent-ready
URL: /docs/agent-ready
LLM index: /llms.txt
Description: Scripts, environment variables, and instructions that turn a repo into a place agents work well.
Related: /docs/sandboxes/scripts, /docs/sandboxes/environment-variables, /docs/agent/instructions, /docs/agent/skills

# Make your repo agent-ready

An agent that can install your dependencies, run your tests, and start your app verifies its own work instead of guessing. That takes four pieces of configuration: a setup script, a run script, environment variables, and instructions. This page walks through each; the checklist at the end is the summary.

## Tell Hoplite how to run your project

Commit a `.hoplite/settings.json` to your repository. 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.

```json title=".hoplite/settings.json"
{
  "version": 1,
  "ports": {
    "preview": 3000
  },
  "scripts": {
    "setup": { "enabled": true, "command": "pnpm install && pnpm db:migrate" },
    "run": { "enabled": true, "command": "pnpm dev" }
  }
}
```

The `setup` script runs after the repo is cloned, before the agent starts working — install dependencies, run migrations, seed data. The `run` script is your dev server command; it runs when a [preview](/docs/sandboxes/previews) starts. `ports.preview` (default `3000`) is the port the preview waits on and proxies; port numbers must be between 3000 and 9999.

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

You can also set or override scripts in Hoplite itself under **Settings → Project → Environment** — the override wins over the repo file. See [Project scripts](/docs/sandboxes/scripts) for `archive` scripts, additional ports, and the full precedence rules.

## Add verification commands

Two optional scripts close the loop on quality:

- **`check`** — a verification command (tests, typecheck) the agent can run
- **`diagnostics`** — runs after each agent edit; `{FILE}` in the command is replaced with the edited file's path

With these in place, the agent gets fast feedback on every change instead of discovering problems at the end.

## Add environment variables

Set secrets under **Settings → Project → Environment**. They're injected into the sandbox shell for every command the agent runs — setup scripts, dev servers, tests, ad-hoc shell calls. You can paste a whole `.env` into the key field to import multiple entries at once, and multi-line values like PEM keys are handled.

Values are encrypted at rest and never shown again after saving. If your setup script needs a private registry token or your app needs a database URL, this is where it comes from. See [Environment variables](/docs/sandboxes/environment-variables).

## Write project instructions

Under **Settings → Project → Agent**, add **instructions**: project-level context prepended to every run. Put your conventions, architecture notes, and things the agent should always or never do here — once, instead of in every thread. See [Instructions](/docs/agent/instructions).

For repeatable workflows the agent should load on demand rather than carry always, add **skills**:

```bash title="terminal"
hoplite skills add release-check --description "Prepare and verify a production release"
```

This creates `.agents/skills/release-check/SKILL.md` in the repo. Write the workflow there and commit it; the agent loads it with its `load_skill` tool when relevant. See [Skills](/docs/agent/skills).

## Let the agent do the setup

You don't have to configure this by hand. The agent's `project_settings_get` tool shows exactly how the project's scripts and settings resolve, and `project_settings_update` proposes changes — which always require your approval. A first thread of "figure out how to install, run, and test this repo, then configure the project scripts" is a reasonable way to bootstrap.

## Agent-readiness checklist

| Item | Why it matters | Where to configure |
| --- | --- | --- |
| Setup script | The sandbox has dependencies, migrations, and seed data before the agent starts | `.hoplite/settings.json` or **Settings → Project → Environment** |
| Run script + preview port | Previews and in-browser verification work on the first try | `.hoplite/settings.json` or **Settings → Project → Environment** |
| Check script | The agent can run tests or typecheck to verify its own work | `.hoplite/settings.json` or **Settings → Project → Environment** |
| Diagnostics script | The agent gets per-file feedback after each edit | `.hoplite/settings.json` or **Settings → Project → Environment** |
| Environment variables | Scripts and commands get the secrets they need | **Settings → Project → Environment** |
| Instructions | Conventions and constraints apply to every run without repeating them | **Settings → Project → Agent** |
| Skills | Named workflows load on demand instead of bloating instructions | `.agents/skills/` in the repo |

## Sitemap

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