# Project setup with .sesh/config.json

> Tell Sesh how to get a fresh copy of your project ready for an agent.

Source: https://sesh.codes/docs/project-setup/

Every session on its own branch starts with a fresh copy of the project. Before the agent starts, Sesh copies in files git doesn't track and runs a setup command, or starts from a copy where setup already ran. A `.sesh/config.json` file in your repository says exactly what to do. Commit it so everyone gets the same setup.

## Without a config file

Sesh looks at your project and guesses:

| It finds | It runs |
|---|---|
| `pnpm-lock.yaml`, `yarn.lock`, `bun.lock` or `package-lock.json` | `pnpm install`, `yarn install`, `bun install` or `npm install` |
| `Package.swift` | `swift package resolve` |
| `Cargo.toml` | `cargo fetch` |
| `go.mod` | `go mod download` |
| `Gemfile` | `bundle install` |
| `uv.lock` or `poetry.lock` | `uv sync` or `poetry install` |

It also copies `.env` and `.env.*` files. The chat says what it guessed, and which tools were missing on the machine.

## Write your own

Create `.sesh/config.json` in the root of the repository:

```json
{
  "setup": "pnpm install && pnpm db:migrate",
  "copy": [".env", ".env.local", "config/*.local.json"],
  "baseBranch": "develop",
  "branchPrefix": "sesh/"
}
```

Once the file exists, Sesh follows it exactly and stops guessing. An empty `{}` turns everything off.

## Keys

| Key | What it does | Default |
|---|---|---|
| `setup` | A shell command run in each new session's folder before the agent starts | Guessed |
| `copy` | Files git doesn't track to copy into each session, as patterns like `*` and `?` | `.env`, `.env.*` |
| `baseBranch` | The branch new sessions start from | The remote's default branch |
| `branchPrefix` | What session branch names start with | `sesh/` |
| `forge` | Where the repository is hosted, when Sesh can't tell. See below. | Detected |
| `teardown` | A shell command run in a session's folder before it's deleted | None |
| `teardownOnArchive` | Also run `teardown` when a session is archived | `false` |
| `ports` | How many ports each session gets for its servers. `0` for none. | `1` |
| `sessionSetup` | A shell command run in every new session's folder after setup, even when setup was skipped. For anything that's different in each session. | None |
| `preparedCopy` | `false` runs setup in every new session instead of starting from a prepared copy | `true` |
| `setupInputs` | More files whose changes mean setup has to run again, besides lockfiles | None |

Setup output shows in the chat as a **Setup** card, and session setup's as a **Session setup** card. If either fails, the agent starts anyway.

## Starting in seconds

Setup can take minutes. So when a session's setup works, Sesh keeps a copy of that folder, and the project's next sessions start from it in a second or two instead of running setup again. The chat says when a session started from the copy.

- Setup runs again on top of the copy when a lockfile or `package.json` changed since, or anything in `.sesh/`. Add other files that matter to `setupInputs`.
- The copy is rebuilt when you change `setup` or `copy`, and after 7 days.
- It needs a disk that can clone files: APFS on a Mac, Btrfs or XFS on Linux. Elsewhere setup runs every time.

Because later sessions reuse what setup made, put anything that's different in each session in `sessionSetup`, which runs every time:

```json
{
  "setup": "pnpm install",
  "sessionSetup": "echo \"PORT=$SESH_SESSION_PORT\" > .env.local"
}
```

If `setup` itself uses a session's own variables (anything but `SESH_ROOT_PATH`), Sesh doesn't keep a copy for it, and the chat says so. If setup does work outside the folder that `sessionSetup` can't take over, set `"preparedCopy": false`.

## Session variables and ports

Setup, teardown, the agent and the session's terminals all get these variables:

| Variable | Value |
|---|---|
| `SESH_SESSION_ID` | The session's ID |
| `SESH_SESSION_NAME` | The session's name |
| `SESH_BRANCH` | The session's branch |
| `SESH_ROOT_PATH` | Your main project folder |
| `SESH_WORKTREE_PATH` | The session's folder |
| `SESH_SESSION_PORT` | A port for this session's server |

No two live sessions on a machine get the same port, so dev servers in parallel sessions don't collide. Tell your server to use it, for example in `package.json`:

```json
"dev": "vite --port ${SESH_SESSION_PORT:-5173}"
```

Need more than one? Set `"ports": 3` to get `SESH_SESSION_PORT`, `SESH_SESSION_PORT_1` and `SESH_SESSION_PORT_2`, one after another. A session keeps its ports until it's archived or deleted. Servers on these ports show in the toolbar like any other.

## Tear down

If a session starts things that outlive it, like containers or a scratch database, start them in `sessionSetup` and undo them in `teardown`:

```json
{
  "setup": "pnpm install",
  "sessionSetup": "docker compose -p \"$SESH_SESSION_ID\" up -d",
  "teardown": "docker compose -p \"$SESH_SESSION_ID\" down -v"
}
```

1. **Delete** runs it in the session's folder before the folder is removed. It shows in the chat as a **Teardown** card.
2. If it fails or runs longer than 2 minutes, the session is deleted anyway, and Sesh shows what went wrong.
3. With `"teardownOnArchive": true`, **Archive** runs it too. Setup and session setup then run again before the agent next starts.

A session nothing has run in yet has nothing to tear down, so teardown is skipped.

## Self-hosted forges

**Create Pull Request** needs to know where the repository lives. Sesh recognizes GitHub, GitLab, Bitbucket, Azure DevOps, Codeberg, Gitea, Forgejo, Tangled and SourceHut, including most self-hosted ones. If it can't tell, set it:

```json
{
  "forge": { "type": "gitlab", "webURL": "https://git.company.com/team/app" }
}
```

`type` is one of `github`, `gitlab`, `bitbucket`, `azure`, `gitea`, `forgejo`, `codeberg`, `tangled` or `sourcehut`.

## Good to know

- `copy` patterns don't support `**`.
- Setup can't be cancelled and has no time limit.
- Teardown reads `.sesh/config.json` from your main project folder, not the session's copy. Sessions with **New branch** off work in that folder itself, so they get no teardown.
- To give sessions ports from another range on a machine, start seshd with `SESH_PORT_RANGE=30000-30999`.
- Secret files you add in Sesh are copied into new sessions too. See [Secrets and variables](https://sesh.codes/docs/secrets-and-variables.md).
