Project Settings

Project Settings is where you configure the project-level defaults and integrations that affect all sandboxes, workflows, and issue sessions. The settings page is organized into tabs, each covering a different aspect of project configuration. Access to settings requires the Admin or Owner role.

Navigate to Project Settings from the bottom of the sidebar (the wrench icon) or directly at /p/{projectId}/settings.

API Key Configuration

CodeCourier requires API keys for the external services it integrates with. Keys are configured per-project, meaning different projects can use different API accounts. All keys are encrypted at rest in the database and only the last four characters are displayed in the UI.

Required Keys

Optional Keys

System Prompt Configuration

The Sandbox System Prompt is a default prompt injected into every sandbox session in the project. It establishes baseline behavior for all AI agents, including instructions for working within the E2B sandbox environment, package management preferences, file system conventions, and Git workflow rules.

The default system prompt includes critical sandbox-specific instructions like:

• Binding dev servers to 0.0.0.0 for public accessibility
• Starting servers in the background with nohup
• Using the /home/user/ base directory
• Constructing the public URL from the sandbox ID and port
• Git commit conventions and authentication setup

You can customize the system prompt to add project-specific rules that should apply to all sessions regardless of which persona or workflow is running.

CLAUDE.md Template

The CLAUDE.md field lets you define a template for the CLAUDE.md file that gets written into each sandbox. This file provides project-level context to the AI agent, including architecture decisions, coding standards, dependency preferences, and other knowledge that should persist across sessions.

Think of CLAUDE.md as the project's "institutional knowledge" that every agent should have access to, regardless of the task.

Issue Discovery Prompt

The Issue Discovery Promptconfigures the default instructions used by issue sessions. This prompt is injected when an AI agent starts analyzing the codebase for issues. Customize it to reflect your project's issue triage conventions, priority preferences, and discovery focus areas.

Environment Variables

You can define environment variables that are injected into every sandbox session. These are useful for configuration values that your codebase needs at runtime:

• Key - The environment variable name (e.g., DATABASE_URL)
• Value - The variable's value
• Secret flag - Whether the value should be masked in the UI

The settings page supports two sets of environment variables:

• Sandbox env vars - Injected into development sandbox sessions
• Deploy env vars - Used during deployment operations

Skills and Commands

Project settings include the ability to select which skills and commands are available project-wide. Skills are packages of domain knowledge (reference files, best practices, API docs) and commands are reusable prompt templates. Selecting them at the project level makes them available to all personas and sessions in the project.

You can also select scripts - executable shell scripts that can be injected into sandbox environments for common setup tasks.

Learning Configuration

The learning system captures patterns, gotchas, and best practices from sandbox sessions and makes them available to future runs. Project settings control:

• Learning Template ID - The sandbox template used for learning extraction
• Learning Model - Which AI model extracts learnings from session transcripts
• Merging Template ID - The template used for merging code changes from completed runs
• Merging Model - Which model handles merge operations

Git Configuration

For projects that create Git commits and pull requests, you can configure:

• GitHub Repository URL - The repository linked to this project (set at the project level)
• Git Commit Name - The author name used in commits created by the AI agent
• Git Commit Email - The author email used in commits

These settings ensure that all AI-generated commits are attributed correctly and follow your team's Git conventions.

Convex Keys

If your project uses Convex as its backend (as CodeCourier itself does), you can configure:

• Convex Deploy Key - Used for deploying Convex functions from the sandbox
• Convex Dev Key - Used for development-mode Convex operations

These keys enable the AI agent to deploy and test Convex backend changes directly from the sandbox environment.

Test User Credentials

For projects that require authenticated testing, you can store test user credentials:

• Email - Test account email address
• Password - Test account password

These credentials are made available to sandbox sessions for automated end-to-end testing, allowing agents to log into the application and test authenticated features.

Session Configurations

Beyond the global project defaults, CodeCourier provides dedicated setup tabs for each of the six session typesthat power the AI workflow pipeline. Each setup tab lets you configure the CLI tool, model, thinking effort, linked Context Document, and selected Assets (Skills, Commands, and Scripts) for that specific session type. Changes to a session type’s setup apply to all new sessions of that type project-wide, unless a persona overrides them.

Answering Setup

Located at /p/{id}/answering-setup. Configures the Answering Agent - the session type that responds to natural-language questions about the codebase and project. Fields:

• CLI tool - Which coding agent CLI to use (Claude Code, OpenCode, Codex)
• Model - The specific LLM model for answering sessions
• Thinking effort - Reasoning depth (none, low, medium, high, max)
• Context - The Context Document injected into answering sessions by default
• Skills, Commands, Scripts - Default assets available to answering sessions

Issues Setup

Located at /p/{id}/issues-setup. Configures the Issue Discovery Agent - the session type that scans the codebase and generates a structured list of issues, bugs, and improvement opportunities. Fields:

• CLI tool - Which coding agent CLI to use
• Model - The specific LLM model for issue discovery sessions
• Thinking effort - Reasoning depth
• Context - The Context Document injected into issue discovery sessions by default
• Skills, Commands, Scripts - Default assets available to issue discovery sessions

Learning Setup

Located at /p/{id}/learning-setup. Configures the Learning Extraction Agent - the session type that reads completed session transcripts and extracts structured learning records from them. Fields:

• CLI tool - Which coding agent CLI to use
• Model - The specific LLM model for learning extraction
• Thinking effort - Reasoning depth
• Context - The Context Document injected into learning sessions by default
• Skills, Commands, Scripts - Default assets available to learning sessions

Merging Setup

Located at /p/{id}/merging-setup. Configures the Merge Agent - the session type responsible for merging code changes from completed workflow runs back into the main branch. Fields:

• CLI tool - Which coding agent CLI to use
• Model - The specific LLM model for merge operations
• Thinking effort - Reasoning depth (higher effort helps resolve complex merge conflicts)
• Context - The Context Document injected into merging sessions by default
• Skills, Commands, Scripts - Default assets available to merging sessions

Evaluator Setup

Located at /p/{id}/evaluator-setup. Configures the Quality Evaluator - a session type that grades and scores agent output against defined quality criteria. The Evaluator is used when you want quantitative quality measurement rather than a binary pass/fail verdict. Fields:

• CLI tool - Which coding agent CLI to use
• Model - The specific LLM model for evaluation sessions
• Thinking effort - Reasoning depth
• Context - The Context Document injected into evaluator sessions by default
• Skills, Commands, Scripts - Default assets available to evaluator sessions

Judge Setup

Located at /p/{id}/judge-setup. Configures the Output Judge - a session type that compares multiple agent outputs side-by-side and selects the best one. The Judge is used in evaluation pipelines where several variants of a solution are generated and you want automated selection of the winner. Fields:

• CLI tool - Which coding agent CLI to use
• Model - The specific LLM model for judge sessions
• Thinking effort - Reasoning depth (high effort recommended for nuanced comparisons)
• Context - The Context Document injected into judge sessions by default
• Skills, Commands, Scripts - Default assets available to judge sessions

Additional Project Settings Fields

The following settings are available in the Project Settings schema but are not covered in earlier sections. They control deployment, testing, lifecycle, and advanced infrastructure behaviors.

Deploy Environment Variables

In addition to sandbox environment variables (used in development sessions), you can define a separate set of Deploy Environment Variables for deployment and production contexts. These are stored encrypted and are only injected into sessions performing deploy operations - they are not visible in standard sandbox sessions.

Use deploy env vars for production API keys, production database URLs, CDN tokens, and other credentials that should never be present in development sandboxes. The key/value format is identical to sandbox env vars, with the same secret masking support.

Test User Credentials

For projects that require authenticated end-to-end testing, you can store Test User Credentials in Project Settings. These are made available to sandbox sessions so agents can log into the application as a test user and exercise authenticated features.

• Email - Test account email address
• Password - Test account password (stored encrypted)

The credentials are injected as environment variables into the sandbox so agents and test scripts can reference them without having them hardcoded anywhere.

PR Template

The PR Template field accepts a markdown template used when agents create pull requests from workflow runs. The template follows the same format as a GitHub.github/pull_request_template.md file. When an agent opens a pull request, this template is used as the PR body, pre-populated with the relevant context from the workflow run (issue title, prompt summary, checklist items).

## Summary
<!-- Describe what this PR does and why -->

## Changes
<!-- List the key files and components changed -->

## Testing
- [ ] Unit tests added or updated
- [ ] Build passes (`bun run build`)
- [ ] Lint clean (`bun run lint`)
- [ ] E2E tests pass (if applicable)

## Related Issues
<!-- Link to the issue or task this PR resolves -->

Convex Deploy Key

The Convex Deploy Key is used by agents to deploy Convex functions from within a sandbox. When set, agents can run npx convex deploy inside the sandbox and the key authenticates the deployment to your Convex project. This enables fully automated end-to-end workflows where the agent writes backend code and deploys it in a single session.

Generate a deploy key from the Convex dashboard under your project’s deployment settings. Deploy keys are scoped to a specific Convex deployment and should use the minimum required permissions.

Convex Dev Key

The Convex Dev Key is used for accessing Convex in development mode from within sandboxes. Unlike the deploy key (which targets production deployments), the dev key connects to your Convex development deployment, enabling agents to read and write data to the dev database during development sessions.

Auto-pause

The Auto-pause toggle controls whether idle sandboxes in the project are automatically paused after a period of inactivity. When enabled, a sandbox that has not received user input or produced new output for a configurable period is automatically suspended to conserve resources.

Paused sandboxes preserve their filesystem state and can be resumed. Auto-pause is recommended for projects where sandbox sessions are frequently left running by accident, as it prevents runaway costs from idle E2B sandboxes.

Max Pause Duration

The Max Pause Duration field sets how long a paused sandbox is retained before being permanently killed. Once a sandbox has been paused for longer than this duration, it is automatically terminated and its state is discarded. Valid values range from minutes to hours, depending on your plan.

Setting a shorter max pause duration reduces costs by killing forgotten sandboxes sooner. Setting a longer duration gives team members more time to return to a paused sandbox and resume work. The right value depends on your team’s working patterns.

Project Logo

You can upload a custom logo for the project. The logo is displayed in the project rail sidebar and helps visually distinguish between projects when you are a member of multiple teams. If no logo is uploaded, the project shows a colored initials badge derived from the project name.

Next Steps