Skip to main content
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 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 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. 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, 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. 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. 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 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 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:
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, 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.