> ## Documentation Index
> Fetch the complete documentation index at: https://test-8862363a-tembo-byod-custom-dependencies.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Projects

> Create reusable environments so Tembo sessions start with the right repositories, dependencies, and skills.

Projects are reusable environments for Tembo sessions. A project defines the repositories, workspace skills, dependencies, setup script, and session sizes that a team uses for a particular codebase or workflow.

Tembo prepares an environment for each selected session size. When you start a session from that project, Tembo restores the prepared environment instead of cloning repositories and installing dependencies from scratch. This is especially useful for large repositories, monorepos, and projects with slow dependency installs.

<Note>
  Projects are available on paid plans. If you need access to test them, [book a call with us](https://book.avoma.com/tembo/tembo-demo/).
</Note>

## What projects include

A project can define:

* One, multiple, all, or no connected repositories
* Workspace skills that should be available in every session
* Repository dependencies to install before sessions start
* A setup script for additional project-specific preparation
* One or more session sizes that people can choose when starting a session
* A daily refresh schedule

Each project can have its own name, icon, and color so people can distinguish it in the session composer and sidebar.

## Create a project

Prerequisites:

* You are on a paid plan.
* You have workspace admin access.
* Any repositories you want to include are already connected to Tembo.

<Warning>
  Configure [custom dependencies](/features/sandbox/custom-dependencies) before building a project. Project builds capture the environment as it exists at build time, so missing `tembo.nix` dependencies are not included until you rebuild the environment.
</Warning>

To create a project:

1. Open **Settings** > **Projects**.
2. Click **New project**.
3. Choose a name, icon, and color.
4. Select the repositories to make available in project sessions.
5. Choose whether to include workspace skills and install repository dependencies.
6. Under **Advanced setup**, optionally add a setup script.
7. Select the session sizes the project should support.
8. Optionally enable **Refresh every day** and choose a time.
9. Click **Create project**.
10. Open the project and click **Build environment**.

Tembo prepares a separate environment for each selected session size. You can start prepared sessions as each environment becomes ready.

## Start a session from a project

Before you start a session, open the project and size selector in the session composer. Choose a project, then choose one of its supported session sizes.

Selecting a project also selects the repositories included in that project. You can change the project before the session starts, but not while a session is running.

## Project environment variables

Add environment variables to a project when you only need them while that project's environments are built. Project variables are combined with [workspace-wide environment variables](/features/sandbox/environment-variables). If both scopes use the same key, the project value takes precedence.

To add project-level environment variables:

1. Open **Settings** > **Projects**.
2. Select the project.
3. Under **Environment variables**, click **Create Secret**.
4. Add a single variable or bulk import `.env`-style contents.
5. Click **Create Secret**.
6. Build or rebuild the project's environment to apply the variables.

## Setup script

Use the setup script for preparation that is not handled by repository dependency installation or [`tembo.nix`](/features/sandbox/custom-dependencies). Tembo runs the script while building the project's environments, after it clones the selected repositories.

The script has access to workspace-wide [environment variables](/features/sandbox/environment-variables) and any environment variables added to the project. Anything the script installs or writes to disk becomes part of the prepared environment.

### Keep setup logic in your repository

To version your setup logic with the rest of your code, commit a script to your repository and call it from the project setup script. For example, if a repository named `my-app` contains `scripts/tembo-setup.sh`, use:

```bash theme={null}
cd /workspace/my-app
bash scripts/tembo-setup.sh
```

Project setup scripts run from `/workspace`. Tembo clones a repository with a unique name into `/workspace/<repository-name>`. Repository names are lowercased, and unsupported characters are replaced with hyphens. If multiple selected repositories resolve to the same directory name, Tembo clones each one into `/workspace/<repository-id>-<repository-name>` instead.

## Session sizes and daily refreshes

A project must support at least one session size. If you select several sizes, Tembo builds and maintains a separate prepared environment for each one. People starting a session from the project can choose among those sizes.

Enable **Refresh every day** to pull the latest repository changes and run the project's setup again each day. The refresh time is shown in your local time.

You can also open a project and click **Rebuild environment** at any time. A rebuild pulls the latest repository changes and reruns setup for every selected size. New sessions use an environment when it is ready; running sessions are not affected. If a rebuild fails, the current prepared environments remain active.

## When to use projects

In general, you should always use a project, even if your workspace only needs one. A project gives sessions a consistent set of repositories, tools, and defaults while reducing setup time.

Use projects when a team repeatedly starts sessions with the same context or spends meaningful time on environment setup, for example:

* Large repositories or monorepos
* Slow package installs
* Build systems with expensive setup steps
* Workflows that use a consistent set of repositories
* Teams that rely on shared workspace skills
* Work that needs different prepared environments or session sizes

If a session does not need a prepared environment, select **No project** in the composer.