> ## Documentation Index > Fetch the complete documentation index at: https://test-8862363a-tembo-docs-commit-attribution-preference.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, default agent instructions, 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. Projects are available on paid plans. Upgrade in **Settings** > **Billing**, or [book a call with us](https://book.avoma.com/tembo/tembo-demo/) if you need access to test them. ## 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 * Default agent instructions included in every session from the project * 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. Project names must be unique in the workspace. ## 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. 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. 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. Optionally add **Default agent instructions**. 8. Select the session sizes the project should support. 9. Optionally enable **Refresh every day** and choose a time. 10. Click **Create project**. Tembo automatically starts building an environment for each selected session size. Tembo prepares a separate environment for each selected session size. You can start prepared sessions as each environment becomes ready. Tembo cannot build an environment if the project has no repositories to clone, no setup script, and workspace skills turned off. ## 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. Sessions from a project can only use the sizes that project builds. See [sandbox sizes](/features/sandbox/overview#sandbox-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. The sidebar groups sessions by project. From a project there, you can start a new session or open the project to edit it. If a session does not need a prepared environment, select **No project** in the composer. ## Default project Workspace admins can set a default project and size in **Settings** > **Sandbox**. New sessions across the workspace use that project and size unless someone picks a different one in the composer. A project can be the default only for sizes it builds. If more than one project exists, each size has at most one default project. ## Default agent instructions Add **Default agent instructions** when you create or edit a project. Tembo includes them in every session started from that project, as guidance for how the agent should work. Use this for coding conventions, testing expectations, or other project-specific guidance that should apply even when the session prompt is different. Changing these instructions applies to new sessions without rebuilding the environment. ## Use a project with agents When you create or edit an [agent](/features/agents), select a project in its run options. Triggered and scheduled runs then start from that project's prepared environment and repositories. ## 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. A project can have at most 100 environment variables. Keys must be unique, values are encrypted and write-only after you save them, and rotating a value means deleting the variable and creating it again. ## 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. This project setup script is separate from the `setupScript` [hook](/features/hooks) in `.tembo.json`. The `.tembo.json` hook runs during the environment build only when **Install dependencies** is enabled, while the project setup script runs whenever it is configured. Sessions restored from a prepared environment do not run the `.tembo.json` hook at startup. Rebuild the project environment after changing setup commands so new sessions pick them up. ### 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 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/-` instead. ## Session sizes, builds, 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 **Build environment** or **Rebuild environment**. The first successful build for a size makes that environment available. 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. Each project keeps a build history. You can: * Open a build or environment to view its log and progress * Cancel a queued or running build * Pin a successful build so new sessions keep using that environment instead of the latest successful one * Switch back to the latest successful build * Rebuild a single environment, or delete an old one Rebuild the environment after changing anything captured at build time, such as repositories, dependencies, the setup script, or environment variables. ## Edit or delete a project Open a project from **Settings** > **Projects** to change its appearance, repositories, setup, instructions, sizes, or schedule, then save. Only workspace admins can edit or delete projects. Deleting a project archives it and disables its refresh schedule. Running sessions are not affected. ## 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 ## API You can also create and manage projects through the [Projects API](/api/v1/projects/list-projects).