# Project settings

Project settings hold what Sensei needs to run your repository. They cover the sandbox size, the services, the environment variables, the branches and the setup scripts. The deploy agent fills them in on the first deploy. To change them, open the repository. A deployed repository with services opens on its [Preview](https://kosuke.ai/docs/set-up/preview-and-publish.md): press **Settings** in the Preview / Settings switch at the top right. Any other repository opens on its settings.

The page shows the Deploy Chat on the left and the settings panel on the right. The panel is titled **Repository settings**. Its tabs are Sandbox, Services, Environment, Advanced, Logs, GitHub and Labels, then [Change history](https://kosuke.ai/docs/set-up/project-settings.md#change-history), last in the list. Every member who can open the project reads them. [Who can change them](https://kosuke.ai/docs/set-up/project-settings.md#who-can-change-them) says who changes what.

Before the first deploy, the panel is locked, because the deploy agent writes it. Press **Edit manually** to unlock it.

## Who can change them

Only a workspace admin, an owner or an admin, changes these settings, in the web or desktop app:

- The **Sandbox** tab: the sandbox tier and the Host setup script.
- The **Services** tab: the App setup script and every service.
- The **Environment** tab: every variable.
- Under **Advanced**: the Agent Working Directory, **Branch tasks from**, **Open PRs against** and the Warmup Script.
- **Import config** and **Import .env**.
- Deploys: **Deploy**, **Redeploy** and messages to the deploy agent. See [Deploy your project](https://kosuke.ai/docs/set-up/deploy.md#who-can-deploy).

A member who is not an admin sees these settings read only, with the line "Only workspace admins can change these settings. You can read them." There are no import, add, lock or delete controls. A member can still press the eye icon to reveal a secret value in Environment.

Every member still changes the QA Guide under Advanced.

An API key and a Connected App cannot make these changes, so neither can the [CLI](https://kosuke.ai/docs/interfaces/cli.md) or the [MCP server](https://kosuke.ai/docs/interfaces/mcp.md). They get 403 `SETTINGS_ADMIN_ONLY` until API keys get a project settings scope. A chat session's agent and a Cron cannot make them either. Sensei can change the setup scripts, services and environment variables for a workspace admin, but only after that admin approves a Sensei card about the project. Sensei makes the change in the Turn the approval starts, and Change history shows it as Sensei for that admin. Sensei can save a secret value, but it never reads one back. The deploy agent still saves the settings it wrote at the end of a Deploy an admin started.

## When a change takes effect

Most sections save when you press their **Save** button. A sandbox tier saves as soon as you pick it.

After a change, press **Redeploy** in the Deploy Chat's message box. The project's main sandbox uses the saved settings only after a redeploy. New sessions usually start with the saved settings at once. A session can instead pick up a sandbox Sensei prepared before the change. That session keeps the old tier and the services already running, even after a redeploy. A redeploy also replaces the sandboxes Sensei keeps ready for new sessions. It does that last, after the main sandbox is up. Once the main sandbox is up, a new session never takes an old one. Until the Deploy Chat's Warming N more sandboxes line finishes, a new session boots a fresh sandbox, which starts slower. If it shows Warming N more sandboxes failed, new sessions keep booting fresh sandboxes until Sensei refills the spares. Sessions already running keep their old settings too. [Deploy your project](https://kosuke.ai/docs/set-up/deploy.md) explains what a redeploy does.

When you save a change to the Sandbox, Services or Environment settings, or to the Warmup Script under Advanced, the project page shows a **Redeploy needed** banner under its header. Every member sees it, on the Preview and in the settings, and it stays after a reload. A workspace admin presses **Redeploy** in the banner to start a deploy, or uses the **Redeploy** button in the Deploy Chat's message box. The banner goes away as soon as a deploy starts. If the deploy fails or you stop it, the banner comes back, so you can redeploy again. After a successful deploy it stays away. Save a setting back to its deployed value and the banner goes away too. The Agent Working Directory, the branch settings, the QA Guide, Labels and the Deploy model show no banner. Before the first deploy there is no banner, because the first deploy applies the settings.

## Sandbox

In a personal project, the [Deploy model](https://kosuke.ai/docs/set-up/deploy.md#choose-the-deploy-model) picker sits at the top of this tab. It sets only the model of the deploy agent.

Sandbox Tier sets the CPU and memory of the project's main sandbox and of every chat session's sandbox. A new tier reaches the main sandbox on the next deploy. New sessions usually get it at once, as [When a change takes effect](https://kosuke.ai/docs/set-up/project-settings.md#when-a-change-takes-effect) explains.

| Tier | CPU | Memory |
|---|---|---|
| Small | 2 | 4 GB |
| Medium | 4 | 8 GB |
| Large | 8 | 16 GB |
| XLarge | 16 | 32 GB |

The first deploy boots XLarge, and the agent then sets the tier the project needs. It measures the services and the project's heaviest check, such as its type check, and picks the smallest tier that holds both. It runs the check with a memory cap of its own. When you ask it to re-size a project below XLarge, it measures on a fresh XLarge sandbox rather than on your preview, then moves the project to the tier it found, so measuring never stops your preview's services. A larger tier costs more per hour. [Plans and billing](https://kosuke.ai/docs/workspace/plans-and-billing.md) lists the rates.

In a chat session, everything the agent starts shares 60% of the sandbox's memory, or less when the deploy agent measured that the services need more of the rest: its builds, type checks, tests and browsers, and its Delegated Runs. The services, the database and Sensei's own server sit outside it, so the agent's work cannot take the rest; the ceiling does not promise your services fit in that rest. When the agent's work passes the ceiling, the sandbox stops a process inside it. Usually that is the heavy command, and the agent sees it fail. When it is the agent itself, the turn stops with **Sandbox out of memory**. The deploy agent keeps the share it measured in `KOSUKE_MEASURED_COMMAND_MEMORY_PERCENT`. To choose the share yourself, set `KOSUKE_COMMAND_MEMORY_PERCENT` to a whole number from 10 to 90, or to `off` to remove the ceiling. Your value wins over the agent's, and the deploy agent never changes it. It applies from the next session.

Each service can use at most three quarters of the sandbox's memory, and so can all its Docker containers together. A service that passes that limit is stopped and starts again. When the whole sandbox runs low on memory, it stops its largest process within seconds instead of freezing: a service, a container or something the agent runs, never Sensei's own server while anything else is left. If that process is the agent, the turn stops with **Sandbox out of memory**.

When the project has a share, yours or the deploy agent's, your services that run as processes also share one ceiling together: what the agent's share leaves, minus 5% for the system, and never under 25%. With 45% for the agent, the services get 50%. A dev server that keeps growing past it is stopped and started again, rather than freezing the sandbox. Services that run as a Docker stack are outside it. Without a share, or with `off`, the services have no shared ceiling, only each service's own limit.

The agent's helper agents (Delegated Runs) and the browsers it opens also share a small number of work slots, about 2 GB each: 4 on XLarge, 3 on Large, 2 on Medium and 1 on Small. A helper agent holds a slot while it runs, and a browser until it closes. What a helper agent starts itself uses that agent's slot. A test run or build takes a slot when it runs through `ksb slot run -- <command>`. When every slot is taken, or the sandbox's memory is more than 75% used, the next one waits and says why. After 20 minutes it gives up without running.

The Host setup script installs runtimes and system packages, such as a database server. It runs on the first deploy, and again only after you change it.

![The Sandbox section of Project settings, picked in the section list on the left. The four Sandbox sizes, with Medium selected, sit above a thirteen-line host setup script that installs PostgreSQL and Redis.](https://kosuke.ai/docs/img/project-settings-sandbox.webp)

## Services

A service is anything that runs, such as an app, a worker or a database. Press **Add Service** to add one, or press a service's row to open it.

The App setup script at the top of the tab runs once at the repository root before any service starts, on every deploy. Put dependency installs there, such as `bun install`.

A new chat session often starts on a pool sandbox that ran the script at an older commit. Sensei skips the script there when the newer commit changed none of these: a lockfile, a dependency manifest, a toolchain version file, an env file, a migration, a seed, a schema file, or a folder a `package.json` names as a `file:` dependency. When the script also generates code from your source, set `rerunSetupOnCheckoutMove` to `true` in a `kosuke.config.json`, and the script runs on every such start. The web app has no switch for it, so a workspace admin imports the file with **Import config**. `kosuke projects settings update <projectId> --rerun-setup-on-checkout-move` gets 403 until API keys get a project settings scope.

| Field | What it holds |
|---|---|
| Name | Required. Lowercase letters, digits and inner hyphens. |
| Directory | The folder the service runs from. Empty means the repository root. |
| Start command | Required. The command that starts the service. It must listen on its first endpoint's port. |
| Stop command | Optional. The command that stops it. |
| Docker stack | Tick it for a multi-container stack run with Docker Compose. The start and stop commands become its up and down commands. |
| Env files | Docker stacks only. The paths the environment variables are written to. Defaults to one `.env`. |
| Endpoints | The ports the service listens on. A service with none runs in the background. |
| Depends on | Services that must be ready before this one starts. |

Each endpoint has a Name, a Port, an Exposure and a Health route.

| Exposure | Where it is reachable |
|---|---|
| Internal | Only inside the sandbox. It gets no URL. |
| Public | At its own URL in a browser. It stays out of the Preview tab. |
| Preview | At its own URL, and it shows in the Preview tab. |

List a service's main endpoint first. Sensei checks it to decide the service is ready, and `{{name.url}}` points to it. The Health route is an HTTP path such as `/api/health` that Sensei requests for that check. Leave it empty for a database such as Postgres or Redis.

Press **Save** on the service, or **Add Service** for a new one. **Delete** removes it.

![The Services section of Project settings, picked in the section list on the left. An app setup script reading "bun install --frozen-lockfile" sits above the Services list, which has an Add Service button and three collapsed services: postgres internal :5432, redis internal :6379 and nextjs preview :3000.](https://kosuke.ai/docs/img/project-settings-services.webp)

## Environment

Environment variables reach every service when it starts. Only a workspace admin adds, changes or removes them.

1. Press **Add Variable** and fill in Name and Value. To add many at once, press **Import .env**, drag a `.env` file onto the tab, or paste several `KEY=value` lines into a field.
2. For a password or key, press the lock icon to mark it secret. A secret value stays hidden until someone presses the eye icon beside it.
3. Press **Save Variables**.

A value can point at a service instead of a fixed address. Type `{{` in a value field to pick one.

| Placeholder | Becomes |
|---|---|
| `{{name.url}}` | The public URL of the service's first endpoint. Only for Public and Preview endpoints. |
| `{{name.url_int}}` | The address inside the sandbox, such as `http://localhost:3000`. |
| `{{name.endpoint.url}}`, `{{name.endpoint.url_int}}` | The same for an endpoint other than the first. |

For example, with a `nextjs` service on port 3000 and an `api` service on port 4000:

```bash
NEXT_PUBLIC_APP_URL={{nextjs.url}}
API_URL={{api.url_int}}
DATABASE_URL=postgresql://postgres@localhost:5432/app
```

Sensei fills in each placeholder when a sandbox starts. Every sandbox has its own public URL, so each session gets the right one. Placeholders always give a web address, `https://` for `url` and `http://localhost` for `url_int`, so write database connection strings out in full.

### Variables that reach your app only

Some names change how a program or a shell starts, where it reads its settings, or how it reaches the network. A variable with one of these names reaches your app and its services, but never Kosuke's own agents:

- `NODE_OPTIONS`, `NODE_PATH`
- `LD_PRELOAD`, `LD_LIBRARY_PATH`, `LD_AUDIT`
- `BASH_ENV`, `ENV`, `PATH`
- `PYTHONSTARTUP`, `PYTHONPATH`, `PYTHONHOME`
- `PERL5OPT`, `PERL5LIB`
- `RUBYOPT`, `RUBYLIB`
- `HOME`, `USER`, `LOGNAME`, `SHELL`, `TMPDIR`, `TMP`, `TEMP`, `CODEX_HOME`, `CLAUDE_CONFIG_DIR`, `SSH_AUTH_SOCK`
- `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY` (in either case), `NODE_EXTRA_CA_CERTS`, `NODE_TLS_REJECT_UNAUTHORIZED`, `SSL_CERT_FILE`, `SSL_CERT_DIR`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE`
- the names Kosuke sets for its agents, such as `KOSUKE_SANDBOX_KEY`, `KOSUKE_API_URL` and `DISPLAY`
- every name that starts with `GIT_` or `XDG_`

Under such a variable, the Environment tab says "Reaches your app only. Kosuke's agents start without it."

## Advanced

| Setting | What it does | When empty |
|---|---|---|
| Agent Working Directory | The folder, relative to the repository root, where the agent works. Use it when the app lives in a subfolder. | The repository root |
| Branch tasks from | The branch new tasks start from. The main sandbox follows it too. | The repository's default branch |
| Open PRs against | The Target Branch. Pull requests open against it, and Sync brings it in. | The repository's default branch |
| Warmup Script | Runs after the services are healthy. Use it to request the busiest pages so the Preview loads fast. | Nothing runs |
| QA Guide | How to test the project in a sandbox: which service to open, how to sign in, how to read its data, and the traps to avoid. QA keeps it under 15,000 characters and puts a recipe that only one branch needs in that run's QA Report. [`/kosuke:automated-qa`](https://kosuke.ai/docs/skills/automated-qa.md) sends it the first time it tests the project and reads it on every run; the guide is saved when the task's Assignee approves the card their Sensei draws for it. You can edit it here. A change reaches the tasks started after it, with no redeploy. Tasks already running read the current guide at the start of each QA run. The deploy agent never changes it. | QA works it out on its first run and sends it to the Assignee's Sensei |

The two branch settings sit under Branch Overrides and share one **Save** button. The QA Guide has its own **Save** button and holds up to 102,400 characters. Keep it short: what QA writes stays under 15,000.

## Logs

The Logs tab streams the main sandbox's logs. Pick Full logs, Setup, or one service. While a deploy runs, it shows the deploy's sandbox instead. Open it first when a deploy fails.

## GitHub

The GitHub tab shows the repository the project builds from. How pull requests merge is under [Merge agent](https://kosuke.ai/docs/set-up/project-settings.md#merge-agent).

## Merge agent

Each repository has one merge agent. An imported repository starts with it [Off](https://kosuke.ai/docs/set-up/project-settings.md#off): pick **Merge train** under Mode to turn it on. A repository made from kosuke-starter starts on **Merge train** with Go-ahead **When checks pass**. A note in the box says which of the two the repository is. The agent merges the pull requests that have the go-ahead into the project's Target Branch, which is the default branch unless you set one under [Advanced](https://kosuke.ai/docs/set-up/project-settings.md#advanced). It merges only a commit that has the go-ahead and whose QA passed, as the Kosuke GitHub App. Under [When checks pass](https://kosuke.ai/docs/set-up/project-settings.md#go-ahead) with Wait for QA off, passing checks are enough. Its runs are chat sessions the agent owns: they stay in this section, off the Tasks board, the session lists, Needs you and search.

The agent is woken by events, never on a timer: a go-ahead opens a run, and while one is open it takes a short turn when a check finishes, a pull request it holds is approved or merges, or a session it asked to sync ends its turn. It ends the run when nothing waits.

The page is titled **Merge agent**, with a small **Docs** link. One box holds its settings. **Mode** picks **Merge train** or **Off**. With Merge train picked, **Go-ahead** follows, and with When checks pass, **Wait for QA**. Under them, two facts you read but do not change: whether GitHub's merge queue is on for the base branch, and **Merges as Kosuke GitHub App**. A note shows while the mode changes. If the change fails, the note says so, with **Try again**. With the merge train picked, it says **Merge train is on**.

### Pipeline

Below the box, **Pipeline, in go-ahead order** shows where each pull request is.

The open run has its own full-width row first. It shows the run's name and a badge: **Now**, or **Stopped** when its turn failed and the retries ran out. One status line says what happens now, and a small link opens the run (**Open run**). With no run open, the row says **No run** and that the next one starts on the next go-ahead.

Then three lanes of pull request cards:

- **Waiting**: someone acts first. The pull request is a draft, QA has not run at its head, or it has no approval. Failed ones wait here too: QA did not pass at its head, or a review asked for changes.
- **Ready**: it merges next, one at a time.
- **Done**: Merged.

Once the open run saves the order it merges in, one list in that order takes the place of Waiting and Ready, with Done beside it.

Each card shows the title, then one line with the reason for Waiting and Failed, then the assignee, the pull request number and one state word. The Tasks board card shows the same word for the same pull request. The first state that fits wins: Merged, Waiting, Failed, Ready. Click a card to open its task. Cards do not expand.

**Earlier runs** is a row you open to list the last 10 runs; its count reads `10+` while older runs remain. **Load more** under them adds the next 25, until the count shows the total. Every earlier run, newest first, a page at a time, with its number, session, state and dates, is listed by `kosuke projects merge-agent runs list` (pass the `nextCursor` it answers as `--cursor` for the next page); `kosuke sessions get` reads a run's session. Open a run to read its transcript in the chat column: switch the chat header from **Deploy** to **Merge agent**, and write to steer it, for example "merge #2961 before #2958". While the run's turn is working, what you send waits in Up next under the composer, as in a task's chat: edit, reorder, delete or send it from there. When the running turn is yours and its model takes a steer, press **Steer now** on a queued message to send it into that turn; ⌘Enter (Ctrl+Enter) in the composer does the same while the run on screen is the open one, since a message to a finished run opens a new run. A turn the app started is nobody's to steer, so a message sent then waits for the turn to end. It never merges a commit nobody gave the go-ahead.

### Merge agent model

The model picker in the Merge agent chat header chooses the model and effort its runs start on, such as Claude Opus (High). It offers what the [Deploy model](https://kosuke.ai/docs/set-up/deploy.md#choose-the-deploy-model) offers: a workspace's Credentials, or a personal project owner's Subscriptions. **Default**, where every project starts, runs each new run on the Default Model, as a task left on it starts. While a run is open, the header shows the model that run runs on, and a pick applies to the next run: the open run keeps its model. Every earlier run shows the model it ran on. In the CLI, run `kosuke projects merge-agent model set <projectId> --model anthropic:opus__high`, or `--model default`; `kosuke projects merge-agent get` returns the model as `model` and each run's as `run.model`.

### Merge train

With **Merge train**, the agent merges one pull request at a time in an order it chooses. It updates a branch that is behind, sends [`/kosuke:sync-branch`](https://kosuke.ai/docs/skills/sync-branch.md) to the session of one that conflicts, waits for a required review, and enqueues instead of merging when the branch has GitHub's merge queue. The repository's settings decide the merge method. When a step needs a person, it messages the pull request's Assignee in Sensei.

### Go-ahead

Under Merge train, **Go-ahead** says what gives a pull request the go-ahead.

- **By a member**: "A member gives each pull request the go-ahead." Its QA must pass at that commit too. This is how every repository worked before the setting existed.
- **When checks pass**: "A pull request whose required checks pass on its latest commit has the go-ahead. Nobody has to give it." Required checks are the ones the branch's rulesets and branch protection require. When the branch requires none, every check on the commit has to finish green, and at least one has to run. A repository with no CI merges nothing this way: the Assignee hears from Sensei, and a member can still give the go-ahead.

Under When checks pass:

- Only a pull request that is ready for review gets the go-ahead, and only once the task's agent has stopped working on it. [`/kosuke:ship`](https://kosuke.ai/docs/automate/sensei.md) marks its pull request ready itself when the work is done, and waits for its checks. A draft never gets the go-ahead, and Kosuke no longer marks one ready.
- A new commit starts the wait again: the go-ahead is for one commit.
- A pull request that conflicts with the base branch runs no checks, so the merge train sends [`/kosuke:sync-branch`](https://kosuke.ai/docs/skills/sync-branch.md) to its session by itself. The task modal shows no Sync button.
- Failed checks give no go-ahead. The task modal shows **Fix it**, which sends the failure to the task's chat.
- A task filed from GitHub, such as a pull request opened there or a Dependabot update, still waits for a member's go-ahead.

**Wait for QA** shows only under When checks pass. On: "a pull request merges only after its checks pass and its QA passes." Off: "a pull request merges once its checks pass. QA does not have to pass first." Under By a member, QA is always required.

Go-ahead and Wait for QA save as soon as you pick them, with no dialog. Switching back to By a member takes away the go-aheads the checks gave, so those pull requests wait for a member. In a repository with the kosuke-starter layout, each task that merges shows as a new Version on its [Preview](https://kosuke.ai/docs/set-up/preview-and-publish.md#versions).

### Off

With **Off**, the mode a new project starts in, Sensei merges nothing in the repository: no merge train, and nothing added to GitHub's merge queue. A go-ahead, a finished check, an approval or a merge wakes nothing, and members merge their pull requests themselves. A note under **Mode** says so, the pipeline is hidden while no run is open, and the chat column cannot start a run. If a run is open when you switch to Off, it stops merging and ends. No run starts after it. Switch back to **Merge train** and a run starts at once for the pull requests that wait with a go-ahead.

The mode saves as soon as you pick it, needs no redeploy, and the lock before the first deploy does not apply to it. From the CLI, `kosuke projects merge-agent get <projectId>` reports the `mode` (`train` or `off`), the `goAhead` (`member` or `checks`) and `waitForQa`. Only `mode` `off` means the Merge agent is off. The output no longer has `enabled`: its `false` meant the merge train, not off. `kosuke projects merge-agent set <projectId>` changes them, one or several at once, with `--mode`, `--go-ahead` (`member` or `checks`) and `--wait-for-qa`. It still takes the older `--no-enabled` (`train`); any other mode, and `--enabled`, is refused with a message that names the merge train.

### Repository

The Repository block shows the repository the project builds from. It has the repository's path, its default branch, and an **Open** button that opens it on GitHub. Below it are the Repository ID, the Installation and Last synced. Last synced is the time of the last push to the branch sessions start from.

The Repository ID stays the same when the repository is renamed or transferred on GitHub.

![The GitHub section of Project settings, picked in the section list on the left. Under a Repository heading, a block shows acme/storefront with a "main" branch badge and an Open button, then three cells reading Repository ID 812405113 with a copy button, Installation 64207731, and Last synced with a date and time.](https://kosuke.ai/docs/img/project-settings-github.webp)

## Chat

The chat column on the left has three tabs: **Deploy**, **Merge agent** and **Chat**. **Deploy** is the one that opens with the page. **Chat** is a normal chat agent in its own sandbox. It works on the repository's default branch and pushes there itself, with no pull request. It has the same message box, tools, skills, plugins, model picker and **Stop** as a task. Sensei adds no step around it: no checks before a push and no save step. When a test fails, a merge conflicts or GitHub refuses a push, the agent handles it in the conversation, as in any task.

Who the pushes come from depends on the repository:

- On an imported repository, Chat pushes as you, with your GitHub Connection. You need a connection and the right to push to the repository.
- On a repository Sensei made from kosuke-starter, Chat pushes as you when you are connected and can push there. Otherwise it pushes as the Kosuke Apps GitHub App, and each commit names you as its co-author. Members have no GitHub access to repositories in Kosuke-Org, so there the App pushes. You can use Chat there without a GitHub Connection.

Each push shows under the turn that made it, with a link to its commit. On a repository with the kosuke-starter layout, each push becomes a [Version](https://kosuke.ai/docs/set-up/preview-and-publish.md#chat-and-versions).

A project has one Chat, and every member writes in the same one. Each turn runs as the member who sent it. While another member's turn runs, your message waits in Up next and starts when that turn ends. You cannot steer another member's turn. The Chat session is no member's task: it stays off the Tasks board, the session lists and search.

Skills that need a branch and pull request of their own, such as `/kosuke:ship`, `/kosuke:open-pr` and `/kosuke:sync-branch`, do not run in Chat. They reply "This skill needs a branch and pull request of its own, so it cannot run in Chat. Start a task for it instead." and change nothing.

With the CLI, `kosuke projects chat get <projectId>` reads whether Chat is on for you, why it is off, its session and its pushes. `kosuke projects chat create <projectId>` opens the Chat session if the project has none yet. Send messages to it as to any session.

### When Chat is off

Chat is off where GitHub's rules or your access forbid a direct push. Then you use the normal workflow: tasks, pull requests and the Merge agent. The **Chat** tab is dimmed. Hover it, focus it or tap it to read why. The tooltip starts with "Chat is off." and then gives the reason and the next step.

Sensei reads the rules as the account that would push, and ignores any bypass that account holds. It reads them again after at most a minute, so a rule you change on GitHub shows within a minute. If a rule changes during a turn, GitHub refuses the push, and the tab turns off at the next read.

| Why Chat is off | Next step |
| --- | --- |
| On an imported repository, your GitHub account is not connected, or its connection needs a reconnect. | Connect or reconnect GitHub in Settings > You > Integrations, or start a task. |
| Your GitHub account cannot push to the default branch. | Start a task instead. |
| GitHub's rules on the default branch require pull requests, status checks, signed commits, deployments or a merge queue, block updates, or keep direct pushes out. | Start a task instead, and the Merge agent lands it. |
| Sensei could not read GitHub's rules for the default branch. | Try again in a moment, or start a task. |
| An older session still works on the default branch. | End it, then open Chat. |
| Sensei has not read the rules yet. The tooltip reads "Checking." | Wait a moment. |

## Labels

The Labels tab lists the repository's Session Labels, each with a color dot and a **Delete** button.

- To change a label's color, click its dot and pick a swatch or type a hex value.
- To delete a label, press **Delete**. The confirmation lists the tasks that carry it, archived and completed included. Tick the box to remove the label from them, then press **Delete label**. Labels live only in Sensei, so nothing changes on GitHub.

You cannot create a label here. A label appears once a task gets it. See [Labels](https://kosuke.ai/docs/sessions/chat-sessions.md#labels).

The Labels tab is not part of the exported or imported config. The lock before the first deploy does not apply to it.

## Change history

**Change history** is the last section in the settings list. It lists every change that went through to the project's setup, services, environment, imports and deploys, newest first. A refused attempt is not listed. A Deploy is listed only when it starts, and always does: Sensei writes its row together with the Deploy, so one cannot start without it. Every member who can open the project reads it.

Each row says what changed, who made it, how and when. How is one of these:

| How | What it means |
|---|---|
| **Browser** | A member signed in to the web or desktop app. Only a workspace admin changes settings or starts a Deploy there. |
| **API key** | An API key, with its name. No key changes settings or starts a Deploy, whatever its scope. |
| **Connected app** | An AI app connected through the MCP server. |
| **Sensei** | The member's own Sensei, for them. |
| **Deploy agent** | The deploy agent, saving the settings it wrote at the end of a Deploy. |

A member who restarts the main preview, from the app, a key, a connected app or their Sensei, starts a Recovery Deploy: it lists as that member starting a Deploy, with how they asked. A Recovery Deploy Sensei starts on its own, after it finds the main sandbox gone, lists no row.

Select a row to see Before and After. Select it again to close it.

Change history never keeps an environment variable's value, secret or not. A variable shows "Not set" or masked dots.

With no changes yet, the section reads "No changes yet." From the CLI, `kosuke projects settings changes list <projectId>` reads the same list.

## Export and import the settings

The two icons at the top right of the panel move the whole configuration as one file in the `kosuke.config.json` format.

- **Export config** downloads it as `<project name>.config.json`. The file includes the QA Guide as `qaGuide`.
- **Import config** reads such a file into this project. Only a workspace admin sees it. Sensei checks it first and lists any problems in an Errors tab. A valid file opens the Import Configuration dialog, which warns that it replaces all existing settings. Press **Continue**, then **Redeploy**.

> **Warning.** The exported file holds every environment variable's value, secrets included. Keep it out of your repository.

## Rename or delete a project

In the sidebar, press the project's menu (**...**) or right-click the project.

- To rename it, choose **Rename**, type the new name and press **Save**. Any member can rename a project. The GitHub repository keeps its name.
- To delete it, choose **Delete Project** and confirm with **Delete Project**. Only owners and admins see this option. Deleting removes the project and all its data from Sensei for good. Your GitHub repository stays as it is.

## Limits

- In the phone layout, on an iPhone or in a narrow window, project settings show "Open this on a computer" instead. See [Desktop app and mobile](https://kosuke.ai/docs/help/desktop-and-mobile.md#use-kosuke-on-a-phone).
- An import replaces every existing setting, except the sandbox tier and the QA Guide when the file leaves them out.
- A placeholder that matches no service endpoint stops the sandbox from starting.

## Next steps

- [Deploy your project](https://kosuke.ai/docs/set-up/deploy.md)
- [Plans and billing](https://kosuke.ai/docs/workspace/plans-and-billing.md)
- [Chat sessions and tasks](https://kosuke.ai/docs/sessions/chat-sessions.md)