---
title: "Project settings"
description: "Configure repository access, execution environments, and agent defaults for each project."
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: Configure repository access, execution environments, and agent defaults for each project.
Related: /docs/sandboxes/scripts, /docs/sandboxes/environment-variables, /docs/agent/models

# Project settings

Give related work a shared configuration with project settings. A project brings together repository bindings, environment variables, scripts, agent defaults, threads, and automations. Open **Settings → Project** with the intended project selected.

## Settings pages

| Page | Configuration |
| --- | --- |
| **Repository** | Linked repositories and their base branches, project name and description, deletion |
| **Environment** | Setup, run, and archive overrides, ports, environment variables |
| **Sandbox** | Initial CPU and memory preset, scaling ceiling, Docker Compose runtime |
| **MCP** | Remote servers and credentials available to the agent |
| **Agents** | Model default, reasoning effort, speed, instructions, skills, PR autofix |

## Repository bindings

Use **Add repository** under **Repository** to attach another connected repository. Set each binding to its repository's default branch or an explicit base branch. New threads select a repository and source within these bindings.

Removing the final binding keeps the project and its history, but prevents new cloud threads and automations until a repository is attached again.

Only workspace owners and admins can delete a project. Under **Repository → Danger zone**, choose **Delete project…**, then type the project name to enable confirmation. Open Hoplite in its own browser tab first: project deletion is unavailable when Hoplite is embedded in another page. Deletion is permanent and removes the project, including its threads, sandboxes, automations, and environment variables. The connected GitHub repository is not deleted or changed.

## Configuration precedence

Script overrides in Hoplite take precedence over [`.hoplite/settings.json`](/docs/sandboxes/scripts#how-scripts-resolve). Removing an override restores the repository value; disabling a script explicitly prevents it from running. The [script reference](/docs/sandboxes/scripts) owns the field definitions and resolution rules.

Keep portable setup in the repository file. Use [environment variables](/docs/sandboxes/environment-variables) for secrets and project overrides for configuration that should differ from the committed defaults.

## Runtime defaults

Under **Sandbox**, choose the initial box size and the ceiling for [resource scaling](/docs/sandboxes/resources). Presets above the plan limit are unavailable. A stored value that does not match a preset appears as **Custom** until a new preset is selected.

Selecting **Docker Compose** changes the runtime for new workspaces. Existing workspaces keep their current runtime. See [Workspace lifecycle](/docs/sandboxes#docker-compose-workspaces) for runtime selection and replacement behavior.
