The agent-ready repository checklist: setup, secrets, tests and previews

Your app starts on your laptop because you've already installed the runtime, created the database and added the missing environment variable. A fresh agent sandbox has none of that history.

When setup is incomplete, the first task becomes an installation investigation. The agent may solve it, but every new thread risks rediscovering the same missing step.

Hoplite's agent-ready guide organizes setup around scripts, environment variables and instructions. The goal is straightforward. A Hoplite cloud agent in a new sandbox should be able to run the same checks you run before you review a change.

Make setup work without a person at the keyboard

Commit .hoplite/settings.json with commands your repository already supports. For a hypothetical pnpm application, a starting configuration could look like this:

{
  "version": 1,
  "ports": {
    "preview": 3000
  },
  "scripts": {
    "setup": {
      "enabled": true,
      "command": "pnpm install --frozen-lockfile"
    },
    "run": {
      "enabled": true,
      "command": "pnpm dev"
    },
    "check": {
      "enabled": true,
      "command": "pnpm test && pnpm typecheck"
    }
  }
}

Those commands need matching scripts in the project. They also need the required runtime and package manager. Pin or install the versions your repository needs. If the app needs a database, set it up in the setup script with migrations and seed data. Do not rely on a database running somewhere else.

Keep setup non-interactive. A migration that waits for confirmation stalls the agent until someone opens the terminal.

Project settings can override the repository file. If a change to .hoplite/settings.json has no effect, ask the agent to inspect the resolved configuration with project_settings_get. The script documentation explains the precedence and the optional diagnostics script, which runs after each edit with {FILE} replaced by the edited file.

Supply development secrets deliberately

Add required variables under Settings, Project, Environment. Hoplite injects them into sandbox commands, including setup and tests. Use development credentials with only the access the task needs.

A DATABASE_URL that points at your laptop won't bring the database with it. Point it at a reachable development database that the setup script creates or migrates. Check what database the seed command targets before you let it write.

Document variable names and their purpose in the repository without committing their values. If a feature needs an external API, explain whether development should use a test account, a fixture or a disabled path. The agent needs to know which behavior is expected when a service is absent.

Make the preview predictable

The run command must start the application on the configured port. Hoplite's preview port range is 3000 through 9999, with 3000 as the default. Add named additional ports when your app has another HTTP service reviewers need to inspect.

In a monorepo, point the command at the intended application. Starting every workspace may consume resources and introduce failures unrelated to the task. Starting only the frontend may also be insufficient if it depends on a local API.

Hoplite's Preview panel reports whether the process is starting, ready, stopped, crashed or unsupported. A ready HTTP server still needs an application check. Open the route that matters and confirm that it loads its required data.

If the process crashes, inspect the exit reason and logs before changing ports at random. A missing variable needs a different fix than an occupied port.

Give the agent one reliable check command

The check script should run the tests you want for most changes. Keep targeted commands documented as well, so a small edit doesn't require a full integration environment just to get initial feedback.

Run the checks before you hand off work. Note known failures and their cause. Otherwise the agent may spend the task fixing unrelated tests or report a failure you already know about.

Project instructions can explain architecture boundaries, generated files and the checks required for sensitive areas. Put longer repeatable procedures in skills instead of pasting them into every prompt.

Try a setup-only thread

Before assigning implementation, ask the agent to install the project, run the checks, start the preview and report any missing prerequisites. Have it identify configuration changes separately from application changes.

Then repeat the setup in a fresh thread. If setup only worked because of a manual fix in the first sandbox, move that fix into the committed setup or project configuration. Your next bug-fix thread should spend its time on the bug.