From 6224c13741c57d09c653d8c5b71e5b04eefe222d Mon Sep 17 00:00:00 2001 From: "tembo[bot]" <208362400+tembo[bot]@users.noreply.github.com> Date: Wed, 12 Aug 2026 22:31:09 +0000 Subject: [PATCH 1/2] revert: projects documentation rename Co-authored-by: Darren <68653294+DarrenBaldwin07@users.noreply.github.com> --- beta/agent-post-trigger-hook.mdx | 2 +- docs.json | 6 +- features/projects.mdx | 87 ---------------------- features/sandbox/custom-dependencies.mdx | 2 +- features/sandbox/environment-variables.mdx | 2 +- features/sandbox/overview.mdx | 2 +- features/snapshots.mdx | 73 ++++++++++++++++++ 7 files changed, 78 insertions(+), 96 deletions(-) delete mode 100644 features/projects.mdx create mode 100644 features/snapshots.mdx diff --git a/beta/agent-post-trigger-hook.mdx b/beta/agent-post-trigger-hook.mdx index f01d2f9..7018cfc 100644 --- a/beta/agent-post-trigger-hook.mdx +++ b/beta/agent-post-trigger-hook.mdx @@ -11,7 +11,7 @@ Use post-trigger hooks to provide the agent with context that can be determinist - Post-trigger hooks aren't meant for configuring dependencies. See [Tembo Projects](/features/projects) instead. + Post-trigger hooks aren't meant for configuring dependencies. See [Tembo Snapshots](/features/snapshots) instead. ## Prerequisites diff --git a/docs.json b/docs.json index 315a54d..4c9f246 100644 --- a/docs.json +++ b/docs.json @@ -59,7 +59,7 @@ "features/sandbox/overview", "features/sandbox/custom-dependencies", "features/sandbox/environment-variables", - "features/projects" + "features/snapshots" ] }, { @@ -294,10 +294,6 @@ "source": "/features/coding-agents", "destination": "/features/agents#agent-harness" }, - { - "source": "/features/snapshots", - "destination": "/features/projects" - }, { "source": "/api/task/:slug", "destination": "/api/session/:slug" diff --git a/features/projects.mdx b/features/projects.mdx deleted file mode 100644 index 3e03cc5..0000000 --- a/features/projects.mdx +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: 'Projects' -description: '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. - - - 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/). - - -## 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. - - - 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. 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. - -## 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. - -## 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. diff --git a/features/sandbox/custom-dependencies.mdx b/features/sandbox/custom-dependencies.mdx index d359c16..306371e 100644 --- a/features/sandbox/custom-dependencies.mdx +++ b/features/sandbox/custom-dependencies.mdx @@ -112,4 +112,4 @@ Keep secrets out of `tembo.nix`. Add secrets through your sandbox [environment v - Keep `tembo.nix` focused on system packages and toolchains that your project needs. - Commit the file so Tembo can load it in every new session. -- Use [projects](/features/projects) if installing dependencies still takes meaningful time at the start of each session. +- Use [snapshots](../snapshots) if installing dependencies still takes meaningful time at the start of each session. diff --git a/features/sandbox/environment-variables.mdx b/features/sandbox/environment-variables.mdx index cb0d14e..8bd99a0 100644 --- a/features/sandbox/environment-variables.mdx +++ b/features/sandbox/environment-variables.mdx @@ -38,7 +38,7 @@ Once saved, a variable is available in the sandbox for the whole session. You ca - **Agent commands**: the agent can read the variable when it runs builds, tests, or scripts. - **[Hooks](/features/hooks)**: `setupScript` and `prePush` commands run with the variables set. -- **[Project](/features/projects) setup scripts**: variables are available while a project's environments are built and are baked into anything the setup script writes to disk. +- **[Snapshot](/features/snapshots) setup scripts**: variables are available while a snapshot is built and are baked into anything the setup script writes to disk. - **[MCP servers](/integrations/mcp) and integrations**: reference a variable so a server or integration can authenticate. For example, reference a variable in a `globalMcpServers` definition instead of hardcoding the value: diff --git a/features/sandbox/overview.mdx b/features/sandbox/overview.mdx index c55afe2..6c42afa 100644 --- a/features/sandbox/overview.mdx +++ b/features/sandbox/overview.mdx @@ -9,7 +9,7 @@ Every session runs in its own isolated sandbox. Sandboxes are ephemeral: spun up Your repository is cloned into the sandbox for the duration of a session and torn down when the session ends — no repository contents or working state persist afterward. -The one exception is [projects](/features/projects). When you use a project to speed up environment setup, its repositories and pre-installed dependencies are cached in reusable environments so future sessions start faster. Those cached copies persist until the project is rebuilt or removed. +The one exception is snapshots. If you use the snapshot feature to speed up environment setup, your repository and pre-installed dependencies are cached into a reusable snapshot image so future sessions start faster. That cached copy persists until the snapshot is rebuilt or removed. Model providers handle prompt data according to their own retention policies — see the retention table in [Max](/features/max) for Tembo-hosted models. With [BYOK](/features/models), model requests run against your own provider account, so provider-side retention follows that account's terms. diff --git a/features/snapshots.mdx b/features/snapshots.mdx new file mode 100644 index 0000000..5ff8335 --- /dev/null +++ b/features/snapshots.mdx @@ -0,0 +1,73 @@ +--- +title: 'Snapshots' +description: 'Preload repositories, dependencies, and skills so Tembo sessions start faster.' +--- + +Snapshots are prebuilt VM environments that Tembo can use as the starting point for new sessions. + +Each snapshot builds a full VM disk with your selected repositories, dependencies, and skills already loaded. When a session starts, Tembo can restore from that disk instead of cloning repositories and installing dependencies from scratch. + +This helps sessions spin up quickly, especially for large repositories, monorepos, or projects with slow dependency installs. + + + Snapshots are available on paid plans. If you need access to test them, [book a call with us](https://book.avoma.com/tembo/tembo-demo/). + + +## What snapshots include + +Snapshots can preload the parts of your environment that usually slow down startup: + +- Repositories Tembo should clone before a session starts +- Project dependencies, so agents do not need to install them during the session +- Tembo managed skills, so agents have your workspace instructions available immediately +- The VM disk state needed to restore that environment for future sessions + +Snapshots are built per workspace and can target the sandbox sizes your team uses. + +## Configure snapshots + +Prerequisites: + +- You are on a paid plan. +- You have workspace admin access. +- The repositories and skills you want to preload are already connected to Tembo. + + + Configure [custom dependencies](/features/sandbox/custom-dependencies) before creating a snapshot. Snapshots capture the environment as it exists when they are built, so missing `tembo.nix` dependencies will not be included until you rebuild the snapshot. + + +To configure snapshots: + +1. Open **Settings**. +2. Go to **Snapshots**. +3. Select the repositories to include. +4. Choose whether to preload dependencies and skills. +5. Select one or more sandbox sizes to build. +6. Choose a build schedule. +7. Save your changes. + +Tembo uses the latest successful snapshot for matching new sessions. + +## Setup script + +Use the setup script to add project-specific tooling, dependencies, or other environment setup to your snapshot. Tembo runs the script while the snapshot is being built, after all selected repositories have been cloned to disk. + +The script has access to all [environment variables](/features/sandbox/environment-variables) configured in **Settings** > **Sandbox**, including secrets your setup commands need. Anything the script installs or writes to disk becomes part of the snapshot and is available to sessions that start from it. + +## Sizes and schedules + +You can build snapshots for any number of sandbox sizes. For example, you can keep a small snapshot ready for routine tasks and a larger snapshot ready for heavier builds or test suites. + +You can also build snapshots on a schedule. Scheduled builds keep repositories, dependencies, and skills up to date, so new sessions start from a recent environment instead of a stale one. + +## When to use snapshots + +Use snapshots when your sessions spend meaningful time on environment setup: + +- Large repositories or monorepos +- Slow package installs +- Build systems with expensive setup steps +- Teams that run frequent Tembo sessions against the same repositories +- Workspaces that rely on managed skills for agent behavior + +If your project already starts quickly, you may not need snapshots. They are most useful when setup time is a consistent part of your session runtime. From ddfdbee9806f8f3671b9173f6f651751a8526e84 Mon Sep 17 00:00:00 2001 From: "tembo[bot]" <208362400+tembo[bot]@users.noreply.github.com> Date: Wed, 12 Aug 2026 22:34:33 +0000 Subject: [PATCH 2/2] docs(projects): replace snapshots guide Co-authored-by: Darren <68653294+DarrenBaldwin07@users.noreply.github.com> --- beta/agent-post-trigger-hook.mdx | 2 +- docs.json | 6 +- features/projects.mdx | 87 ++++++++++++++++++++++ features/sandbox/custom-dependencies.mdx | 2 +- features/sandbox/environment-variables.mdx | 2 +- features/sandbox/overview.mdx | 2 +- features/snapshots.mdx | 73 ------------------ 7 files changed, 96 insertions(+), 78 deletions(-) create mode 100644 features/projects.mdx delete mode 100644 features/snapshots.mdx diff --git a/beta/agent-post-trigger-hook.mdx b/beta/agent-post-trigger-hook.mdx index 7018cfc..f01d2f9 100644 --- a/beta/agent-post-trigger-hook.mdx +++ b/beta/agent-post-trigger-hook.mdx @@ -11,7 +11,7 @@ Use post-trigger hooks to provide the agent with context that can be determinist - Post-trigger hooks aren't meant for configuring dependencies. See [Tembo Snapshots](/features/snapshots) instead. + Post-trigger hooks aren't meant for configuring dependencies. See [Tembo Projects](/features/projects) instead. ## Prerequisites diff --git a/docs.json b/docs.json index 4c9f246..315a54d 100644 --- a/docs.json +++ b/docs.json @@ -59,7 +59,7 @@ "features/sandbox/overview", "features/sandbox/custom-dependencies", "features/sandbox/environment-variables", - "features/snapshots" + "features/projects" ] }, { @@ -294,6 +294,10 @@ "source": "/features/coding-agents", "destination": "/features/agents#agent-harness" }, + { + "source": "/features/snapshots", + "destination": "/features/projects" + }, { "source": "/api/task/:slug", "destination": "/api/session/:slug" diff --git a/features/projects.mdx b/features/projects.mdx new file mode 100644 index 0000000..3e03cc5 --- /dev/null +++ b/features/projects.mdx @@ -0,0 +1,87 @@ +--- +title: 'Projects' +description: '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. + + + 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/). + + +## 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. + + + 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. 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. + +## 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. + +## 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. diff --git a/features/sandbox/custom-dependencies.mdx b/features/sandbox/custom-dependencies.mdx index 306371e..d359c16 100644 --- a/features/sandbox/custom-dependencies.mdx +++ b/features/sandbox/custom-dependencies.mdx @@ -112,4 +112,4 @@ Keep secrets out of `tembo.nix`. Add secrets through your sandbox [environment v - Keep `tembo.nix` focused on system packages and toolchains that your project needs. - Commit the file so Tembo can load it in every new session. -- Use [snapshots](../snapshots) if installing dependencies still takes meaningful time at the start of each session. +- Use [projects](/features/projects) if installing dependencies still takes meaningful time at the start of each session. diff --git a/features/sandbox/environment-variables.mdx b/features/sandbox/environment-variables.mdx index 8bd99a0..cb0d14e 100644 --- a/features/sandbox/environment-variables.mdx +++ b/features/sandbox/environment-variables.mdx @@ -38,7 +38,7 @@ Once saved, a variable is available in the sandbox for the whole session. You ca - **Agent commands**: the agent can read the variable when it runs builds, tests, or scripts. - **[Hooks](/features/hooks)**: `setupScript` and `prePush` commands run with the variables set. -- **[Snapshot](/features/snapshots) setup scripts**: variables are available while a snapshot is built and are baked into anything the setup script writes to disk. +- **[Project](/features/projects) setup scripts**: variables are available while a project's environments are built and are baked into anything the setup script writes to disk. - **[MCP servers](/integrations/mcp) and integrations**: reference a variable so a server or integration can authenticate. For example, reference a variable in a `globalMcpServers` definition instead of hardcoding the value: diff --git a/features/sandbox/overview.mdx b/features/sandbox/overview.mdx index 6c42afa..c55afe2 100644 --- a/features/sandbox/overview.mdx +++ b/features/sandbox/overview.mdx @@ -9,7 +9,7 @@ Every session runs in its own isolated sandbox. Sandboxes are ephemeral: spun up Your repository is cloned into the sandbox for the duration of a session and torn down when the session ends — no repository contents or working state persist afterward. -The one exception is snapshots. If you use the snapshot feature to speed up environment setup, your repository and pre-installed dependencies are cached into a reusable snapshot image so future sessions start faster. That cached copy persists until the snapshot is rebuilt or removed. +The one exception is [projects](/features/projects). When you use a project to speed up environment setup, its repositories and pre-installed dependencies are cached in reusable environments so future sessions start faster. Those cached copies persist until the project is rebuilt or removed. Model providers handle prompt data according to their own retention policies — see the retention table in [Max](/features/max) for Tembo-hosted models. With [BYOK](/features/models), model requests run against your own provider account, so provider-side retention follows that account's terms. diff --git a/features/snapshots.mdx b/features/snapshots.mdx deleted file mode 100644 index 5ff8335..0000000 --- a/features/snapshots.mdx +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: 'Snapshots' -description: 'Preload repositories, dependencies, and skills so Tembo sessions start faster.' ---- - -Snapshots are prebuilt VM environments that Tembo can use as the starting point for new sessions. - -Each snapshot builds a full VM disk with your selected repositories, dependencies, and skills already loaded. When a session starts, Tembo can restore from that disk instead of cloning repositories and installing dependencies from scratch. - -This helps sessions spin up quickly, especially for large repositories, monorepos, or projects with slow dependency installs. - - - Snapshots are available on paid plans. If you need access to test them, [book a call with us](https://book.avoma.com/tembo/tembo-demo/). - - -## What snapshots include - -Snapshots can preload the parts of your environment that usually slow down startup: - -- Repositories Tembo should clone before a session starts -- Project dependencies, so agents do not need to install them during the session -- Tembo managed skills, so agents have your workspace instructions available immediately -- The VM disk state needed to restore that environment for future sessions - -Snapshots are built per workspace and can target the sandbox sizes your team uses. - -## Configure snapshots - -Prerequisites: - -- You are on a paid plan. -- You have workspace admin access. -- The repositories and skills you want to preload are already connected to Tembo. - - - Configure [custom dependencies](/features/sandbox/custom-dependencies) before creating a snapshot. Snapshots capture the environment as it exists when they are built, so missing `tembo.nix` dependencies will not be included until you rebuild the snapshot. - - -To configure snapshots: - -1. Open **Settings**. -2. Go to **Snapshots**. -3. Select the repositories to include. -4. Choose whether to preload dependencies and skills. -5. Select one or more sandbox sizes to build. -6. Choose a build schedule. -7. Save your changes. - -Tembo uses the latest successful snapshot for matching new sessions. - -## Setup script - -Use the setup script to add project-specific tooling, dependencies, or other environment setup to your snapshot. Tembo runs the script while the snapshot is being built, after all selected repositories have been cloned to disk. - -The script has access to all [environment variables](/features/sandbox/environment-variables) configured in **Settings** > **Sandbox**, including secrets your setup commands need. Anything the script installs or writes to disk becomes part of the snapshot and is available to sessions that start from it. - -## Sizes and schedules - -You can build snapshots for any number of sandbox sizes. For example, you can keep a small snapshot ready for routine tasks and a larger snapshot ready for heavier builds or test suites. - -You can also build snapshots on a schedule. Scheduled builds keep repositories, dependencies, and skills up to date, so new sessions start from a recent environment instead of a stale one. - -## When to use snapshots - -Use snapshots when your sessions spend meaningful time on environment setup: - -- Large repositories or monorepos -- Slow package installs -- Build systems with expensive setup steps -- Teams that run frequent Tembo sessions against the same repositories -- Workspaces that rely on managed skills for agent behavior - -If your project already starts quickly, you may not need snapshots. They are most useful when setup time is a consistent part of your session runtime.