# Create Agent
Source: https://docs.tembo.io/api/create-agent
/openapi.documented.yml post /agent
Create a new agent for your organization.
# Create Session
Source: https://docs.tembo.io/api/create-session
/openapi.documented.yml post /session/create
Create a session for tembo to start working on in the background
# Overview
Source: https://docs.tembo.io/api/index
Create sessions, manage repositories, and automate workflows programmatically.
View the API documentation for self-hosted Tembo deployments.
## Authentication
Generate an API key from **Settings > API Keys** in the [dashboard](https://app.tembo.io).
```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://api.tembo.io/session/list
```
## SDK
```bash npm theme={null}
npm install @tembo-io/sdk
```
```bash yarn theme={null}
yarn add @tembo-io/sdk
```
```bash pnpm theme={null}
pnpm add @tembo-io/sdk
```
```bash bun theme={null}
bun add @tembo-io/sdk
```
```javascript theme={null}
import Tembo from '@tembo-io/sdk';
const client = new Tembo({
apiKey: process.env.TEMBO_API_KEY,
});
const session = await client.session.create({
prompt: 'Fix the authentication bug in the login component',
repositories: ['https://github.com/org/repo'],
});
```
## Rate limits
100 requests per minute per API key. 1,000 requests per hour per organization.
# List Repositories
Source: https://docs.tembo.io/api/list-repositories
/openapi.documented.yml get /repository/list
Gets a list of enabled repositories for the organization
# List Sessions
Source: https://docs.tembo.io/api/list-sessions
/openapi.documented.yml get /session/list
Gets a paginated list of sessions for the organization
# Search Sessions
Source: https://docs.tembo.io/api/search-sessions
/openapi.documented.yml get /session/search
Search sessions for the organization with pagination
# Create Agent
Source: https://docs.tembo.io/api/self-hosted/create-agent
/openapi.self-hosted.yml post /agent
Create a new agent for your organization.
# Create Session
Source: https://docs.tembo.io/api/self-hosted/create-session
/openapi.self-hosted.yml post /session/create
Create a session for tembo to start working on in the background
# Self-Hosted API Overview
Source: https://docs.tembo.io/api/self-hosted/index
Create sessions, manage repositories, and automate workflows in your self-hosted Tembo instance.
## Authentication
Generate an API key from **Settings > API Keys** in your self-hosted Tembo dashboard.
Replace `tembo.example.com` with the hostname of your Tembo instance.
```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://tembo.example.com/api/public-api/session/list
```
## SDK
```bash npm theme={null}
npm install @tembo-io/sdk
```
```bash yarn theme={null}
yarn add @tembo-io/sdk
```
```bash pnpm theme={null}
pnpm add @tembo-io/sdk
```
```bash bun theme={null}
bun add @tembo-io/sdk
```
```javascript theme={null}
import Tembo from '@tembo-io/sdk';
const client = new Tembo({
apiKey: process.env.TEMBO_API_KEY,
baseURL: 'https://tembo.example.com/api/public-api/',
});
const session = await client.session.create({
prompt: 'Fix the authentication bug in the login component',
repositories: ['https://github.com/org/repo'],
});
```
## Rate limits
100 requests per minute per API key. 1,000 requests per hour per organization.
# List Repositories
Source: https://docs.tembo.io/api/self-hosted/list-repositories
/openapi.self-hosted.yml get /repository/list
Gets a list of enabled repositories for the organization
# List Sessions
Source: https://docs.tembo.io/api/self-hosted/list-sessions
/openapi.self-hosted.yml get /session/list
Gets a paginated list of sessions for the organization
# Search Sessions
Source: https://docs.tembo.io/api/self-hosted/search-sessions
/openapi.self-hosted.yml get /session/search
Search sessions for the organization with pagination
# Send Session Message
Source: https://docs.tembo.io/api/self-hosted/send-session-message
/openapi.self-hosted.yml post /session/{sessionId}/messages
Create a message for an existing session and queue a follow-up job
# Stop Session
Source: https://docs.tembo.io/api/self-hosted/stop-session
/openapi.self-hosted.yml post /session/{sessionId}/stop
Stop all running sandbox sessions, runtime sessions, and jobs for a session
# Trigger Agent
Source: https://docs.tembo.io/api/self-hosted/trigger-agent
/openapi.self-hosted.yml post /agent/{keyOrId}/trigger
Trigger an agent with an arbitrary JSON payload, which is passed to the agent as event context.
You can identify the agent by either its UUID or its macro (key). The API key can be supplied via the `Authorization: Bearer` header or the `apiKey` query parameter.
# Send Session Message
Source: https://docs.tembo.io/api/send-session-message
/openapi.documented.yml post /session/{sessionId}/messages
Create a message for an existing session and queue a follow-up job
# Stop Session
Source: https://docs.tembo.io/api/stop-session
/openapi.documented.yml post /session/{sessionId}/stop
Stop all running sandbox sessions, runtime sessions, and jobs for a session
# Trigger Agent
Source: https://docs.tembo.io/api/trigger-agent
POST /agent/{keyOrId}/trigger
Trigger an agent with an arbitrary JSON payload.
# Agent Actions
Source: https://docs.tembo.io/features/agent-actions
Tembo agents can do more than open PRs.
Pull requests are the most common output, but Tembo agents can take any action available through your connected integrations and [MCP servers](/integrations/mcp).
A single session can span multiple repositories. Tembo can use context from connected integrations and MCP servers during the same session, make informed decisions, and open a pull request or merge request in each affected repository. It can also coordinate changes across different git providers when needed.
## What agents can do
| Action | Integration |
| ------------------------------------- | ------------------------------------- |
| Open and update pull requests | GitHub, GitLab, Bitbucket |
| Post messages and summaries | Slack |
| Create, update, and comment on issues | Linear, Jira |
| Create and update pages | Notion |
| Query databases | Postgres, Supabase, Neon, PlanetScale |
| Analyze errors and stack traces | Sentry |
| Run browser automation | Kernel (Playwright) |
| Access analytics and feature flags | PostHog |
| Manage users and auth | Clerk |
| Access payments and subscriptions | Stripe |
| Access CRM data | Attio |
## Examples
**Triage a Linear ticket in Slack**: A Slack message triggers Tembo to read the Linear ticket, scan the codebase for context, and post an explanation back to the Slack thread.
**Summarize Sentry errors**: A daily agent fetches errors from Sentry, ranks them by impact, creates Linear tickets, and posts a summary to Slack.
**Enrich issues with context**: When a new issue is created, Tembo searches the codebase, pulls related Notion docs, and adds implementation hints as a comment.
**Query production data**: During a session, an agent queries your Postgres database to understand the schema and writes a migration based on actual table structure.
**Ship a cross-repo change**: One session updates multiple services, uses Linear and Sentry context to verify the work, and opens a PR or MR in each affected repository.
## How it works
Agents access integrations through MCP servers. When you connect an integration or install an MCP server, it becomes available to agents during sessions and scheduled runs. No extra configuration needed.
See [MCP](/integrations/mcp) for available servers.
# Agent Skills
Source: https://docs.tembo.io/features/agent-skills
Guide how agents approach sessions with custom skills in your repository.
Skills are instructions that live in your repository and guide how agents approach work. They help agents follow multi-step processes like research, planning, implementation, and review instead of doing everything in a single pass.
## How it works
Place skills in the dotfile directory for your coding agent at the root of your repository:
* `.claude/` for Claude Code
* `.codex/` for Codex
* `.opencode/` for OpenCode
* `.cursor/` for Cursor
The agent picks up these skills when working on sessions in that repo. You need to instruct the agent to use a skill, either in the session description or after a PR is opened via the [feedback loop](/features/feedback-loop):
```
@tembo Use the implementation skill for this session
```
```
@tembo Now use the code-review skill to review your changes
```
## Example
A skill that guides the agent through a structured implementation flow:
```markdown theme={null}
# Implementation Skill
1. Research the codebase to understand existing patterns
2. Create a plan with specific files and changes
3. Implement the plan following project conventions
4. Run tests and fix any failures
5. Self-review the diff before opening a PR
```
## What skills are good for
* Enforcing a research-then-implement workflow
* Requiring test coverage before opening a PR
* Defining code review checklists the agent runs against its own output
* Setting quality thresholds for different session types
## What's coming
We're building first-party skill support and planning mode so Tembo can handle work in staged steps:
**Research → Plan → Implement → Review → Iterate**
This will improve PR quality on larger sessions, where today the agent may need a few iterations before the output is merge-ready. [Rule files](/features/rule-files) and skills in dotfile directories are the best way to guide agents today.
## Tembo Managed Skills
You can also create and manage skills directly in Tembo.
Open **Settings** → **Skills** to:
* Add a new skill
* Give it a name and description
* Write the main instructions in `SKILL.md`
* Add extra reference files if needed
* Edit or delete existing skills
Tembo managed skills are stored in your workspace settings and loaded into sessions automatically when Tembo runs an agent.
# Agents
Source: https://docs.tembo.io/features/agents
Run coding agents on a schedule or triggered by events.
Run coding agents in the background, on a schedule or triggered by events. A Sentry error gets fixed within seconds. Docs stay in sync with your code. Security vulnerabilities get caught before they become problems.
Each agent runs in a secure [sandbox](/features/sandbox/overview) with full codebase and repository access and your configured [MCP servers](/integrations/mcp).
## Agent harness
Tembo is harness and model agnostic. For each agent you configure, you pick the harness (and model) that runs in the session it spawns, for example Claude Code with Sonnet 4.6, Codex with GPT-5.4, or Cursor. Set a default per agent, or override per session.
See [Models](/features/models) for the full supported model list, BYOK details, and AWS Bedrock BYOK support.
}>
Anthropic's Claude models. Best balance of quality, reliability, and cost.
**Models:** Opus 5, Fable 5, Sonnet 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 4.6, Opus 4.5, Haiku 4.5
}>
OpenAI's GPT-5 family with configurable reasoning effort (minimal, low, medium, high).
**Models:** GPT-5.6 Sol, GPT-5.6 Terra, GPT-5.6 Luna, GPT-5.5 Pro, GPT-5.5, GPT-5.4, GPT-5.3 Codex, GPT-5.4 Mini, GPT-5.4 Nano
}>
Multi-provider via Cursor CLI.
**Models:** Composer 2.5, Composer 2, Composer 2 Fast, Composer 1.5, Opus 5, Sonnet 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 4.6, Opus 4.5, GPT-5.6 Sol, GPT-5.6 Terra, GPT-5.5, GPT-5.3 Codex, GPT-5.3 Codex Spark, Gemini 3.1 Pro, Gemini 3.5 Flash, Grok
}>
Multi-provider support: Anthropic, OpenAI, and OSS models.
**Models:** Opus 5, Fable 5, Sonnet 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 4.6, Opus 4.5, Haiku 4.5, GPT-5.6 Sol, GPT-5.6 Terra, GPT-5.6 Luna, GPT-5.5 Pro, GPT-5.5, GPT-5.4, GPT-5.3 Codex, GPT-5.4 Mini, GPT-5.4 Nano, Gemini 3.1 Pro, Gemini 3.5 Flash, GLM 5.2, Kimi K3, Kimi K2.6, Kimi K2.7 Code, DeepSeek V4 Pro, DeepSeek V4 Flash, MiniMax M2.7, MiniMax M3
}>
Claude-powered with automatic model selection.
}>
A minimal, extensible terminal coding harness with multi-provider support.
**Models:** Opus 5, Fable 5, Sonnet 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 4.6, Opus 4.5, Haiku 4.5, GPT-5.6 Sol, GPT-5.6 Terra, GPT-5.6 Luna, GPT-5.5 Pro, GPT-5.5, GPT-5.4, GPT-5.3 Codex, GPT-5.4 Mini, GPT-5.4 Nano, GPT-5.2, GLM 5.2, Kimi K3, Kimi K2.6, Kimi K2.7 Code, DeepSeek V4 Pro, DeepSeek V4 Flash, MiniMax M2.7, MiniMax M3
## Triggers
These are just examples to give you a rough idea. You decide how to set this up, there are no limitations.
### Scheduled
Run agents at regular intervals.
| Schedule | Example |
| ----------- | ------------------------------------------- |
| **Hourly** | Monitor for CI failures, new Sentry errors |
| **Daily** | Generate changelogs, post standup summaries |
| **Weekly** | Clean up stale TODOs, security scans |
| **Monthly** | Dependency audits, documentation reviews |
### Event-driven
React to events from your integrations in real-time.
| Integration | Events |
| ----------- | -------------------------------------------------- |
| **GitHub** | PR opened, PR merged, issue created, comment added |
| **GitLab** | Merge request opened, merged, issue created |
| **Sentry** | New error, error spike, regression detected |
| **Linear** | Issue created, issue updated, status changed |
| **Slack** | Message in channel, @tembo mention |
#### Trigger through webhooks
You can trigger an agent on demand from external systems using the agent's [webhook trigger endpoint](/api/trigger-agent).
The payload is passed to the agent as event context, so your instructions can reference it directly. For example, you could write instructions like *"Fix the issue at the URL provided in the event payload"*.
## Creating an agent
### From a template
1. Go to **Agents** in the [dashboard](https://app.tembo.io)
2. Click **Templates**
3. Pick a template and click **Use template**
4. Customize the instructions and enable
[Browse all templates](https://tembo.io/for)
### From scratch
1. Click **New Agent**
2. Write your instructions
3. Add triggers (schedule and/or event-based)
4. Select [agent harness](#agent-harness)
5. Instruct MCP servers or integrations
6. Save and enable
## Macros
You can trigger a specific agent on demand from anywhere you can mention `@tembo` by using its macro.
```txt theme={null}
@tembo !
```
Tembo routes the request to the agent with that macro and passes the rest of the message as the prompt.
For example, this triggers the agent named `review`:
```txt theme={null}
@tembo !review please review this PR
```
## Beyond code
Agents aren't limited to engineering work. With [MCP servers](/integrations/mcp), agents can work across your entire stack.
| Example | Trigger | What it does |
| ----------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Daily ARR report | Daily | Pulls revenue data from [Stripe](/integrations/mcp) and posts to [Slack](/integrations/slack) |
| Feature requests from calls | Daily | Scans call transcripts for feature requests and creates [Linear](/integrations/linear) tickets |
| Customer health check | Weekly | Summarizes support tickets, usage trends, and churn signals in [Slack](/integrations/slack) |
| Enrich CRM records | New deal created | Pulls company info and adds context to [Attio](/integrations/mcp) or your CRM |
| Create CRM tickets from Slack | `@tembo` in [Slack](/integrations/slack) | Creates a ticket in your CRM enriched with context from other connected integrations |
Any tool with an [MCP server](/integrations/mcp) can be used as an agent.
You can also do this on-demand from [Slack](/integrations/slack) without setting up an agent:
```
@tembo What's our ARR right now? Check Stripe.
```
```
@tembo Summarize the feature requests from this week's sales calls and create Linear tickets for the top 5.
```
# Feedback Loop
Source: https://docs.tembo.io/features/feedback-loop
Iterate on Tembo's work just like you would with any teammate.
Mention `@tembo` in a PR comment to request changes. Tembo updates the code and pushes new commits. Keep iterating until it's right.
* **Inline review comments**: Comment on specific lines. Tembo knows exactly which code you mean.
* **Regular comments**: Comment anywhere on the PR.
* **Slack threads**: If the session started from Slack, keep mentioning `@tembo` in the same thread.
On Bitbucket, use `/tembo` instead of `@tembo`.
Only comments that mention `@tembo` are picked up.
## Examples
```
@tembo Add retry logic with exponential backoff and a unit test
```
```
@tembo This function should handle the case where the user doesn't exist
```
## Multi-repo
Feedback on one PR can trigger changes across all connected repos. Tembo updates existing PRs and creates new ones where needed.
# Hooks
Source: https://docs.tembo.io/features/hooks
Run custom setup and pre-push commands during a session.
Hooks run shell commands at specific points during a session. Configure them in `.tembo.json` at your repository root.
## Available hooks
**`setupScript`** - Runs after Tembo clones your repo, before it starts working.
**`prePush`** - Runs after Tembo makes changes, before pushing and opening a PR.
## Example
```json theme={null}
{
"hooks": {
"setupScript": [
"npm ci",
"cp .env.example .env.local"
],
"prePush": [
"npm run lint",
"npm run test",
"npm run build"
]
}
}
```
## Details
* Commands run sequentially in the repository root
* If a command fails, Tembo logs the failure and continues with the remaining commands in the hook
* Hooks run in the same [sandbox](/features/sandbox/overview) as the session
* Shell features (piping, redirects, `&&`) are supported
# Model Settings
Source: https://docs.tembo.io/features/model-settings
Configure default agents, provider keys, custom MCP servers, and model availability.
Use **Settings > Models** in the [dashboard](https://app.tembo.io) to control how your workspace selects and runs models.
## Default agent
Set the default agent and model Tembo uses for new sessions and automations.
* Pick the workspace default from a single dropdown in **Settings > Models**
* You can still override agent/model per session or automation
### Personal default agent
You can set your own default agent and model in **Settings > Preferences**. Your personal default takes priority over the workspace default for your own sessions.
## Provider API keys
You can manage model provider credentials in one place:
* Anthropic API key
* OpenAI API key
* Amp API key
* Cursor API key
* OpenRouter API key
* AWS Bedrock access key, secret key, and region
Keys are saved at the workspace level and used when a selected model requires that provider.
## Custom MCP servers (global JSON)
`globalMcpServers` lets you define shared MCP servers available across sessions and automations.
```json theme={null}
{
"mcpServers": {
"my-server": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "your-github-token"
}
}
}
}
```
This JSON is workspace-wide. Invalid JSON is rejected when you save.
## Available models
The **Available Models** list lets you enable or disable specific models for your organization.
* Models are enabled by default
* Org admins can toggle models on/off
* Non-admin members can view status but cannot change it
You cannot disable the model currently used by your default agent. Change the default agent model first.
# Models
Source: https://docs.tembo.io/features/models
Supported models, providers, and BYOK options.
Tembo supports multiple model providers across coding agents. The Free plan includes select open-source models through Tembo Managed Inference, while paid plans unlock the full managed model catalog. You can also connect your own model access with BYOK (Bring Your Own Key) or a ChatGPT subscription.
## BYOK (Bring Your Own Key)
BYOK lets your workspace call models with your own provider credentials instead of Tembo-managed credentials.
* Add keys in **Settings -> Models -> API Keys**.
* You can connect OpenAI, Anthropic, Cursor, Amp, and OpenRouter credentials on every Tembo plan, including Free.
* AWS Bedrock and GCP Vertex AI credentials require a paid Tembo plan.
* Tembo still handles orchestration, session context, sandbox execution, and PR automation.
BYOK inference costs \$0 through Tembo. Sessions still use billable cloud VM compute, which draws from your workspace's [usage allowance](/resources/pricing).
### Switch a model between BYOK and Tembo Managed Inference
Workspace admins can change the inference provider for individual models from **Settings -> Models**.
In **Available Models**, use the model's **Inference** dropdown to choose **BYOK** or **Tembo Managed Inference**, when those options are available for that model and workspace.
### Bedrock BYOK support
Tembo supports BYOK with Amazon Bedrock.
To enable it, add:
* **AWS Access Key ID**
* **AWS Secret Access Key**
* **AWS Region**
in **Settings -> Models -> API Keys -> AWS Bedrock**.
### GCP Vertex AI BYOK support
Tembo supports BYOK with GCP Vertex AI.
To enable it, add:
* **Service account JSON**
* **Project ID**
* **Location**
in **Settings -> Models -> API Keys -> GCP Vertex AI**.
## Connect a ChatGPT subscription
You can connect a ChatGPT subscription on every Tembo plan, including Free, to use supported OpenAI models with Codex, OpenCode, or Pi. You need a ChatGPT Plus, Pro, Business, Edu, or Enterprise plan.
1. Open **Settings > Connected accounts**.
2. Under **LLM subscriptions**, click **Connect Codex**.
3. Copy the authorization code, then click **Open authorization page**.
4. Enter the code in ChatGPT and approve the connection. Keep the Tembo dialog open while authorization completes.
5. Return to Tembo and confirm that **ChatGPT Codex** shows **Connected**.
If prompted, enable device code authorization in [ChatGPT Settings > Security](https://chatgpt.com/settings/security), then try connecting again.
## Supported models
The table below reflects the models currently supported by Tembo.
| Model | Model ID | Provider | BYOK Required |
| ------------------- | --------------------- | --------- | ------------- |
| Opus 5 | `claude-opus-5` | Anthropic | No |
| Fable 5 | `claude-fable-5` | Anthropic | No |
| Sonnet 5 | `claude-sonnet-5` | Anthropic | No |
| Opus 4.8 | `claude-opus-4-8` | Anthropic | No |
| Opus 4.7 | `claude-opus-4-7` | Anthropic | No |
| Opus 4.6 | `claude-opus-4-6` | Anthropic | No |
| Sonnet 4.6 | `claude-sonnet-4-6` | Anthropic | No |
| Opus 4.5 | `claude-opus-4-5` | Anthropic | No |
| Haiku 4.5 | `claude-4-5-haiku` | Anthropic | No |
| GPT-5.6 Sol | `gpt-5.6-sol` | OpenAI | Yes |
| GPT-5.6 Terra | `gpt-5.6-terra` | OpenAI | Yes |
| GPT-5.6 Luna | `gpt-5.6-luna` | OpenAI | Yes |
| GPT-5.5 Pro | `gpt-5.5-pro` | OpenAI | Yes |
| GPT-5.5 | `gpt-5.5` | OpenAI | Yes |
| GPT-5.4 | `gpt-5.4` | OpenAI | Yes |
| GPT-5.4 Mini | `gpt-5.4-mini` | OpenAI | No |
| GPT-5.4 Nano | `gpt-5.4-nano` | OpenAI | No |
| GPT-5.3 Codex | `gpt-5.3-codex` | OpenAI | No |
| GPT-5.3 Codex Spark | `gpt-5.3-codex-spark` | OpenAI | Yes |
| GPT-5.2 Codex | `gpt-5.2-codex` | OpenAI | No |
| GPT-5.2 | `gpt-5.2` | OpenAI | Yes |
| GLM 5.2 | `glm-5p2` | Z.ai | No |
| Composer 1.5 | `composer-1.5` | Cursor | Yes |
| Composer 2 | `composer-2` | Cursor | Yes |
| Composer 2 Fast | `composer-2-fast` | Cursor | Yes |
| Composer 2.5 | `composer-2.5` | Cursor | Yes |
| Gemini 3.1 Pro | `gemini-3.1-pro` | Google | No |
| Gemini 3.5 Flash | `gemini-3.5-flash` | Google | No |
| Grok | `grok` | xAI | Yes |
| Kimi K3 | `kimi-k3` | Fireworks | No |
| Kimi K2.6 | `kimi-k2p6` | Fireworks | No |
| Kimi K2.7 Code | `kimi-k2p7-code` | Fireworks | No |
| MiniMax M2.7 | `minimax-m2p7` | MiniMax | No |
| MiniMax M3 | `minimax-m3` | MiniMax | No |
| DeepSeek V4 Pro | `deepseek-v4-pro` | DeepSeek | No |
| DeepSeek V4 Flash | `deepseek-v4-flash` | DeepSeek | No |
Model availability can vary by agent and workspace configuration. If a model is disabled in your workspace, it will not appear in agent pickers until re-enabled.
# Pull Requests
Source: https://docs.tembo.io/features/pull-requests
Tembo opens PRs with clear descriptions, signed commits, and your PR template.
When a session is complete, Tembo opens a pull request. You review it, use the [feedback loop](/features/feedback-loop) to iterate, and merge when ready.
If a session spans multiple repositories, Tembo opens a pull request or merge request in each one. It can also coordinate changes across supported git providers, including GitHub, GitLab, and Bitbucket.
## What's in a Tembo PR
* Clear description of the problem and solution
* Follows your coding standards via [rule files](/features/rule-files)
* Links to the original issue, error, or session
* Tests when appropriate
* Signed and verified commits (GitHub)
* Uses your PR template if one exists
## PR templates
Tembo checks for templates in these locations:
* `/.github/pull_request_template.md`
* `/docs/pull_request_template.md`
* `/pull_request_template.md`
## Advanced
GitHub PRs are automatically signed with a "Verified" badge. No configuration needed.
Check that the repository is activated in Integrations. Verify Tembo can create branches. Check there isn't already an open PR for the same issue.
Add a PR template to your repo. Use a [rule file](/features/rule-files) with PR formatting preferences. Write clearer session descriptions.
# Rule Files
Source: https://docs.tembo.io/features/rule-files
Define project context and conventions for Tembo to follow.
Add a rule file to your repository root so Tembo understands your project's conventions, architecture, and coding standards. Tembo reads it before every session.
## Supported files
Tembo uses the first file it finds from this list:
* `tembo.md` (recommended)
* `AGENTS.md`
* `CLAUDE.md`
* `.cursorrules`
* `.windsurfrules`
* `.clinerules`
* `.rules`
* `AGENT.md`
* `.github/copilot-instructions.md`
## Example
```markdown theme={null}
# Project Context
React + TypeScript frontend with Node.js backend.
## Commands
- `npm install` - Install dependencies
- `npm run dev` - Start dev server
- `npm test` - Run tests
## Code Style
- TypeScript strict mode, explicit types
- Functional React components with hooks
- Conventional commits: `type(scope): message`
## Structure
- `/src/components` - UI components
- `/src/services` - API and business logic
- `/tests` - Test files
```
## What to include
* **Build/dev commands** - How to build, test, and run the project
* **Code style** - Naming conventions, formatting, standards
* **Testing** - Frameworks, expectations, coverage targets
* **Architecture** - Project structure, design patterns, where code belongs
* **Pitfalls** - Known issues or gotchas to avoid
# Custom Dependencies
Source: https://docs.tembo.io/features/sandbox/custom-dependencies
Add project-specific tools to Tembo sandboxes with tembo.nix.
Add a `tembo.nix` file to your repository root when your project needs tools that are not pre-installed in the sandbox. Tembo automatically detects the file and runs commands inside your Nix dev shell.
## Prerequisites
* You have a repository connected to Tembo.
* You know which system packages or language toolchains your project needs.
## Create tembo.nix
Create `tembo.nix` in your repository root with a default dev shell. Tembo uses `devShells.x86_64-linux.default` in the sandbox.
```nix theme={null}
{
description = "Tembo Cloud VM Dependencies";
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
flake-utils.url = "github:numtide/flake-utils";
};
outputs = { self, nixpkgs, flake-utils }:
flake-utils.lib.eachDefaultSystem (system:
let
pkgs = nixpkgs.legacyPackages.${system};
in {
devShells.default = pkgs.mkShell {
packages = with pkgs; [
go
rustc
cargo
jdk
];
};
}
);
}
```
After you commit the file, new Tembo sessions use the dev shell automatically. Agents can then run commands that depend on those packages, such as `go test`, `cargo test`, or Java build tools.
## Add packages
Add packages to the `packages` list. For example, this dev shell adds PostgreSQL client tools and `pkg-config` for projects that compile native dependencies:
```nix theme={null}
{
description = "Tembo Cloud VM Dependencies";
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
flake-utils.url = "github:numtide/flake-utils";
};
outputs = { self, nixpkgs, flake-utils }:
flake-utils.lib.eachDefaultSystem (system:
let
pkgs = nixpkgs.legacyPackages.${system};
in {
devShells.default = pkgs.mkShell {
packages = with pkgs; [
postgresql
pkg-config
openssl
];
};
}
);
}
```
## Configure the shell
Use `shellHook` when the sandbox needs environment variables for local commands:
```nix theme={null}
{
description = "Tembo Cloud VM Dependencies";
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
flake-utils.url = "github:numtide/flake-utils";
};
outputs = { self, nixpkgs, flake-utils }:
flake-utils.lib.eachDefaultSystem (system:
let
pkgs = nixpkgs.legacyPackages.${system};
in {
devShells.default = pkgs.mkShell {
packages = with pkgs; [
nodejs_22
pnpm
];
shellHook = ''
export NODE_ENV=development
'';
};
}
);
}
```
Keep secrets out of `tembo.nix`. Add secrets through your sandbox [environment variables](/features/sandbox/environment-variables) instead.
## Tips
* 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.
# Environment Variables
Source: https://docs.tembo.io/features/sandbox/environment-variables
Store secrets and configuration that Tembo injects into every sandbox session.
Environment variables let you store secrets and configuration once and have Tembo inject them into every session's [sandbox](/features/sandbox/overview). They're the recommended way to pass API keys, tokens, and other configuration to agent commands, [hooks](/features/hooks), MCP servers, and connected integrations, without committing secrets to your repository.
Environment variables are workspace-wide. Every session your workspace runs, including agent runs and interactive terminal sessions, receives them in its sandbox environment.
## Prerequisites
* You have access to your Tembo workspace settings.
* You know the keys and values your project needs at runtime.
## Add a variable
1. Open **Settings**.
2. Go to **Sandbox**.
3. Under **Environment Variables**, click **Create Secret**.
4. Add variables one of two ways:
* **Single Variable**: enter a **Key** (for example `CLIENT_KEY`) and its **Value**.
* **Bulk Import**: paste `.env`-style contents, one `KEY=value` per line.
5. Click **Create Secret**.
For bulk import, each line must use the `KEY=value` format. Blank lines and lines without a value are skipped:
```bash theme={null}
DEPLOY_TOKEN=abc123
DATABASE_URL=postgres://user:pass@host:5432/db
SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0
```
## How variables are used
Once saved, a variable is available in the sandbox for the whole session. You can use it from:
* **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.
* **[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:
```json theme={null}
{
"mcpServers": {
"github": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "$GITHUB_TOKEN"
}
}
}
}
```
## Security
* **Encrypted at rest.** Values are encrypted before they're stored.
* **Write-only in the dashboard.** After you save a variable, the value is hidden. The list shows only the key and when it was created, and there is no way to reveal a stored value.
* **Scoped to your workspace.** Variables are only injected into sessions that belong to the workspace where you created them.
## Constraints
* Keys are unique within a workspace.
* To rotate or change a value, delete the variable and create it again. Values can't be edited in place because they're hidden after saving.
* Tembo injects its own reserved variables into every session, including `TEMBO_`-prefixed variables and, for [triggered agents](/features/agents#triggers), `TRIGGER_PAYLOAD`. Avoid using these names for your own variables, as Tembo's values take precedence.
* Keep secrets out of [`tembo.nix`](/features/sandbox/custom-dependencies) and out of your repository. Store them here instead.
## Remove a variable
1. Open **Settings** > **Sandbox**.
2. Find the variable in the **Environment Variables** table.
3. Open the row menu and select **Delete**.
Deletion is immediate and can't be undone. New sessions will no longer receive the variable.
# Overview
Source: https://docs.tembo.io/features/sandbox/overview
Secure, isolated environments where coding agents execute sessions.
Every session runs in its own isolated sandbox. Sandboxes are ephemeral: spun up for the session, destroyed when it's done. No code or state persists after execution.
## Data handling
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.
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.
## Sandbox sizes
Tembo offers five sandbox sizes. Each session runs in a dedicated Linux VM, and no two sessions share the same VM.
| Size | vCPU | Memory | Disk |
| ------ | ---- | ------ | ------ |
| Nano | 2 | 2 GB | 50 GB |
| Micro | 2 | 4 GB | 50 GB |
| Medium | 4 | 8 GB | 50 GB |
| Large | 8 | 16 GB | 100 GB |
| XL | 16 | 32 GB | 200 GB |
Micro and Medium are best for routine code analysis, fixes, features, and reviews. Large and XL are best for heavier builds, integration tests, Docker workloads, large repositories, or multi-container setups.
Need more than 32 GB of RAM? Contact [support@tembo.io](mailto:support@tembo.io) to request access.
VM sandboxes include full nested virtualization for Docker-in-Docker and provide a stronger isolation boundary.
If your org requires that untrusted code only runs with a VM boundary, we can enforce a VM-only posture. Contact [support@tembo.io](mailto:support@tembo.io).
## Pre-installed tools
All sandbox sizes come with:
| Category | Tools |
| -------------- | ------------------------------ |
| **JavaScript** | Node.js 22, Bun, pnpm, Yarn |
| **Python** | Python 3.12, pipx, uv, ruff |
| **Ruby** | Ruby 3.3, Bundler, RuboCop |
| **.NET** | .NET SDK 10 |
| **Rust** | rustc, Cargo, Clippy, rustfmt |
| **Java** | JDK 21, Gradle, Maven |
| **Cloud** | Google Cloud SDK |
| **Containers** | Docker 28, Docker Compose 2.31 |
| **Other** | Git, curl, ShellCheck, httpie |
Go and Elixir are available through Nix dev shells. Add a `tembo.nix` to install language-specific tooling for your project.
## Add custom dependencies
Add a [`tembo.nix`](/features/sandbox/custom-dependencies) file to your repository when your project needs tools that are not pre-installed in the sandbox.
# AWS
Source: https://docs.tembo.io/features/self-hosted/deploy/aws
Deploy Tembo self-hosted on Amazon Web Services.
## Overview
The Tembo self-hosted stack runs as a single NixOS machine. All services sit behind nginx on port 80:
| Service | Path | Port (internal) |
| ------------------------ | ------------- | --------------- |
| Web UI | `/` | 3000 |
| API | `/api/*` | 3001 |
| Admin UI | `/admin/` | 3002 |
| Installer / setup wizard | `/installer/` | 3999 |
| PostgreSQL 16 | — | 5432 |
| PGAdmin Console | — | 5050 |
| Redis | — | 6379 |
| Prometheus | — | 9090 |
Tembo distributes a pre-built NixOS AMI (Amazon Machine Image) to your AWS account. You launch an EC2 instance from that AMI, open the required ports, and configure a single JSON file. No OS setup or image building is required on your end.
***
## Step 1: Request Access
To get started with Tembo self-hosted, you will need a license key and access to the Tembo AMI. Book a demo with the Tembo team to get set up:
Once you have a license key, contact Tembo to have the AMI shared with your AWS account. You will need to provide:
* Your **license key**
* Your **AWS Account ID** (12-digit number, found in the AWS Console under your account menu or via `aws sts get-caller-identity --query Account --output text`)
* Your preferred **AWS region** (e.g. `us-east-1`)
Tembo will share the AMI with your account. You will receive an AMI ID (e.g. `ami-0abc1234def56789`) once sharing is confirmed.
The AMI contains no embedded secrets. Initial configuration is written to `/var/lib/tembo/config.json` at first boot by the `tembo-config-seed` service.
***
## Step 2: Launch an EC2 Instance
### Instance requirements
| Resource | Minimum | Recommended |
| -------- | ------- | ----------- |
| vCPUs | 4 | 8 |
| RAM | 16 GB | 32 GB |
| Disk | 128 GB | 256 GB |
We recommend **`c5.metal`** or another bare-metal instance for the best experience. Bare-metal instances expose `/dev/kvm` natively so sandbox VMs run with full hardware acceleration.
8th-gen Intel Nitro instances (e.g. `m8i.*`) also work but require **nested virtualization** to be enabled at launch (see step 7 below). All other instance types fall back to software emulation, which is significantly slower.
### Via the AWS Console
1. Go to **EC2 > Instances > Launch instances**
2. Under **Application and OS Images**, choose **My AMIs** and select the AMI shared by Tembo
3. Choose an instance type (`c5.metal` recommended, or `m8i.4xlarge` or equivalent)
4. Under **Key pair**, select an existing key pair or create a new one — you will need this to SSH in
5. Under **Network settings**, create or select a security group (you will configure inbound rules in the next step)
6. Under **Configure storage**, set the root volume to at least **256 GiB**
7. If using a **non-bare-metal** instance (e.g. `m8i.*`): expand **Advanced details** and set **Nested virtualization** to **Enable**. Skip this step for bare-metal instances (`c5.metal`, `r7i.metal-*`) — nested virtualization is not available on bare metal and is not needed
8. Launch the instance
### Via the AWS CLI
```bash theme={null}
aws ec2 run-instances \
--image-id \
--instance-type c5.metal \
--key-name \
--block-device-mappings '[{"DeviceName":"/dev/xvda","Ebs":{"VolumeSize":128,"VolumeType":"gp3"}}]' \
--tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=tembo-self-hosted}]' \
--cpu-options "CoreCount=,ThreadsPerCore=1" \
--metadata-options "HttpEndpoint=enabled,HttpTokens=required"
```
Replace `CoreCount` with the number of physical cores for your instance type. For `c5.metal` this is `48`.
Nested virtualization is only required for non-bare-metal instances (e.g. `m8i.*`). Bare-metal instances (`c5.metal`, `r7i.metal-*`) expose KVM natively — do not enable nested virtualization on them.
***
## Step 3: Configure the Security Group
By default, EC2 instances block all inbound traffic. Add inbound rules to allow access to Tembo:
| Type | Protocol | Port | Source | Purpose |
| ---------- | -------- | ---- | --------------- | ------------------------------- |
| Custom TCP | TCP | 80 | (Your IP range) | Tembo web UI and API |
| Custom TCP | TCP | 3999 | Your IP | Installer / setup wizard |
| Custom TCP | TCP | 8888 | Your IP | VS Code server (config editing) |
| SSH | TCP | 22 | Your IP | SSH access |
### Via the AWS Console
1. Go to **EC2 > Security Groups**
2. Select the security group attached to your instance
3. Click **Inbound rules > Edit inbound rules**
4. Add the rules above, then save
### Via the AWS CLI
```bash theme={null}
# Allow HTTP on port 80
aws ec2 authorize-security-group-ingress \
--group-id \
--protocol tcp \
--port 80 \
--cidr 0.0.0.0/0
# Allow installer, VS Code server, and SSH — restrict to your IP
aws ec2 authorize-security-group-ingress \
--group-id \
--protocol tcp \
--port 3999 \
--cidr /32
aws ec2 authorize-security-group-ingress \
--group-id \
--protocol tcp \
--port 8888 \
--cidr /32
aws ec2 authorize-security-group-ingress \
--group-id \
--protocol tcp \
--port 22 \
--cidr /32
```
Tembo services route through nginx on port 80. Do **not** open ports 3000, 3001, or 3002 publicly — those are internal-only ports. Accessing the app directly on port 3000 bypasses nginx and will break authentication.
***
## Step 4: Run the Installer and Configure the Instance
### 4a: Run the install workflow
Once the instance is running, open the installer in your browser:
```
http://:3999
```
Follow the on-screen steps to complete the install workflow. This provisions the Tembo services and prepares the instance for use. This install can take up to an hour to fully complete. Subsequent updates will be faster.
### 4b: Configure `/var/lib/tembo/config.json`
After the installer finishes, open the VS Code server to edit the configuration file:
```
http://:8888
```
The VS Code server opens directly to `/var/lib/tembo/config.json`. You can also see it in the VS Code file explorer on the right as `config.json` A few values must be set correctly for the install to work.
Ensure these keys are present and correct:
```json theme={null}
{
"betterAuth.secret": "",
"api.base": "http:///api/",
"frontend.url": "http://"
}
```
| Key | Notes |
| ------------------- | ------------------------------------------------------------------------------------------------------------- |
| `betterAuth.secret` | Auto-generated on first boot if missing. Leave it if it is already set. |
| `api.base` | Must match the URL of the API. **Must end with a trailing `/`**. |
| `frontend.url` | Defaults to `http://localhost:3000`, which breaks auth on a remote VM. Set this to the actual IP or hostname. |
After saving, restart the API. There is a background service that should restart the API for you on finishing edits, but you can also do this from a terminal in the VS Code server, or via SSH:
```bash theme={null}
sudo systemctl restart tembo-ts-api
```
The config seed runs before `tembo-ts-api`, `tembo-ts-cron`, and agent workers on every boot. Manual edits are preserved — the seed only writes values that are missing or empty.
If you have a domain name, set both `api.base` and `frontend.url` to the domain (e.g. `https://tembo.example.com/api/` and `https://tembo.example.com`) rather than the raw IP. This makes it easier to rotate instances or add a load balancer later.
***
## Step 5: Verify the Install
Open a browser and navigate to:
```
http://
```
You should see the Tembo sign-up or sign-in screen.
Check service status on the instance:
```bash theme={null}
systemctl status tembo-ts-api
systemctl status tembo-ts-agent-X
systemctl status tembo-web
systemctl status nginx
```
For the `tembo-ts-agent-X`, depending on how many agents you chose to provision in the install step, X will be that number. (Eg. 3 agents make tembo-ts-agent-1, tembo-ts-agent-2, tembo-ts-agent3)
***
## Troubleshooting
### Auth 404 on sign-up
**Symptom:** `POST http://:3000/api/auth/sign-up/email` returns 404.
**Cause:** You are hitting the Next.js frontend directly on port 3000, bypassing nginx. The `/api/auth/*` handler does not exist at that port.
**Fix:** Access the app through nginx on port 80:
```
http:// # correct
http://:3000 # wrong — internal port only
```
If port 80 is blocked, check your EC2 security group inbound rules.
### 401 after sign-up
**Symptom:** Sign-up succeeds but all subsequent API requests return 401.
**Cause:** Billing is enabled by default. Without Stripe configured, organization creation fails silently, leaving the user with no active org.
**Fix:** Confirm `BILLING_ENABLED = "false"` is set in the API environment in your NixOS configuration. Contact Tembo support if this was not set in the distributed image.
### Sign-in loops / cookie issues
**Symptom:** Sign-in redirects back to the login page, or cookies are not set.
**Cause:** `api.base` or `frontend.url` in `config.json` does not match the URL you are accessing the app from. Better Auth uses these for trusted origins and cookie domain validation.
**Fix:** Edit `/var/lib/tembo/config.json` and set both keys to the exact origin you are using in the browser. Restart the API:
```bash theme={null}
sudo nano /var/lib/tembo/config.json
sudo systemctl restart tembo-ts-api
```
### Services not starting
```bash theme={null}
# Check all Tembo services at once
systemctl list-units 'tembo-*'
# View logs for a specific service
journalctl -u tembo-ts-api -n 100
journalctl -u tembo-web -n 100
```
The `tembo-config-seed` service must complete before the API and agents start. If the API fails immediately at boot, check:
```bash theme={null}
journalctl -u tembo-config-seed
cat /var/lib/tembo/config.json
```
### Instance not reachable after launch
* Confirm the instance is in a **Running** state in the EC2 console
* Verify the security group has an inbound rule for port 80 (and port 22 for SSH)
* If using an Elastic IP, ensure it is associated with the instance
***
## Need Help?
If you run into any issues, contact [support@tembo.io](mailto:support@tembo.io).
# Azure
Source: https://docs.tembo.io/features/self-hosted/deploy/azure
Deploy Tembo self-hosted on Microsoft Azure.
## Overview
The Tembo self-hosted stack runs as a single NixOS machine. All services sit behind nginx on port 80:
| Service | Path | Port (internal) |
| ------------------------ | ------------- | --------------- |
| Web UI | `/` | 3000 |
| API | `/api/*` | 3001 |
| Admin UI | `/admin/` | 3002 |
| Installer / setup wizard | `/installer/` | 3999 |
| PostgreSQL 16 | — | 5432 |
| PGAdmin Console | — | 5050 |
| Redis | — | 6379 |
| Prometheus | — | 9090 |
Tembo distributes a pre-built NixOS image via an Azure Compute Gallery shared to your subscription. You create a VM from that image, open the required ports, and configure a single JSON file. No OS setup or image building is required on your end.
***
## Step 1: Request Access
To get started with Tembo self-hosted, you will need a license key and access to the Tembo Azure Compute Gallery image. Book a demo with the Tembo team to get set up:
Once you have a license key, contact Tembo to have the image shared with your Azure subscription. You will need to provide:
* Your **license key**
* Your **Azure Subscription ID**
* Your preferred **Azure region** (e.g. `eastus`)
Tembo will share the Compute Gallery image with your subscription. You will receive the gallery details (subscription ID, resource group, and gallery name) once sharing is confirmed.
The image contains no embedded secrets. Initial configuration is written to `/var/lib/tembo/config.json` at first boot by the `tembo-config-seed` service.
***
## Step 2: Create a Resource Group
```bash theme={null}
az group create \
--name tembo-self-hosted-rg \
--location eastus
```
***
## Step 3: Create the VM from the Gallery Image
### VM requirements
| Resource | Minimum | Recommended |
| -------- | ------- | ----------- |
| vCPUs | 4 | 8 |
| RAM | 16 GB | 32 GB |
| Disk | 128 GB | 256 GB |
For the best sandbox performance, use a VM size that supports **nested virtualization** (e.g. `Standard_D8s_v3`, `Standard_D16s_v3`, or any v3/v4/v5 D-series or E-series). This allows sandbox VMs to run with hardware acceleration via KVM.
### Via the Azure CLI
```bash theme={null}
az vm create \
--resource-group tembo-self-hosted-rg \
--name tembo-self-hosted \
--image "/subscriptions//resourceGroups//providers/Microsoft.Compute/galleries//images/tembo-self-hosted/versions/latest" \
--size Standard_D8s_v3 \
--os-disk-size-gb 128 \
--admin-username eng \
--generate-ssh-keys \
--public-ip-sku Standard
```
Replace the placeholders with values provided by Tembo:
| Placeholder | Description |
| ------------------------- | -------------------------------------- |
| `` | Tembo's Azure subscription ID |
| `` | Resource group where the gallery lives |
| `` | Name of the Azure Compute Gallery |
Note the `IpAddress` in the output — you will need it in later steps.
### Via the Azure Portal
1. Go to **Virtual machines > Create**
2. Select your resource group and region
3. Under **Image**, click **See all images**, then **Shared images** and select the Tembo image
4. Choose a VM size (`Standard_D8s_v3` or larger recommended)
5. Under **Disks**, set the OS disk size to at least **256 GiB**
6. Under **Networking**, select or create a virtual network
7. Create the VM
***
## Step 4: Configure the Network Security Group
By default, Azure VMs block all inbound traffic except SSH. Add inbound rules to allow access to Tembo:
| Priority | Port | Protocol | Source | Action | Purpose |
| -------- | ---- | -------- | ------------------------- | ------ | ------------------------------- |
| 100 | 80 | TCP | (your preferred IP range) | Allow | Tembo web UI and API |
| 110 | 3999 | TCP | Your IP | Allow | Installer / setup wizard |
| 120 | 8888 | TCP | Your IP | Allow | VS Code server (config editing) |
| 130 | 22 | TCP | Your IP | Allow | SSH access |
Ports 3999 and 8888 are only needed during initial setup. You can remove those rules after configuration is complete.
### Via the Azure CLI
```bash theme={null}
# Allow HTTP on port 80
az network nsg rule create \
--resource-group tembo-self-hosted-rg \
--nsg-name tembo-self-hostedNSG \
--name AllowHTTP \
--priority 100 \
--protocol Tcp \
--destination-port-ranges 80 \
--access Allow
# Allow installer — restrict to your IP
az network nsg rule create \
--resource-group tembo-self-hosted-rg \
--nsg-name tembo-self-hostedNSG \
--name AllowInstaller \
--priority 110 \
--protocol Tcp \
--destination-port-ranges 3999 \
--source-address-prefixes /32 \
--access Allow
# Allow VS Code server — restrict to your IP
az network nsg rule create \
--resource-group tembo-self-hosted-rg \
--nsg-name tembo-self-hostedNSG \
--name AllowVSCode \
--priority 120 \
--protocol Tcp \
--destination-port-ranges 8888 \
--source-address-prefixes /32 \
--access Allow
# Allow SSH — restrict to your IP
az network nsg rule create \
--resource-group tembo-self-hosted-rg \
--nsg-name tembo-self-hostedNSG \
--name AllowSSH \
--priority 130 \
--protocol Tcp \
--destination-port-ranges 22 \
--source-address-prefixes /32 \
--access Allow
```
Or in the portal: **VM > Networking > Add inbound port rule**.
Tembo services route through nginx on port 80. Do **not** open ports 3000, 3001, or 3002 publicly — those are internal-only ports. Accessing the app directly on port 3000 bypasses nginx and will break authentication.
***
## Step 5: Run the Installer and Configure the Instance
### 5a: Run the install workflow
Once the VM is running, open the installer in your browser:
```
http://:3999
```
Follow the on-screen steps to complete the install workflow. This provisions the Tembo services and prepares the instance for use. This install can take up to an hour to fully complete. Subsequent updates will be faster.
### 5b: Configure `/var/lib/tembo/config.json`
After the installer finishes, open the VS Code server to edit the configuration file:
```
http://:8888
```
The VS Code server opens directly to `/var/lib/tembo/config.json`. You can also see it in the VS Code file explorer on the right as `config.json`. A few values must be set correctly for the install to work.
Ensure these keys are present and correct:
```json theme={null}
{
"betterAuth.secret": "",
"api.base": "http:///api/",
"frontend.url": "http://"
}
```
| Key | Notes |
| ------------------- | ------------------------------------------------------------------------------------------------------------- |
| `betterAuth.secret` | Auto-generated on first boot if missing. Leave it if it is already set. |
| `api.base` | Must match the public URL of the API. **Must end with a trailing `/`**. |
| `frontend.url` | Defaults to `http://localhost:3000`, which breaks auth on a remote VM. Set this to the actual IP or hostname. |
After saving, restart the API. There is a background service that should restart the API for you on finishing edits, but you can also do this from a terminal in the VS Code server, or via SSH:
```bash theme={null}
sudo systemctl restart tembo-ts-api
```
The config seed runs before `tembo-ts-api`, `tembo-ts-cron`, and agent workers on every boot. Manual edits are preserved — the seed only writes values that are missing or empty.
If you have a domain name, set both `api.base` and `frontend.url` to the domain (e.g. `https://tembo.example.com/api/` and `https://tembo.example.com`) rather than the raw IP. This makes it easier to rotate VMs or add a load balancer later.
***
## Step 6: Verify the Install
Open a browser and navigate to:
```
http://
```
You should see the Tembo sign-up or sign-in screen.
Check service status on the VM:
```bash theme={null}
systemctl status tembo-ts-api
systemctl status tembo-ts-agent-X
systemctl status tembo-web
systemctl status nginx
```
For the `tembo-ts-agent-X`, depending on how many agents you chose to provision in the install step, X will be that number. (Eg. 3 agents make tembo-ts-agent-1, tembo-ts-agent-2, tembo-ts-agent-3)
***
## Troubleshooting
### Auth 404 on sign-up
**Symptom:** `POST http://:3000/api/auth/sign-up/email` returns 404.
**Cause:** You are hitting the Next.js frontend directly on port 3000, bypassing nginx. The `/api/auth/*` handler does not exist at that port.
**Fix:** Access the app through nginx on port 80:
```
http:// # correct
http://:3000 # wrong — internal port only
```
If port 80 is blocked, check the Azure NSG inbound rules.
### 401 after sign-up
**Symptom:** Sign-up succeeds but all subsequent API requests return 401.
**Cause:** Billing is enabled by default. Without Stripe configured, organization creation fails silently, leaving the user with no active org.
**Fix:** Confirm `billing.enabled: false` is set in the API environment in your config.json. Contact Tembo support if this was not set in the distributed image.
### Sign-in loops / cookie issues
**Symptom:** Sign-in redirects back to the login page, or cookies are not set.
**Cause:** `api.base` or `frontend.url` in `config.json` does not match the URL you are accessing the app from. Better Auth uses these for trusted origins and cookie domain validation.
**Fix:** Edit `/var/lib/tembo/config.json` and set both keys to the exact origin you are using in the browser. Restart the API:
```bash theme={null}
sudo nano /var/lib/tembo/config.json
sudo systemctl restart tembo-ts-api
```
### Services not starting
```bash theme={null}
# Check all Tembo services at once
systemctl list-units 'tembo-*'
# View logs for a specific service
journalctl -u tembo-ts-api -n 100
journalctl -u tembo-web -n 100
```
The `tembo-config-seed` service must complete before the API and agents start. If the API fails immediately at boot, check:
```bash theme={null}
journalctl -u tembo-config-seed
cat /var/lib/tembo/config.json
```
### VM not reachable after launch
* Confirm the VM is in a **Running** state in the Azure portal
* Verify the NSG has an inbound rule for port 80 (and port 22 for SSH)
* If using a virtual network, confirm the subnet has a route to the internet
***
## Need Help?
If you run into any issues, contact [support@tembo.io](mailto:support@tembo.io).
# GCP
Source: https://docs.tembo.io/features/self-hosted/deploy/gcp
Deploy Tembo self-hosted on Google Cloud Platform.
GCP support is currently in early access. To get on the list, book a demo call with the Tembo team: Book a Demo
***
## Need Help?
If you run into any issues, contact [support@tembo.io](mailto:support@tembo.io).
# Kubernetes
Source: https://docs.tembo.io/features/self-hosted/deploy/kubernetes
Deploy Tembo self-hosted on Kubernetes.
Kubernetes support is currently in early access. To get on the list, book a demo call with the Tembo team: Book a Demo
***
## Need Help?
If you run into any issues, contact [support@tembo.io](mailto:support@tembo.io).
# AWS S3 Storage
Source: https://docs.tembo.io/features/self-hosted/integrations/aws-storage
Configure Amazon S3 for Tembo self-hosted on AWS.
Tembo can use an S3 bucket as a single store for image attachments, org profile pictures, VM snapshots, and user storage. If you skip this configuration, file upload features will be unavailable.
***
## Step 1: Create an S3 Bucket
### Via the AWS CLI
```bash theme={null}
aws s3api create-bucket \
--bucket \
--region us-east-1
```
For regions other than `us-east-1`, add the location constraint:
```bash theme={null}
aws s3api create-bucket \
--bucket \
--region us-west-2 \
--create-bucket-configuration LocationConstraint=us-west-2
```
### Via the AWS Console
1. Go to **S3** → **Create bucket**
2. Enter a **Bucket name** (globally unique)
3. Select your **AWS Region**
4. Leave all other settings as default and click **Create bucket**
***
## Step 2: Create IAM Credentials
Tembo needs an IAM user with read/write access to the bucket. If your EC2 instance already has an IAM instance profile with S3 access, you can skip this step — Tembo will use the instance's credentials automatically.
### Via the AWS CLI
```bash theme={null}
# Create the IAM user
aws iam create-user --user-name tembo-storage
# Create an inline policy granting access to the bucket
aws iam put-user-policy \
--user-name tembo-storage \
--policy-name tembo-s3-access \
--policy-document '{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:ListBucket"],
"Resource": [
"arn:aws:s3:::",
"arn:aws:s3:::/*"
]
}]
}'
# Create access keys
aws iam create-access-key --user-name tembo-storage
```
Note the `AccessKeyId` and `SecretAccessKey` from the output.
### Via the AWS Console
1. Go to **IAM** → **Users** → **Create user**
2. Enter a username (e.g. `tembo-storage`) and click **Next**
3. Select **Attach policies directly**, then click **Create policy**
4. In the policy editor, paste:
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:ListBucket"],
"Resource": [
"arn:aws:s3:::",
"arn:aws:s3:::/*"
]
}]
}
```
5. Name the policy (e.g. `tembo-s3-access`) and click **Create policy**
6. Back on the user creation page, attach the new policy and click **Next** → **Create user**
7. Open the user, go to the **Security credentials** tab, and click **Create access key**
8. Select **Application running outside AWS**, then click **Next** → **Create access key**
9. Copy the **Access key** and **Secret access key**
***
## Step 3: Configure CORS
Tembo uploads image attachments directly from the browser to S3. S3 blocks these cross-origin requests by default, so you must add a CORS rule.
### Via the AWS CLI
```bash theme={null}
aws s3api put-bucket-cors \
--bucket \
--cors-configuration '{
"CORSRules": [{
"AllowedOrigins": ["http://"],
"AllowedMethods": ["GET", "PUT", "DELETE", "HEAD"],
"AllowedHeaders": ["*"],
"ExposeHeaders": [],
"MaxAgeSeconds": 3600
}]
}'
```
If you are using a custom domain, replace `http://` with your domain.
### Via the AWS Console
1. Go to **S3** → select your bucket → **Permissions** tab
2. Scroll to **Cross-origin resource sharing (CORS)** and click **Edit**
3. Paste:
```json theme={null}
[
{
"AllowedOrigins": ["http://"],
"AllowedMethods": ["GET", "PUT", "DELETE", "HEAD"],
"AllowedHeaders": ["*"],
"ExposeHeaders": [],
"MaxAgeSeconds": 3600
}
]
```
4. Click **Save changes**
***
## Step 4: Add to config.json
Open `/var/lib/tembo/config.json` (via the VS Code server at `http://:8888` or SSH) and add:
```json theme={null}
{
"selfHosted.objectStorage.provider": "aws",
"selfHosted.objectStorage.bucket": "",
"aws.region": "us-east-1",
"selfHosted.objectStorage.aws.accessKeyId": "",
"selfHosted.objectStorage.aws.secretAccessKey": ""
}
```
If your EC2 instance has an IAM instance profile with S3 access, omit `accessKeyId` and `secretAccessKey` — Tembo will use the instance's credentials automatically.
Then restart the API:
```bash theme={null}
sudo systemctl restart tembo-ts-api
```
# Azure Storage
Source: https://docs.tembo.io/features/self-hosted/integrations/azure-storage
Configure Azure Blob Storage for Tembo self-hosted on Azure.
Tembo can use an Azure Blob Storage container as a single bucket for image attachments, org profile pictures, VM snapshots, and user storage. If you skip this configuration, file upload features will be unavailable.
***
## Step 1: Create a Storage Account
### Via the Azure CLI
```bash theme={null}
az storage account create \
--name \
--resource-group tembo-self-hosted-rg \
--location eastus \
--sku Standard_LRS
```
### Via the Azure Portal
1. Go to **Storage accounts** → **+ Create**
2. Select your subscription and resource group
3. Enter a **Storage account name** (globally unique, 3–24 characters, lowercase alphanumeric only)
4. Choose your **Region**
5. Leave **Redundancy** as **Locally-redundant storage (LRS)**
6. Click **Review + create**, then **Create**
***
## Step 2: Create the Container
### Via the Azure CLI
```bash theme={null}
az storage container create \
--name \
--account-name
```
### Via the Azure Portal
1. Go to **Storage accounts** → select your account
2. In the left sidebar, under **Data storage**, click **Containers**
3. Click **+ Container**
4. Enter a name and click **Create**
***
## Step 3: Get the Account Key
### Via the Azure CLI
```bash theme={null}
az storage account keys list \
--account-name \
--resource-group tembo-self-hosted-rg \
--query "[0].value" -o tsv
```
### Via the Azure Portal
1. Go to **Storage accounts** → select your account
2. In the left sidebar, under **Security + networking**, click **Access keys**
3. Click **Show** next to **key1** and copy the **Key** value
***
## Step 4: Configure CORS
Tembo uploads image attachments directly from the browser to the storage container. Azure blocks these cross-origin requests by default, so you must add a CORS rule.
### Via the Azure CLI
```bash theme={null}
az storage cors add \
--account-name \
--services b \
--methods DELETE GET HEAD OPTIONS PUT \
--origins 'http://' \
--allowed-headers '*' \
--exposed-headers '*' \
--max-age 3600
```
If you are using a custom domain, replace `http://` with your domain.
### Via the Azure Portal
1. Go to **Storage accounts** → select your account
2. In the left sidebar, under **Settings**, click **Resource sharing (CORS)**
3. Select the **Blob service** tab
4. Click **+ Add** and fill in:
* **Allowed origins**: `http://` (or your domain)
* **Allowed methods**: `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PUT`
* **Allowed headers**: `*`
* **Exposed headers**: `*`
* **Max age**: `3600`
5. Click **Save**
***
## Step 5: Add to config.json
Open `/var/lib/tembo/config.json` (via the VS Code server at `http://:8888` or SSH) and add:
```json theme={null}
{
"selfHosted.objectStorage.provider": "azure",
"selfHosted.objectStorage.bucket": "",
"selfHosted.objectStorage.azure.storageAccountName": "",
"selfHosted.objectStorage.azure.storageAccountKey": ""
}
```
Then restart the API:
```bash theme={null}
sudo systemctl restart tembo-ts-api
```
# GitHub
Source: https://docs.tembo.io/features/self-hosted/integrations/github
Set up the GitHub App integration for Tembo self-hosted.
## Overview
The GitHub integration allows Tembo to clone repositories, create branches, push commits, open pull requests, and respond to issues and webhooks. On the SaaS platform this is pre-configured — on self-hosted you need to create your own GitHub App and point it at your instance.
***
## Step 1: Create a GitHub App
1. Go to **GitHub > Settings > Developer settings > GitHub Apps > New GitHub App**
### GitHub App name
Choose a name for your app, e.g. `Tembo (self-hosted)`. This will be visible to users when they install the app.
### Homepage URL
```
http://
```
### Callback URL
```
http:///api/oauth/github/callback
```
This is where GitHub redirects users after they authorize the app.
### Check **Request user authorization (OAuth) during installation**
This is important — it ensures that when a user installs the app, they are also prompted to authorize Tembo to act on their behalf. Without this, Tembo cannot perform actions as the installing user.
### Webhook URL
```
http:///api/webhook/github
```
### Webhook secret
Generate a random string and enter it here. Save this value — you will need it for the Tembo config later.
### Permissions
Under **Repository permissions**, set:
| Permission | Access |
| ------------------- | ------------ |
| **Actions** | Read-only |
| **Checks** | Read & write |
| **Commit statuses** | Read-only |
| **Contents** | Read & write |
| **Issues** | Read & write |
| **Metadata** | Read-only |
| **Pull requests** | Read & write |
| **Webhooks** | Read & write |
Under **Account permissions**, no changes are needed.
### Subscribe to events
Check the following:
* Check run
* Create
* Delete
* Issue comment
* Issues
* Pull request
* Pull request review
* Pull request review comment
* Pull request review thread
* Push
* Repository
* Status
* Workflow run
### Where can this GitHub App be installed?
Select **Only on this account** if you only need it for a single org. Select **Any account** if you want to install it across multiple orgs.
### Create the app
Click **Create GitHub App**.
***
## Step 2: Generate a Client Secret
After the app is created, you will be on the app settings page.
1. Under **Client secrets**, click **Generate a new client secret**
2. Copy the secret immediately — it will only be shown once
***
## Step 3: Generate a Private Key
Still on the app settings page:
1. Scroll down to **Private keys**
2. Click **Generate a private key**
3. A `.pem` file will be downloaded — you will need its full contents for the config
***
## Step 4: Install the App
1. In the left sidebar, click **Install App**
2. Select the organization or account to install it on
3. Choose **All repositories** or select specific repositories
4. Click **Install** — because you checked **Request user authorization (OAuth) during installation**, you will be redirected to authorize the app as well
***
## Step 5: Configure Tembo
Open `/var/lib/tembo/config.json` (via the VS Code server at `http://:8888` or via SSH) and add the following keys:
```json theme={null}
{
"github.appId": "",
"github.appName": "",
"github.clientId": "",
"github.clientSecret": "",
"github.privateKey": "",
"github.webhookSecret": "",
"github.clientUserName": "",
"github.clientUserEmail": ""
}
```
| Key | Where to find it |
| ----------------- | ---------------------------------------------------------------------------- |
| `appId` | App settings page, listed as **App ID** |
| `appName` | The slug of your app name (e.g. `tembo-self-hosted`) |
| `clientId` | App settings page, listed as **Client ID** |
| `clientSecret` | The client secret you generated in Step 2 |
| `privateKey` | Contents of the `.pem` file from Step 3 (include the full key with newlines) |
| `webhookSecret` | The random string you set as the webhook secret in Step 1 |
| `clientUserName` | The GitHub username the bot will commit as |
| `clientUserEmail` | The email the bot will commit as |
After saving, restart the API:
```bash theme={null}
sudo systemctl restart tembo-ts-api
```
Updating the config.json will also cause the instance api to restart automatically.
***
## Step 6: Verify
1. Go to your Tembo instance and navigate to **Settings > Integrations**
2. Confirm GitHub shows as connected
3. Try creating a session against one of the repositories you installed the app on
***
## Need Help?
If you run into any issues, contact [support@tembo.io](mailto:support@tembo.io).
# Slack
Source: https://docs.tembo.io/features/self-hosted/integrations/slack
Set up the Slack integration for Tembo self-hosted.
## Overview
The Slack integration allows Tembo to send notifications, receive commands, and stream session updates to your Slack workspace. On the SaaS platform this is pre-configured — on self-hosted you need to create your own Slack app and point it at your instance.
***
## Step 1: Create a Slack App
1. Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App**
2. Choose **From scratch**
3. Fill in:
| Field | Value |
| ------------- | -------------------------- |
| **App Name** | e.g. `Tembo (self-hosted)` |
| **Workspace** | Select your workspace |
4. Click **Create App**
***
## Step 2: Configure OAuth & Permissions
1. In the left sidebar, go to **OAuth & Permissions**
2. Under **Redirect URLs**, add:
```
http:///api/oauth/slack/callback
```
3. Under **Bot Token Scopes**, add the following scopes:
* `app_mentions:read`
* `channels:history`
* `channels:join`
* `channels:read`
* `chat:write`
* `emoji:read`
* `files:read`
* `files:write`
* `groups:history`
* `groups:read`
* `im:history`
* `im:read`
* `im:write`
* `mpim:history`
* `mpim:read`
* `reactions:read`
* `reactions:write`
* `team:read`
* `users:read`
* `users:read.email`
4. Under **User Token Scopes**, add the following scopes:
* `channels:history`
* `im:history`
* `search:read.public`
* `search:read.im`
* `search:read.files`
* `search:read.users`
* `users:read`
* `users:read.email`
***
## Step 3: Enable Event Subscriptions
1. In the left sidebar, go to **Event Subscriptions**
2. Toggle **Enable Events** to on
3. Set the **Request URL** to:
```
http:///api/webhook/slack
```
Slack will send a verification challenge to this URL — it should respond with a `200` once your instance is running.
4. Under **Subscribe to bot events**, add:
* `app_mention`
* `message.channels`
* `message.groups`
* `message.im`
* `message.mpim`
* `reaction_added`
* `team_join`
5. Click **Save Changes**
***
## Step 4: Enable Interactivity
1. In the left sidebar, go to **Interactivity & Shortcuts**
2. Toggle **Interactivity** to on
3. Set the **Request URL** to:
```
http:///api/integration/slack/interaction
```
4. Click **Save Changes**
This enables buttons, overflow menus, and modal forms (e.g. the feedback modal) to work in Slack messages from Tembo.
***
## Step 5: Install the App to Your Workspace
1. In the left sidebar, go to **Install App**
2. Click **Install to Workspace** and authorize
***
## Step 6: Configure Tembo
From the Slack app settings page under **Basic Information**, gather the following values:
* **App ID**
* **Client ID**
* **Client Secret**
* **Signing Secret**
Open `/var/lib/tembo/config.json` (via the VS Code server at `http://:8888` or via SSH) and add the following keys:
```json theme={null}
{
"slack.appId": "",
"slack.clientId": "",
"slack.clientSecret": "",
"slack.signingSecret": ""
}
```
| Key | Where to find it |
| --------------------- | ---------------------------------------------------- |
| `slack.appId` | Basic Information page, listed as **App ID** |
| `slack.clientId` | Basic Information page, listed as **Client ID** |
| `slack.clientSecret` | Basic Information page, listed as **Client Secret** |
| `slack.signingSecret` | Basic Information page, listed as **Signing Secret** |
After saving, restart the API:
```bash theme={null}
sudo systemctl restart tembo-ts-api
```
Updating the config.json will also cause the instance API to restart automatically.
***
## Step 7: Verify
1. Go to your Tembo instance and navigate to **Settings > Integrations**
2. Click **Connect** on the Slack integration
3. Authorize the app in your workspace
4. Try mentioning the bot in a channel or sending it a direct message
***
## Need Help?
If you run into any issues, contact [support@tembo.io](mailto:support@tembo.io).
# Overview
Source: https://docs.tembo.io/features/self-hosted/overview
Run Tembo inside infrastructure you control, with packaged releases and enterprise support from Tembo.
Tembo self-hosted runs the entire Tembo platform on a **single instance** inside infrastructure you control. No cluster, no orchestrator — one machine, fully configured and ready to go.
Kubernetes and GCP support are currently in early access. To get on the list, book a demo call with the Tembo team: Book a Demo
Tembo provides the packaged release, upgrade path, and support. You decide how it is deployed, networked, and operated.
## How it works
The self-hosted stack is a NixOS-based machine image with all services pre-configured. You launch an instance from a Tembo-provided image (AMI, VHD, etc.), run a web-based installer, and configure a single JSON file. No OS setup or image building is required on your end.
NixOS gives you atomic updates with automatic rollback — upgrades either succeed completely or roll back to the previous working state.
A standard deployment runs these core services, all behind nginx on port 80:
| Service | Description |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Web app** | Next.js frontend for the user interface |
| **API** | REST API for product workflows, auth, and orchestration |
| **Agent workers** | Configurable workers (default 8) that handle sessions, code execution, and database operations in isolated sandboxes |
| **Cron** | Scheduled jobs, kicked off from Tembo's `Agents` feature or via tool calls from coding agents |
| **Admin UI** | Administrative dashboard for system management |
| **PostgreSQL 16** | Application database (and the job queue) — runs locally or can point to an external instance using your own connection string |
| **Redis** | Caching |
| **Prometheus** | Metrics collection and monitoring (optional) |
## Web-based installer
Every deployment ships with a built-in installer at `/installer/`. On first boot, it walks you through setup — configuring services, setting your license key, and tuning options like the number of agent workers. No Nix knowledge is required.
For releases and updates, Tembo can manage them for you, or your team can manually opt in to changes through the installer UI.
### How updates are delivered
Updates are **pull-based**. Your instance checks for new releases by calling Tembo's release endpoint over outbound HTTPS, authenticated with your license key, then downloads the packaged release. Tembo never connects inbound to your environment to push updates. Because the stack is NixOS-based, updates apply atomically and roll back automatically if they fail.
You choose how updates are applied:
* **Self-service:** your team opts in to a new release through the installer UI, on your own schedule.
* **Managed (optional):** if you would rather Tembo run updates for you, we can do so as an optional service using access you explicitly grant. Contact your Tembo account team to set this up.
## What you manage
You manage the infrastructure, networking, secrets, backups, and day-to-day operations of the environment.
Tembo provides the application release, deployment guidance, and support for upgrades.
You can also work with the Tembo team more directly through support packages, including optional FDE support for features specific to your team. If you want help operating the VM layer, the Tembo team can help manage your VMs and stay ahead of scaling, availability, and downtime risks as usage grows.
## Security and networking
Self-hosted is designed for teams that want Tembo inside a private cloud, dedicated network, or on-prem environment.
* You control ingress, DNS, TLS, and firewall policy
* Application data and runtime configuration stay in your environment
* Outbound access can be limited to the systems Tembo needs to reach, such as git providers, model endpoints, or internal services
* Upgrades happen on your schedule
## Who it is for
* Teams that need Tembo inside infrastructure they control
* Organizations with security or compliance requirements around source code, credentials, or runtime data
* Companies that want a simple single-instance deployment, with the option to use an external Postgres database
* Buyers who want a predictable, customer-managed upgrade process
If you do not need that level of control, the hosted SaaS product is usually simpler to adopt and operate.
## Next steps
* [Contact Us](https://book.avoma.com/tembo/tembo-self-hosted-discovery/)
***
## Need Help?
If you run into any issues, contact [support@tembo.io](mailto:support@tembo.io).
# Snapshots
Source: https://docs.tembo.io/features/snapshots
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.
# Tembo Documentation
Source: https://docs.tembo.io/index
Run any coding agent across your repos, tickets, and tools, with full visibility.
## What you can do with Tembo
Set up recurring workflows triggered by events or schedules.
Detect errors from Sentry, analyze the root cause, and open fix PRs automatically.
Assign issues from Linear, Jira, or GitHub and get code written for you.
Get automated code reviews on every PR with inline comments.
Scan for vulnerabilities, stale TODOs, and refactoring opportunities on a schedule.
Keep documentation in sync with your codebase as code changes.
## Agents & integrations
Tembo is harness and model agnostic. Pick the right tool for each session. Tag `@tembo` from wherever you already work.
See [all harnesses and models →](/features/agents#agent-harness) or [all integrations →](/integrations).
## Get started
Get up and running with Tembo in minutes.
Set up event-driven workflows that run automatically.
# Integrations
Source: https://docs.tembo.io/integrations
Connect the tools Tembo can read from, trigger from, and act in.
## Agent tools
} href="/integrations/mcp">
Connect built-in and custom MCP servers for agent tool access.
## Source control
} href="/integrations/github">
Pull requests, code review, issues, and automated workflows.
} href="/integrations/gitlab">
Merge requests, code scanning, and pipeline monitoring.
} href="/integrations/bitbucket">
Pull requests and code changes in your Bitbucket workspace.
} href="/integrations/chrome-extension">
Open GitHub, GitLab, and Bitbucket pull requests in Tembo review.
## Project management and knowledge
} href="/integrations/linear">
Assign issues to Tembo and get PRs back.
} href="/integrations/jira">
Assign tickets to Tembo and get PRs back.
} href="/integrations/notion">
Access workspace content and documentation.
## Communication
} href="/integrations/slack">
Trigger sessions by mentioning @tembo in any channel.
} href="/integrations/teams">
Trigger sessions by mentioning @Tembo in Teams chats or channels.
} href="/integrations/raycast">
Use quick commands and menubar access for Tembo sessions.
} href="/integrations/fathom">
Bring meeting recordings, transcripts, summaries, and action items into sessions.
## Data and infrastructure
} href="/integrations/aws">
Give agents access to AWS services via OIDC web identity federation.
} href="/integrations/postgres">
Monitor performance, detect slow queries, and optimize databases.
} href="/integrations/supabase">
Monitor and optimize Supabase database performance.
} href="/integrations/snowflake">
Call Tembo from Snowflake Cortex Agents via MCP.
} href="/integrations/bigquery">
Query BigQuery datasets from Tembo agents via MCP.
} href="/integrations/infisical">
Inject secrets into Tembo-powered runs without committing .env files.
Connect sessions to your private network with on-demand ephemeral keys.
## Monitoring and security
} href="/integrations/sentry">
Detect production errors and open fix PRs automatically.
} href="/integrations/snyk">
Scan vulnerabilities and open auto-fix PRs for dependencies.
## Business systems
} href="/integrations/hubspot">
Trigger sessions from CRM events and query HubSpot data live during sessions.
} href="/integrations/stripe">
Work with payments, billing, and customer operations via Stripe MCP.
# AWS
Source: https://docs.tembo.io/integrations/aws
Give your agents access to any AWS service via OIDC web identity federation — no static credentials required.
Tembo acts as an OIDC identity provider. Your agents receive short-lived STS credentials that expire automatically — no AWS access keys are ever stored in Tembo.
Connecting an account takes two things: an OIDC provider and an IAM role in your AWS account. You can let Tembo's CloudFormation template create both, or create them yourself with your own tooling.
## What agents can do
Once connected, agents have access to the [AWS Agent Toolkit](https://github.com/awslabs/mcp/tree/main/src/aws-api) — AWS's official MCP service covering 15,000+ APIs across every AWS service:
* **`call_aws`** — execute any authenticated AWS API call
* **`suggest_aws_commands`** — translate natural language to AWS API calls
* **`run_script`** — run Python code with AWS API access in a sandboxed environment
* **`search_documentation` / `read_documentation`** — search and read all AWS documentation
* **`get_presigned_url`** — generate pre-signed S3 URLs
Agents can only do what the IAM role permits. The default is `ReadOnlyAccess`; you control this entirely.
## Before you start
You need permission to create IAM roles and identity providers in the target AWS account.
Connect as many AWS accounts as you like. Each gets its own label and an isolated MCP server session, so a `production` and a `staging` account never share credentials.
## Choose a setup method
Fastest path. Tembo gives you a template that creates the OIDC provider and role for you.
Use your own Terraform, CDK, Pulumi, or the AWS CLI. Full requirements below.
Both produce identical results. Tembo only needs the finished role ARN.
## Option 1: Use the CloudFormation template
Go to [Integrations](https://app.tembo.io/integrations) and click **Connect** next to AWS. Enter a name for this account, for example `production`.
Click **Create via CloudFormation** to open a pre-filled stack in your AWS console, then deploy it.
If that link returns "Access Denied", download the template from the connect modal and upload it manually instead: in the [CloudFormation console](https://console.aws.amazon.com/cloudformation), choose **Create stack → With new resources → Upload a template file**, then supply your [workspace ID](#find-your-workspace-id) when prompted.
When the stack completes, open its **Outputs** tab and copy the `RoleArn` value.
Back in the connect modal, switch to **Enter ARN manually**, paste the ARN, and click **Connect**.
## Option 2: Create the resources yourself
Create two resources in the AWS account you want to connect, then hand Tembo the role ARN.
### Find your workspace ID
The role's trust policy has to name the workspace allowed to assume it. In Tembo, go to **Settings → Workspace** and copy the value under **Workspace ID**.
The value starts with `org_`, because a workspace is an organization internally. That's why the trust policy's subject is `org:` followed by this value.
### Requirements
| Setting | Value |
| --------------------------------- | ------------------------------------------------------------ |
| OIDC provider URL | `https://internal.tembo.io` |
| Audience (client ID) | `sts.amazonaws.com` |
| Trust policy action | `sts:AssumeRoleWithWebIdentity` |
| `internal.tembo.io:aud` condition | `sts.amazonaws.com` |
| `internal.tembo.io:sub` condition | `org:` |
| Max session duration | 3600 seconds |
| Permissions | Your choice. `ReadOnlyAccess` is the default Tembo suggests. |
Three details are easy to get wrong:
* **The provider must live in the same AWS account as the role.** AWS resolves the federated principal locally when the role is assumed, so a provider in another account will not work.
* **The condition keys drop the scheme.** They are `internal.tembo.io:sub`, not `https://internal.tembo.io:sub`.
* **The subject is prefixed.** If your workspace ID is `org_2vyf1Ja...`, the `sub` value is `org:org_2vyf1Ja...` — the literal string `org:` followed by the full ID.
Always pin the `sub` condition to your workspace ID. The OIDC provider only proves that Tembo signed the token, not which workspace it was issued for. Without the `sub` condition, a token issued to any other Tembo workspace would satisfy your trust policy.
### The OIDC provider
Register `https://internal.tembo.io` as an IAM OIDC identity provider with `sts.amazonaws.com` as the only audience.
You only need one per AWS account. IAM identity providers are global, so if you manage infrastructure per-region, create it once rather than once per region. If the provider already exists in the account, reuse it instead of creating a second one.
Thumbprints do not need maintaining. AWS verifies the JWKS endpoint's TLS certificate against its own library of trusted root certificate authorities, and only falls back to the configured thumbprint if the certificate is not signed by one of those. Tembo's endpoint uses a publicly trusted certificate, so a placeholder value of forty zeroes is fine.
### The IAM role
Attach this trust policy, replacing the account ID and workspace ID:
```json Trust policy theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::111122223333:oidc-provider/internal.tembo.io"
},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"internal.tembo.io:aud": "sts.amazonaws.com",
"internal.tembo.io:sub": "org:org_2vyf1Ja..."
}
}
}
]
}
```
Then attach permissions. Start with `arn:aws:iam::aws:policy/ReadOnlyAccess` and narrow or widen it to suit. Set the role's maximum session duration to 3600 seconds to match the session length Tembo requests.
The role name does not matter — Tembo identifies the role by ARN.
### Terraform
```hcl theme={null}
resource "aws_iam_openid_connect_provider" "tembo" {
url = "https://internal.tembo.io"
client_id_list = ["sts.amazonaws.com"]
thumbprint_list = ["0000000000000000000000000000000000000000"]
}
data "aws_iam_policy_document" "tembo_assume_role" {
statement {
effect = "Allow"
actions = ["sts:AssumeRoleWithWebIdentity"]
principals {
type = "Federated"
identifiers = [aws_iam_openid_connect_provider.tembo.arn]
}
condition {
test = "StringEquals"
variable = "internal.tembo.io:aud"
values = ["sts.amazonaws.com"]
}
condition {
test = "StringEquals"
variable = "internal.tembo.io:sub"
values = ["org:${var.tembo_workspace_id}"]
}
}
}
resource "aws_iam_role" "tembo" {
name = "tembo-integration"
assume_role_policy = data.aws_iam_policy_document.tembo_assume_role.json
max_session_duration = 3600
}
resource "aws_iam_role_policy_attachment" "tembo_read_only" {
role = aws_iam_role.tembo.name
policy_arn = "arn:aws:iam::aws:policy/ReadOnlyAccess"
}
output "tembo_role_arn" {
value = aws_iam_role.tembo.arn
}
```
### AWS CLI
```bash theme={null}
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
TEMBO_WORKSPACE_ID=org_2vyf1Ja... # from Settings → Workspace
aws iam create-open-id-connect-provider \
--url https://internal.tembo.io \
--client-id-list sts.amazonaws.com \
--thumbprint-list 0000000000000000000000000000000000000000
cat > trust-policy.json <
**Self-hosted Tembo:** replace `internal.tembo.io` throughout with your instance's `TEMBO_OIDC_ISSUER` hostname, scheme stripped. Your instance must serve `/.well-known/openid-configuration` and `/.well-known/jwks.json` over public HTTPS, because AWS STS fetches the JWKS itself when a role is assumed — reachability from inside your own network is not enough.
## How authentication works
Tembo never stores AWS credentials. For each agent run:
1. Tembo mints a short-lived RS256 JWT (5-minute TTL) signed with its OIDC private key, carrying `iss` of the Tembo issuer, `aud` of `sts.amazonaws.com`, and `sub` of `org:`
2. Tembo calls `sts:AssumeRoleWithWebIdentity` against your role, presenting that JWT. This call carries no AWS credentials of its own — the token is the identity
3. STS finds the OIDC provider in your account matching the token's issuer, fetches Tembo's public JWKS to verify the signature, then evaluates your trust policy conditions
4. The resulting temporary credentials (1-hour TTL) are injected into the agent's sandbox and never leave it
Because the token is the identity, nothing about this depends on which AWS account Tembo runs in.
## Troubleshooting
The one-click URL fetches the template from an S3 bucket. If the bucket policy has not been updated, the AWS console returns an access denied error. Download the template from the connect modal and upload it manually instead — it creates identical resources.
Work through these in order:
1. **Provider URL exact match.** It must be `https://internal.tembo.io` — correct scheme, no trailing slash, no typos. STS matches the token's `iss` claim against the registered provider URL exactly.
2. **Provider is in the same account as the role.** A provider in a different account is not usable.
3. **`sub` includes the `org:` prefix.** The value is `org:org_2vyf1Ja...`, not `org_2vyf1Ja...`.
4. **Condition keys have no scheme.** `internal.tembo.io:sub`, not `https://internal.tembo.io:sub`.
5. **Workspace ID matches.** Compare against the value under **Workspace ID** in **Settings → Workspace**.
Sessions are 1 hour. If your role's maximum session duration is lower than 3600 seconds, sessions will be shorter than expected — raise it to 3600.
The agent sandbox requires outbound access to `https://aws-mcp.us-east-1.api.aws` for the AWS Agent Toolkit MCP service. On self-hosted deployments in a private network, confirm egress to that endpoint is allowed.
The role's policies decide what agents can do, and `ReadOnlyAccess` is read-only by design. To allow writes, attach additional policies to the role. Note that `ReadOnlyAccess` does grant `s3:Get*`, so agents can read object contents — attach an explicit `Deny` if you need to keep specific buckets out of reach.
Some AWS features encrypt data with a customer-managed KMS key and require the caller to hold `kms:Decrypt` on that key. `ReadOnlyAccess` does not grant `kms:Decrypt`. Add a scoped statement to the role for the specific key, ideally conditioned on `kms:ViaService` so it is only usable through the owning service.
# BigQuery
Source: https://docs.tembo.io/integrations/bigquery
Query BigQuery datasets from Tembo agents.
## Features
* MCP server for querying BigQuery datasets during sessions
## Installation
Go to [Integrations](https://app.tembo.io/integrations) and click **Connect** next to BigQuery, then enter your Google Cloud **Project ID** and a service account JSON key with access to your BigQuery datasets.
## Usage
After connecting, Tembo can query your BigQuery datasets during sessions through a dedicated MCP server for that project.
## Advanced
The BigQuery MCP can run queries against your project during sessions when querying would help complete the work.
Use a dedicated service account scoped to only the datasets Tembo needs to query.
# Bitbucket
Source: https://docs.tembo.io/integrations/bitbucket
Pull requests and code changes in your Bitbucket workspace.
## Features
* Open pull requests with code changes
* Respond to PR feedback and iterate
* Draft PR support with automatic branch cleanup
* Multi-workspace repository sync
## Installation
Create a dedicated Bitbucket account for Tembo using an email alias (`you+tembo@company.com`) or dedicated email. Invite it to your workspace.
Go to [Integrations](https://app.tembo.io/integrations) and click **Install** next to Bitbucket. Log in as the Tembo service account.
Select which repositories Tembo should work with.
## Usage
### PR comments
Add `/tembo` in any pull request comment to request changes. Tembo reads the feedback, updates the code, and pushes new commits.
```
/tembo Please add error handling to this function
```
Works on PRs created by Tembo and PRs created by your team.
## Agents
See [Agents](/features/agents) for available Bitbucket event triggers.
## Advanced
Wait 2-5 minutes for initial sync. Click the sync button to refresh. Verify the service user has workspace access.
Check that the repository is activated and branch protection rules allow Tembo to create branches.
Ensure the service user has proper permissions and workspace membership. Try disconnecting and reconnecting.
# Chrome extension
Source: https://docs.tembo.io/integrations/chrome-extension
Open GitHub, GitLab, and Bitbucket pull requests in Tembo review.
The Tembo Chrome extension redirects supported pull request pages to the matching Tembo review, so you can review code in Tembo instead of staying in the git provider.
## Features
* Redirect GitHub pull requests to Tembo review
* Redirect GitLab merge requests to Tembo review
* Redirect Bitbucket pull requests to Tembo review
* Toggle redirects on or off from the extension popup
* Configure the redirect base URL for self-hosted Tembo deployments
## Installation
Install [Tembo from the Chrome Web Store](https://chromewebstore.google.com/detail/tembo/ndddjkpleekhdmmnnlpoofojjhapekbi?authuser=0\&hl=en).
Sign in to [Tembo](https://app.tembo.io) with the workspace that has access to the repository.
Open a supported GitHub, GitLab, or Bitbucket pull request. The extension redirects the page to the matching Tembo review.
## Supported pull request URLs
The extension supports pull requests and merge requests on the hosted git providers:
| Provider | Supported URL pattern |
| --------- | ----------------------------------------------------------------- |
| GitHub | `https://github.com/{owner}/{repo}/pull/{number}` |
| GitLab | `https://gitlab.com/{group}/{project}/-/merge_requests/{number}` |
| Bitbucket | `https://bitbucket.org/{workspace}/{repo}/pull-requests/{number}` |
## Usage
When you visit a supported pull request URL, the extension sends you to Tembo's review redirect page. Tembo resolves the provider URL inside your active organization and opens the matching review.
The repository must be connected to Tembo through [GitHub](/integrations/github), [GitLab](/integrations/gitlab), or [Bitbucket](/integrations/bitbucket).
## Advanced
Click the Tembo extension icon and turn redirects off. Turn them back on when you want provider pull request pages to open in Tembo again.
Click the Tembo extension icon and change **Base URL** if you use self-hosted Tembo. The extension uses this as the redirect base URL. The default is `https://app.tembo.io`.
Confirm redirects are enabled, you are using a supported hosted provider URL, and the repository is connected to Tembo. Self-hosted git provider domains are not supported by the extension.
# Fathom
Source: https://docs.tembo.io/integrations/fathom
Bring your Fathom meeting recordings, transcripts, summaries, and action items into Tembo sessions.
## Features
* Read access to your Fathom meeting recordings, transcripts, summaries, and action items
* Search meetings by title, host, or attendee name/email
* Surface meeting context to Tembo agents during sessions for follow-up tasks, summaries, and action-item triage
## Installation
In the Tembo app, go to **Settings → Integrations**.
Scroll to the **Productivity** group and click **Install** next to Fathom.
If you have to create an account at this step, you will have to go back into Tembo and restart the install process.
A popup opens at `fathom.video`. Sign in with the Fathom account you want to connect.
The popup host is `fathom.video`, not `api.fathom.ai`. This is expected — Fathom routes the OAuth consent screen through their main app domain.
Fathom will then ask you to grant the `mcp` scope. Click **Authorize**.
After authorizing, you'll be redirected back to the Tembo Integrations page and Fathom will switch from uninstalled to installed.
## Usage
Once installed, Tembo agents automatically have access to the Fathom MCP server during sessions. No further configuration is needed — agents can search your meetings, read transcripts and summaries, and reference action items to inform the changes they propose.
## Advanced
Tembo's Fathom integration requests a single OAuth scope, `mcp`, which grants the agent **read-only** access to Fathom resources exposed through the official Fathom MCP server (`https://api.fathom.ai/mcp`): meetings, recordings, transcripts, summaries, action items, teams, and members. Tembo cannot create, modify, or delete meetings or any other Fathom data.
Each Tembo user connects their own Fathom account. Your token only sees meetings you recorded plus any meetings shared with your team in Fathom. To give Tembo broader visibility, have additional teammates install the integration with their own Fathom accounts.
During install, the OAuth popup opens at `fathom.video/mcp/oauth/authorize` rather than `api.fathom.ai`. This is how Fathom's published OAuth discovery document directs clients — the consent screen lives on the main app domain, the token endpoint lives on the API domain.
Fathom access tokens are short-lived. Tembo refreshes them automatically using the rotating refresh token issued during install. If a refresh fails (for example, if you revoked access in Fathom), the integration will surface a reconnect prompt — go to **Settings → Integrations** and click **Install** on the Fathom card to re-authorize.
# GitHub
Source: https://docs.tembo.io/integrations/github
Pull requests, code review, and automated workflows.
## Features
* Open pull requests with code changes
* Review PRs with inline comments
* Respond to PR feedback and iterate
* Start work from GitHub issues
* Auto-fix failed GitHub Actions workflows
* Signed and verified commits on all Tembo PRs
## Installation
Go to [Integrations](https://app.tembo.io/integrations) and click **Install** next to GitHub.
Choose **All repositories** or **Selected repositories** and authorize.
Select which repositories Tembo should work with under "Active Repositories".
## Usage
### PR comments
Comment `@tembo` on any pull request to request changes. Works in the main thread or as inline review comments on specific lines. Tembo reads the feedback, updates the code, and pushes new commits.
```
@tembo Please add error handling to this function
```
Works on PRs created by Tembo and PRs created by your team.
### Issues
Comment `@tembo` on any issue to start implementation. Tembo reads the issue title and description, then opens a PR.
```
@tembo Implement the API endpoint described in this issue
```
## Agents
See [Agents](/features/agents#event-driven) for available GitHub event triggers.
### PR reviews
Reviews pull requests for bugs, security issues, and code quality. Leaves inline comments automatically when a PR is opened.
### Enrich issues
Adds codebase context to new GitHub issues, helping agents and teammates understand the relevant code before starting work.
### Failed workflows
Detects GitHub Actions failures and opens fix PRs automatically.
## Advanced
By default, PRs and commits are made under the Tembo bot account. To attribute them to your GitHub user instead, connect your personal GitHub account in your [Tembo user settings](https://app.tembo.io/settings).
All commits in Tembo PRs are automatically signed and verified with a "Verified" badge in GitHub.
No configuration needed.
Tembo can merge or close a pull request through GitHub tool calls. If a merge or close action is requested while another Tembo job is already running on that pull request, the agent rejects the request. Wait for the active job to finish, then try again.
Wait 2-5 minutes for initial sync. If they still don't show, click the sync button on the GitHub
integration card. Check that you granted Tembo access during installation and that you have
permission to install GitHub Apps for your organization.
Make sure you're using `@tembo` (lowercase) and that the repository is activated in Integrations.
Check that the repository is activated and there isn't already an open PR for the same issue.
# GitLab
Source: https://docs.tembo.io/integrations/gitlab
Merge requests, code scanning, and pipeline monitoring.
## Features
* Open merge requests with code changes
* Respond to MR feedback and iterate
* Auto-fix failed CI/CD pipelines
* Scan for TODOs, security issues, and tech debt
## Installation
Tembo supports a shared GitLab service account or a personal account connected through OAuth. We recommend a service account so the integration does not depend on an individual team member.
### Connect a service account
You must be a Tembo organization admin. On GitLab.com, you must also be an Owner of the top-level group and may need to verify your identity. For GitLab Self-Managed or Dedicated, you must be an instance administrator or an Owner who is allowed to create service accounts.
In GitLab, open your top-level group and go to **Settings → Service accounts**. Select **Add service account**, name the account, and select **Create service account**.
See [GitLab's service account instructions](https://docs.gitlab.com/user/profile/service_accounts/#create-a-service-account) for GitLab.com and self-managed prerequisites.
Add the service account as a member of the top-level group or each project that Tembo should access. Assign the **Maintainer** role so Tembo can create project webhooks as well as branches and merge requests. GitLab requires the Maintainer or Owner role to [create project webhooks](https://docs.gitlab.com/user/project/integrations/webhooks/#create-a-webhook).
On **Settings → Service accounts**, open the service account's menu and select **Manage access tokens → Add new token**. Enter a name and expiration date, select only the `api` scope, and select **Create personal access token**. Copy the generated token.
GitLab documents token creation, expiration limits, rotation, and revocation under [Create a personal access token for a service account](https://docs.gitlab.com/user/profile/service_accounts/#create-a-personal-access-token-for-a-service-account).
In Tembo, go to [Integrations](https://app.tembo.io/integrations) and select **Install** next to GitLab. Paste the token into **Service account access token**, then select **Connect with access token**.
Select which repositories Tembo should work with under **Active Repositories**.
Tembo rejects tokens owned by regular personal user accounts. When the service account token expires, is rotated, or is revoked, reconnect the integration with the new token.
### Connect with OAuth
Go to [Integrations](https://app.tembo.io/integrations), select **Install** next to GitLab, and select **Continue with OAuth**. Authorize access, then select which repositories Tembo should work with under **Active Repositories**.
## Usage
### MR comments
Comment `@tembo` on any merge request to request changes. Works in the main thread or as inline review comments.
```
@tembo Please add error handling to this function
```
Works on MRs created by Tembo and MRs created by your team.
## Agents
See [Agents](/features/agents) for available GitLab event triggers.
### Failed pipelines
Tembo can detect CI/CD pipeline failures and open fix MRs automatically. Set up an [agent](/features/agents) with a pipeline failure trigger.
## Advanced
Wait 2-5 minutes for initial sync. Click the sync button on the GitLab integration card to refresh. Check that you granted access during installation.
Make sure you're using `@tembo` (lowercase) and that the repository is activated in Integrations.
Check that the repository is activated and there isn't already an open MR for the same issue.
# HubSpot
Source: https://docs.tembo.io/integrations/hubspot
Trigger Tembo sessions from HubSpot CRM events and query HubSpot data live during sessions.
HubSpot connects to Tembo as **two separate apps** that you can install independently or together:
* **HubSpot Triggers** — webhook-driven CRM events that start Tembo sessions
* **HubSpot MCP** — an MCP server agents use to query HubSpot data during sessions
You install each from the [Integrations page](https://app.tembo.io/integrations).
## Features
* 14 webhook triggers across contacts, companies, deals, tickets, and tasks
* HubSpot MCP server for in-session CRM queries
* Workflow templates for common CRM patterns
* Signed webhooks with HubSpot's v3 signature scheme
## Installation
Go to [Integrations](https://app.tembo.io/integrations) and click **Install** next to HubSpot Triggers. Authorize Tembo in the HubSpot OAuth flow.
From the same page, install HubSpot MCP. This is a separate authorization for the MCP server agents use during sessions.
On the [Agents](/features/agents) page, pick which HubSpot trigger events should start sessions.
## Usage
1. An event happens in HubSpot — a new ticket, a deal stage change, a contact deletion.
2. HubSpot sends a signed webhook to Tembo.
3. Tembo verifies the signature, matches the portal to your workspace, and evaluates triggers.
4. Matching triggers start sessions according to your agent configuration.
During a session, agents can also reach into HubSpot directly through the MCP server to look up additional context — related deals, contact history, engagement records.
## Triggers
Three event families across four CRM objects, plus two specialized events:
### Creation
* `contact.creation`, `company.creation`, `deal.creation`, `ticket.creation`, `task.creation`
### Property change
* `contact.propertyChange`, `company.propertyChange`, `deal.propertyChange`, `ticket.propertyChange`
### Deletion
* `contact.deletion`, `company.deletion`, `deal.deletion`, `ticket.deletion`
### Specialized
* `deal.associationChange` — fires when a deal's associations to other objects change
See [Agents](/features/agents) for trigger-to-agent configuration.
## Workflow templates
Three HubSpot-centric templates ship with Tembo:
* **HubSpot Call Task Coach** (Productivity) — on a new CALL task, posts a pre-call brief to Slack with context pulled from the related contact, deal, and recent engagements.
* **HubSpot Email Task Drafter** (Productivity) — on a new EMAIL task, drafts a personalized outreach email and saves it as a draft. Never sends automatically.
* **HubSpot Ticket → Linear Bug** (Management) — triages new HubSpot tickets and files Linear bugs with customer context when engineering action is needed.
## Advanced
HubSpot exposes triggers and MCP as two separate apps in their marketplace, so Tembo installs them separately too. Triggers deliver CRM events into Tembo as session starts. MCP lets agents query HubSpot live during a running session. Install both for full coverage.
Verify the HubSpot portal is connected on the [Integrations page](https://app.tembo.io/integrations). Triggers fire per workspace agent config — double-check your [Agents](/features/agents) settings.
Tembo validates `X-HubSpot-Signature-v3` with a 5-minute timestamp window. If events are silently dropped, check that your system clock and HubSpot's are in sync.
Not every object has every event. Tasks only emit creation; only deals emit association change. If you need a trigger that isn't listed, let us know.
# Infisical
Source: https://docs.tembo.io/integrations/infisical
Inject secrets into Tembo-powered runs without committing .env files.
## Features
* Works out of the box in Tembo sandboxes (Infisical CLI is already installed)
* Injects secrets at runtime without committing `.env` files
* Supports optional env var overrides for project/environment/path/domain defaults
## Installation
In Tembo, go to **Settings** -> **Sandbox**.
Add `INFISICAL_TOKEN` to your sandbox environment variables and save.
Start a new Tembo session. That's it.
## Usage
In Tembo sandbox sessions, this will automatically work once `INFISICAL_TOKEN` is set.
Run commands with `infisical run --`:
```bash theme={null}
infisical run -- bun run --watch index.ts
infisical run -- next dev --turbopack --port 3000
```
If your script cannot infer the Infisical project automatically, add
`--projectId` before the command separator:
```bash theme={null}
infisical run --projectId -- bun run --watch index.ts
```
## Optional overrides
If you want to override defaults for `infisical run`, add these in **Settings -> Sandbox**:
* `INFISICAL_PROJECT_ID`
* `INFISICAL_ENV`
* `INFISICAL_SECRET_PATH`
* `INFISICAL_API_URL`
Explicit CLI flags still win over env-var defaults.
# Jira
Source: https://docs.tembo.io/integrations/jira
Assign tickets to Tembo and get PRs back.
## Features
* Add the `Tembo` label to trigger implementation
* Use `tembo/{repo-name}` labels to target specific repositories
* Status updates and PR links posted as comments
## Installation
Create a dedicated standard Jira user for Tembo using an email alias (`you+tembo@company.com`) or dedicated mailbox. In the Jira user profile, set the name/display name to `Tembo` so integration comments show up as `Tembo`.
Go to [Integrations](https://app.tembo.io/integrations) and click **Install** next to Jira. Log in as the standard Jira user.
Create a `Tembo` label in your Jira project (recommended). Add it to any issue you want Tembo to work on.
## Usage
Add the `Tembo` label to any issue. Tembo reads the description, creates a coding session, and opens a PR.
If you add a `tembo/{repo-name}` label, that also triggers Tembo and routes the task to the selected repository.
### Target a specific repository
Add a label in the format `tembo/{repo-name}` (for example, `tembo/monorepo`). This label also triggers processing on its own, so you do not need a separate `Tembo` label.
* `{repo-name}` must match the repository name as it appears in Tembo (the `name` field on the connected repository).
* The `tembo/` prefix is case-sensitive: use lowercase `tembo/`.
* Valid characters in `{repo-name}` are letters, numbers, `_`, `.`, and `-`.
When multiple `tembo/{repo-name}` labels are present, Tembo uses the first one that matches a connected, enabled repository.
### Fallback behavior
If no `tembo/{repo-name}` label matches a connected, enabled repository, Tembo falls back in this order:
1. The default repository configured for your Jira integration in Tembo
2. The first available enabled repository in your Tembo organization
## Agents
See [Agents](/features/agents) for available Jira event triggers.
## Advanced
Verify the issue has the `Tembo` label or a `tembo/{repo-name}` label (for example, `tembo/monorepo`). Confirm you installed using the dedicated standard Jira user. Check integration status on the [Integrations page](https://app.tembo.io/integrations).
Ensure GitHub/GitLab/Bitbucket is connected. Include clear descriptions with acceptance criteria.
# Linear
Source: https://docs.tembo.io/integrations/linear
Assign issues to Tembo and get PRs back.
## Features
* Assign issues to Tembo to trigger implementation
* Multi-repository support for full-stack features
* Status updates and PR links posted to issues
* MCP server for real-time issue data access during sessions
## Installation
Go to [Integrations](https://app.tembo.io/integrations) and click **Install** next to Linear.
Authorize Tembo to access your Linear workspace.
Tembo creates a "Tembo Git Repositories" label group with your repos. Set a default repository to avoid labeling every issue.
## Usage
Assign a Linear issue to Tembo. Select one or more repositories when prompted. Tembo reads the issue, writes the code, and opens PRs.
For multi-repo sessions, select multiple repositories and Tembo coordinates changes across all of them. It can also handle repositories across different git providers when needed.
## Agents
See [Agents](/features/agents) for available Linear event triggers.
## Advanced
When connected, a Linear MCP server is automatically available to agents. They can query issues, access project details, and read comments in real-time.
Verify the issue is assigned to the Tembo bot user. Check integration status on the [Integrations page](https://app.tembo.io/integrations).
Ensure you've connected a code hosting provider (GitHub/GitLab/Bitbucket) and repositories are visible in your dashboard.
# MCP
Source: https://docs.tembo.io/integrations/mcp
Connect built-in and custom MCP servers for agent tool access.
MCP (Model Context Protocol) servers let agents use external tools and data during sessions.
## Features
* Install MCP servers from the [Integrations page](https://app.tembo.io/integrations)
* Add your own MCP servers with `stdio`, `http`, or `sse` transport
* Connect OAuth-based remote MCP servers
* Enable MCP servers from existing integrations automatically (GitHub, Linear, Sentry, Postgres)
## Installation
Go to [Integrations](https://app.tembo.io/integrations).
Install any listed MCP integration (for example, Notion or Stripe). Once connected, the server is available in new sessions.
Click **Custom MCP**, paste your JSON config, then save.
## Usage
### Prerequisites
* You have access to your organization in Tembo
* You have the server URL or command needed to start your MCP server
* You have any required credentials (API key, OAuth app, or environment variables)
### Custom server transport types
#### HTTP
Use this for hosted MCP endpoints.
```json theme={null}
{
"mcpServers": {
"api-server": {
"type": "http",
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer token"
}
}
}
}
```
#### SSE
Use this for hosted MCP servers that expose an SSE endpoint.
```json theme={null}
{
"mcpServers": {
"events-server": {
"type": "sse",
"url": "https://example.com/sse"
}
}
}
```
#### Stdio
Use this when the MCP server runs as a local command.
```json theme={null}
{
"mcpServers": {
"github-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "your-github-token"
}
}
}
}
```
### Configuration formats
Tembo accepts both of these formats:
* Object format (recommended): `mcpServers` is an object keyed by server name
* Array format: `mcpServers` is an array with explicit `name` values
```json theme={null}
{
"mcpServers": [
{
"name": "api-server",
"type": "http",
"url": "https://example.com/mcp"
}
]
}
```
## Advanced
If a remote server requires OAuth, Tembo prompts you to authorize during setup and completes the connection after you approve access.
Check that the JSON is valid, required fields are present, and the integration is saved successfully. Start a new session after saving to pick up updated MCP config.
Verify API keys, headers, or environment variables. For `http` and `sse` servers, confirm the URL is reachable from your server environment.
# Notion
Source: https://docs.tembo.io/integrations/notion
Access workspace content and documentation.
## Features
* MCP server access to pages, databases, and workspace content
* Agents can reference documentation during sessions
* OAuth authentication with workspace-scoped access
## Installation
Go to [Integrations](https://app.tembo.io/integrations) and click **Install** next to Notion.
Authorize Tembo and select which pages it can access.
## Usage
Once connected, the Notion MCP server is automatically available to agents. They can read pages, query databases, and navigate your workspace to pull context during sessions.
## Advanced
Verify you completed the OAuth flow and granted access to the correct workspace. Check that you selected pages during authorization.
During authorization, you must explicitly select which pages Tembo can access. Nested pages inherit parent permissions.
# OpenConnect
Source: https://docs.tembo.io/integrations/openconnect
Connect sandboxes to private networks via OpenConnect VPN.
The OpenConnect integration is currently in preview. Contact
[support](/support) if you'd like it enabled for your organization.
## Features
* Connect agent sandboxes to private networks so they can reach internal databases and services
* The agent connects on demand — only when a task actually needs the private network — instead of on every session
* Works alongside the Postgres integration to access databases that aren't publicly reachable
## Supported VPNs
The VPN integration uses [OpenConnect](https://www.infradead.org/openconnect/), an open-source VPN client that is compatible with several enterprise VPN servers:
| Protocol | Compatible with |
| ----------------------- | ------------------------------------------- |
| Fortinet SSL VPN | FortiClient, FortiGate |
| Cisco AnyConnect | Cisco Secure Client, ASA, IOS |
| Palo Alto GlobalProtect | GlobalProtect client, PAN-OS |
| Juniper Network Connect | Juniper/Pulse Secure, Ivanti Connect Secure |
If your organization uses any of these VPN products, Tembo can connect to it directly — no changes to your VPN infrastructure required.
## Installation
Open [Integrations](https://app.tembo.io/integrations) and click **Install** next to OpenConnect under the **Developer Tools** category.
Fill in the connection form:
* **Connection Name** — a label for this VPN (e.g. "Production VPN")
* **Protocol** — select your VPN type
* **VPN Gateway** — the hostname or IP of your VPN concentrator (e.g. `vpn.example.com`)
* **Username** and **Password** — credentials that the sandbox will use to authenticate
Once the VPN is configured, add a [Postgres integration](/integrations/postgres) using the **private** connection string of your database. When the agent needs to reach the database, it connects the VPN first, then reaches it through the tunnel.
## Usage
Once configured, the agent gains a **connect** tool. It brings up the VPN on demand — when a task requires reaching a host that's only available on your private network — rather than on every session. You can also just ask the agent to connect. The tunnel then stays active for the rest of the session.
This is useful when your database or internal services are behind a firewall and not reachable from the public internet. Instead of exposing your database publicly or setting up a bastion host, you provide the same VPN credentials your team already uses.
### Example workflow
1. Configure the VPN integration with your gateway credentials
2. Add a Postgres integration with your private connection string (e.g. `postgresql://user:pass@10.0.1.50:5432/mydb`)
3. In a session, the agent connects to the VPN when it needs the database (or when you ask it to), then queries your database as if it were on your network
## Advanced
The connect tool runs OpenConnect inside the sandbox VM to establish a VPN tunnel. This creates a virtual network interface (`tun0`) that routes traffic to your private network through the encrypted tunnel. The connection is on demand — nothing happens until the agent invokes the tool — and does not persist across sessions, so a new session starts without a tunnel until it's needed again.
OpenConnect supports some forms of MFA (e.g. TOTP tokens appended to the password field), but interactive MFA prompts are not supported. If your VPN requires interactive two-factor authentication, consider creating a dedicated service account with a static password or certificate-based authentication for Tembo access.
VPN credentials are never exposed to the agent. When the connect tool runs, the system fetches the credentials over an authenticated channel only for the moment of connecting, hands the password directly to OpenConnect, and discards it — it is not written to disk or placed in the agent's context. Even so, consider using a dedicated VPN account with limited network access scoped to only the resources Tembo needs.
# Postgres
Source: https://docs.tembo.io/integrations/postgres
Performance monitoring, slow query detection, and optimization.
## Features
* Monitor slow queries and suggest optimizations
* Detect missing and unused indexes
* Open PRs with migration scripts
* MCP server for read-only database access during sessions
## Installation
Go to [Integrations](https://app.tembo.io/integrations) and click **Connect** next to Postgres, then enter your database connection string.
## Usage
After connecting, Tembo can use Postgres tools to run queries against your database during sessions.
Tembo also monitors your database using `pg_stat_statements`. When it finds slow queries or missing indexes, it opens a PR with migration scripts and expected improvement metrics.
Requires `pg_stat_statements` extension: `CREATE EXTENSION IF NOT EXISTS pg_stat_statements;`
## Advanced
The Postgres MCP can access your database during sessions when querying would help complete the work.
You only need to provide a valid connection string. Always review migration PRs before merging, especially for large tables.
# Raycast
Source: https://docs.tembo.io/integrations/raycast
Quick commands and menubar access for Tembo sessions.
## Features
* Create sessions from Raycast
* View and filter sessions with search
* Menubar integration for quick access
* Raycast AI natural language support
## Installation
Install the Tembo extension from the [Raycast Store](https://www.raycast.com/store) or search "Tembo" in the command palette.
Generate an API key from **Settings > API Keys** in the [dashboard](https://app.tembo.io).
Open Raycast preferences, go to Extensions > Tembo, and enter your API key.
## Usage
**Create Session** - Enter a description, select a repository, and set priority.
**View Sessions** - Filter by repository, status, or assignee. Search through descriptions.
**Menubar** - See active sessions at a glance with status indicators.
**Raycast AI** - Use natural language: "Create a session to fix the login bug" or "Show my in-progress sessions".
## Advanced
`⌘+K` open command palette, `⌘+Enter` create session, `⌘+R` refresh session list, `⌘+,` extension settings.
Verify your API key is correct in extension settings. Try refreshing with `⌘+R`.
# Sentry
Source: https://docs.tembo.io/integrations/sentry
Automatic error detection and fix PRs.
## Features
* Detect errors as they occur in production
* Analyze stack traces, breadcrumbs, and error context
* Open fix PRs automatically
* MCP server for real-time error data access during sessions
## Installation
Go to [Integrations](https://app.tembo.io/integrations) and click **Connect** next to Sentry.
Authorize Tembo to read error data and receive webhook events.
Map Sentry projects to the repositories where errors occur. Only mapped projects generate fix PRs.
## Usage
1. Sentry captures an error and sends a webhook to Tembo
2. Tembo retrieves the full error context (stack traces, breadcrumbs, environment)
3. Tembo analyzes the codebase and opens a fix PR
4. Use the [feedback loop](/features/feedback-loop) to iterate
## Agents
See [Agents](/features/agents) for available Sentry event triggers.
## Advanced
When connected, a Sentry MCP server is automatically available to agents. They can query error data, retrieve stack traces, and analyze trends in real-time.
Check project mapping on the Integrations page. Ensure Sentry captures sufficient stack trace info. Tembo deduplicates fixes for already-addressed errors.
Use the sync button to refresh projects. Verify Tembo has access and the Sentry organization is connected.
# Slack
Source: https://docs.tembo.io/integrations/slack
Trigger sessions by mentioning @tembo in any channel.
## Features
* Create sessions by mentioning `@tembo` in any channel or DM
* Specify repos, branches, and agents inline
* Thread context is automatically read
* Status reactions and PR notifications in Slack
## Installation
Go to [Integrations](https://app.tembo.io/integrations) and click **Install** next to Slack.
Authorize Tembo to access your Slack workspace.
Connect your repositories first (GitHub, GitLab, or Bitbucket), then set a default repository in the Slack integration settings.
## Usage
### Basic
```
@tembo Fix the authentication bug in the login flow
```
### With options
```
@tembo In owner/webapp on branch dev, add password strength validation
```
**You can specify:** repository, branch, and agent in plain text (for example: `owner/webapp`, `branch dev`, `agent gpt-5.4`).
### Multiple repositories
```
@tembo Add user authentication in owner/frontend and owner/backend
```
Tembo creates separate PRs for each repo and coordinates changes.
### Thread context
Mention `@tembo` in a thread and it reads the full conversation history for context.
### Iterate in Slack
After Tembo opens a PR, you can keep mentioning `@tembo` in the same Slack thread to give feedback and iterate. No need to leave comments on the PR itself.
### Cancel sessions
Click the options on Tembo's message in Slack to stop a running session without leaving Slack.
### Status indicators
* ⌛️ Working
* ✅ Complete
* ❌ Failed
When done, Tembo posts PR links back to the thread.
## Agents
See [Agents](/features/agents) for available Slack event triggers.
## Advanced
Verify Tembo is installed on the [Integrations page](https://app.tembo.io/integrations). Invite the bot to the channel with `/invite @tembo`.
Set a default repository in Slack integration settings, or specify the repository directly in your message (for example: `owner/repo`).
When you leave feedback on a PR created from Slack, Tembo posts a notification back to the original Slack thread with a summary of changes.
# Snowflake
Source: https://docs.tembo.io/integrations/snowflake
Call Tembo from Snowflake Cortex Agents via the Model Context Protocol.
## Overview
This integration is the inverse of most Tembo integrations: Snowflake is the **MCP client** and Tembo is the **MCP server**. Once configured, your Snowflake users can ask a Cortex Agent things like *"list my Tembo sessions"* or *"trigger a Tembo agent on issue X"* directly from **Snowflake Intelligence** chat — the same surface they already use for Cortex Analyst and Cortex Search.
The integration is implemented as a Snowflake-managed MCP server that exposes Tembo's public REST API as a set of `GENERIC` tools. The API token lives in Snowflake's secret store; agents call the tools through a Python UDF that handles auth and routing.
| Component | Purpose |
| ---------------------------------------------- | -------------------------------------------------------- |
| Snowflake `SECRET` | Stores the Tembo API token |
| `NETWORK RULE` + `EXTERNAL ACCESS INTEGRATION` | Allows egress to `api.tembo.io` |
| Python UDF (`tembo_call`) | Makes authenticated HTTPS requests to the Tembo REST API |
| Snowflake-managed `MCP SERVER` | Exposes the UDF as named `GENERIC` tools |
| Cortex Agent | Routes user prompts to the right Tembo tool |
An alternative OAuth2-based path using `CREATE EXTERNAL MCP SERVER` is documented in the **Advanced** section, but requires OAuth2 support that the Tembo MCP server does not yet expose. Use the steps below for any current deployment.
***
## Prerequisites
* A Snowflake account with **Cortex Agents** and **Snowflake Intelligence** enabled
* A Snowflake role with:
* `CREATE INTEGRATION ON ACCOUNT`
* `CREATE MCP SERVER` on the target schema
* `CREATE AGENT` on the target schema
* `USAGE` on a warehouse the agent will run with
* A Tembo API token — generate one from your Tembo account settings
* The Tembo REST API base URL: `https://api.tembo.io`
For self-hosted Tembo installs, substitute your deployment's base URL throughout. See [Self-Hosted Overview](/features/self-hosted/overview) for details.
***
## Step 1: Store the Tembo API Token as a Snowflake Secret
```sql theme={null}
CREATE OR REPLACE SECRET tembo_api_token
TYPE = GENERIC_STRING
SECRET_STRING = '';
```
Never paste the token directly into a UDF body or stored procedure. Always reference it through the `SECRET` object and the `_snowflake.get_generic_secret_string` API.
To rotate later, regenerate the token in Tembo and run:
```sql theme={null}
ALTER SECRET tembo_api_token SET SECRET_STRING = '';
```
***
## Step 2: Allow Egress to api.tembo.io
```sql theme={null}
CREATE OR REPLACE NETWORK RULE tembo_api_network_rule
MODE = EGRESS
TYPE = HOST_PORT
VALUE_LIST = ('api.tembo.io:443');
CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION tembo_api_access_integration
ALLOWED_NETWORK_RULES = (tembo_api_network_rule)
ALLOWED_AUTHENTICATION_SECRETS = (tembo_api_token)
ENABLED = TRUE;
```
The external access integration binds the network rule and the secret together so the UDF can use both.
***
## Step 3: Create the Python UDF that Calls Tembo
This UDF is the dispatch layer — each tool name maps to a Tembo REST endpoint.
```sql theme={null}
CREATE OR REPLACE FUNCTION tembo_call(tool STRING, args VARIANT)
RETURNS VARIANT
LANGUAGE PYTHON
RUNTIME_VERSION = '3.11'
HANDLER = 'handler'
EXTERNAL_ACCESS_INTEGRATIONS = (tembo_api_access_integration)
SECRETS = ('token' = tembo_api_token)
PACKAGES = ('requests')
AS $$
import _snowflake, json, requests
BASE = "https://api.tembo.io"
ROUTES = {
"list_sessions": ("GET", "/session/list"),
"search_sessions": ("GET", "/session/search"),
"list_repositories": ("GET", "/repository/list"),
"create_session": ("POST", "/session/create"),
"trigger_agent": ("POST", "/agent/{keyOrId}/trigger"),
}
def handler(tool, args):
if tool not in ROUTES:
return {"error": f"unknown tool: {tool}"}
method, path_template = ROUTES[tool]
args = dict(args or {})
if "{keyOrId}" in path_template:
key_or_id = args.pop("keyOrId", None)
if not key_or_id:
return {"error": "missing required arg: keyOrId"}
path = path_template.replace("{keyOrId}", key_or_id)
else:
path = path_template
token = _snowflake.get_generic_secret_string("token")
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
}
if method == "GET":
r = requests.get(BASE + path, headers=headers, params=args, timeout=30)
else:
r = requests.post(BASE + path, headers=headers, data=json.dumps(args), timeout=30)
try:
return r.json()
except Exception:
return {"status": r.status_code, "body": r.text}
$$;
```
Smoke-test the UDF before continuing: `SELECT tembo_call('list_repositories', OBJECT_CONSTRUCT());`. You should get back the JSON list of repos enabled in your Tembo org.
***
## Step 4: Create the Snowflake-Managed MCP Server
Expose each route as a named `GENERIC` tool. `input_constants` pins the first UDF argument per tool so the agent only has to supply the `args` VARIANT.
```sql theme={null}
CREATE OR REPLACE MCP SERVER tembo_mcp_server
FROM SPECIFICATION $$
tools:
- name: "list_sessions"
type: "GENERIC"
identifier: "..tembo_call"
description: "List recent Tembo sessions for the current organization."
title: "List Tembo Sessions"
input_constants:
tool: "list_sessions"
- name: "search_sessions"
type: "GENERIC"
identifier: "..tembo_call"
description: "Search Tembo sessions by query string. Pass { q: '' } in args."
title: "Search Tembo Sessions"
input_constants:
tool: "search_sessions"
- name: "list_repositories"
type: "GENERIC"
identifier: "..tembo_call"
description: "List repositories enabled for Tembo in this organization."
title: "List Tembo Repos"
input_constants:
tool: "list_repositories"
- name: "create_session"
type: "GENERIC"
identifier: "..tembo_call"
description: "Start a new Tembo background session. Pass the issue URL or prompt in args."
title: "Create Tembo Session"
input_constants:
tool: "create_session"
- name: "trigger_agent"
type: "GENERIC"
identifier: "..tembo_call"
description: "Trigger a Tembo agent. Pass { keyOrId: '', ...payload } in args."
title: "Trigger Tembo Agent"
input_constants:
tool: "trigger_agent"
$$;
```
Replace `.` with the database and schema where you created `tembo_call`.
***
## Step 5: Attach the MCP Server to a Cortex Agent
```sql theme={null}
CREATE OR REPLACE AGENT my_tembo_agent
WITH PROFILE = $$
{
"display_name": "Tembo Assistant"
}
$$
COMMENT = 'Chat with Tembo from inside Snowflake'
FROM SPECIFICATION $$
instructions:
orchestration: "When the user asks about Tembo sessions, repos, or agents, use the Tembo MCP tools."
mcp_servers:
- server_spec:
name: "..tembo_mcp_server"
$$;
```
If the agent already exists, use `ALTER AGENT ... MODIFY LIVE VERSION SET SPECIFICATION` instead of `CREATE OR REPLACE AGENT`.
***
## Step 6: Grant Access
Grant the role(s) that will use the agent access to the external access integration, the MCP server, the UDF, and the agent itself:
```sql theme={null}
GRANT USAGE ON INTEGRATION tembo_api_access_integration TO ROLE ;
GRANT USAGE ON MCP SERVER tembo_mcp_server TO ROLE ;
GRANT USAGE ON FUNCTION tembo_call(STRING, VARIANT) TO ROLE ;
GRANT USAGE ON AGENT my_tembo_agent TO ROLE ;
```
Anyone with `USAGE` on `tembo_api_access_integration` can call the Tembo API as your token. Scope this role narrowly.
***
## Step 7: Chat with Tembo from Snowflake Intelligence
1. In Snowsight, open **AI & ML → Snowflake Intelligence**
2. Pick **Tembo Assistant**
3. Try one of:
* *"Show me my five most recent Tembo sessions."*
* *"Which repositories are enabled for Tembo?"*
* *"Trigger the Tembo agent `daily-triage` with `{ priority: 'high' }`."*
The agent calls `tools/list` against `tembo_mcp_server`, picks the right `GENERIC` tool, which routes through `tembo_call` → Tembo REST API → response.
***
## Troubleshooting
### `tools/list` returns nothing
**Symptom:** The agent doesn't know about any Tembo tools.
**Cause:** The role used by the chat session lacks `USAGE` on the MCP server, or the server was created in a different schema than the one the agent resolves to.
**Fix:** Confirm the server exists and the grant is in place:
```sql theme={null}
SHOW MCP SERVERS IN SCHEMA .;
GRANT USAGE ON MCP SERVER tembo_mcp_server TO ROLE ;
```
### UDF returns 401 or 403
**Symptom:** Tools execute but return `{ "status": 401, ... }` or `{ "status": 403, ... }`.
**Cause:** The secret is wrong or expired, or the executing role lacks `USAGE` on `tembo_api_access_integration`.
**Fix:** Smoke-test the UDF directly:
```sql theme={null}
SELECT tembo_call('list_repositories', OBJECT_CONSTRUCT());
```
If that errors, rotate the Tembo token, update the secret with `ALTER SECRET tembo_api_token SET SECRET_STRING = ''`, and grant `USAGE` on the access integration to the role.
### Agent doesn't pick a Tembo tool when asked
**Symptom:** The agent answers from general knowledge instead of calling a tool.
**Cause:** Tool descriptions are too vague. Cortex Agents route on tool descriptions, and ambiguous ones get skipped.
**Fix:** Tighten each tool's `description` to mention Tembo explicitly and what the tool returns. Re-run the `CREATE OR REPLACE MCP SERVER` block with sharper descriptions.
### `EXTERNAL ACCESS INTEGRATION` egress blocked
**Symptom:** UDF errors with a network-related exception.
**Cause:** The network rule or the access integration is missing, disabled, or doesn't include `api.tembo.io:443`.
**Fix:** Confirm both objects exist and are enabled:
```sql theme={null}
SHOW NETWORK RULES LIKE 'tembo_api_network_rule';
SHOW EXTERNAL ACCESS INTEGRATIONS LIKE 'tembo_api_access_integration';
```
***
## Advanced
Snowflake also supports `CREATE EXTERNAL MCP SERVER`, which is the cleaner long-term shape because it lets Snowflake speak MCP directly to the remote server with OAuth2 auth.
Today the Tembo MCP server authenticates with a bearer token, and `CREATE EXTERNAL MCP SERVER` requires `API_USER_AUTHENTICATION` with `TYPE = OAUTH2`. Until the Tembo MCP exposes an OAuth2 endpoint, this path requires you to operate an OAuth2-fronting shim that forwards to the Tembo MCP.
For reference, the SQL looks like:
```sql theme={null}
CREATE OR REPLACE API INTEGRATION tembo_mcp_api_integration
API_PROVIDER = external_mcp
API_ALLOWED_PREFIXES = ('https://api.tembo.io/public-api/mcp')
API_USER_AUTHENTICATION = (
TYPE = OAUTH2
OAUTH_CLIENT_ID = ''
OAUTH_CLIENT_SECRET = ''
OAUTH_AUTHORIZATION_ENDPOINT = '/authorize'
OAUTH_TOKEN_ENDPOINT = '/token'
OAUTH_CLIENT_AUTH_METHOD = CLIENT_SECRET_BASIC
OAUTH_REFRESH_TOKEN_VALIDITY = 86400
)
ENABLED = TRUE;
CREATE EXTERNAL MCP SERVER tembo_mcp_server
WITH DISPLAY_NAME = 'Tembo'
API_INTEGRATION = tembo_mcp_api_integration;
```
When the Tembo MCP gains native OAuth2 support this section will become the recommended path.
To add a new tool, add an entry to `ROUTES` in the Python UDF and a matching entry to the `tools:` list in the MCP server specification. Re-run both `CREATE OR REPLACE` statements; the agent picks up the new tool on its next request.
For self-hosted Tembo, replace `https://api.tembo.io` with your deployment's base URL in both the network rule (`VALUE_LIST`) and the Python UDF (`BASE`). The rest of the flow is identical.
Generate a new token in Tembo, then update the secret in place:
```sql theme={null}
ALTER SECRET tembo_api_token SET SECRET_STRING = '';
```
No other objects need to change — the UDF reads the secret fresh on every invocation.
***
## References
* Snowflake — [Cortex Agents MCP](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp)
* Snowflake — [Cortex Agents MCP Connectors](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp-connectors)
* Tembo — [MCP integration](/integrations/mcp)
* Tembo — [Public API reference](/api)
# Snyk
Source: https://docs.tembo.io/integrations/snyk
Vulnerability scanning and auto-fix PRs for your dependencies.
## Features
* Scan repositories for known vulnerabilities in dependencies (Snyk Open Source)
* Surface Snyk-detected issues to Tembo agents during sessions
* Open PRs that bump vulnerable packages to fixed versions
## Installation
In the Tembo app, go to **Settings → Integrations**.
Scroll to the **Monitoring** group and click **Install** next to Snyk.
Sign in with your organization email using an approved auth method.
If you don't have a Snyk account yet, you'll be guided through Snyk's account setup after the initial sign-in. Once your account is ready, return to **Settings → Integrations** in Tembo and click **Install** again to complete the connection.
If you're already signed in to Snyk, click **Authorize** and confirm you've selected the correct Snyk organization before continuing.
Snyk will request access to your organization. Click **Authorize**.
The install must be authorized by a **Snyk organization admin**. If you're not an admin on the Snyk org, ask one to complete this step for you.
After authorizing, you'll be redirected to the Tembo Integrations page. Snyk will switch from uninstalled to installed.
## Usage
Once installed, Tembo monitors your Snyk-connected repositories for known vulnerabilities and opens fix PRs that bump affected dependencies to safe versions. Tembo agents can reference Snyk-detected issues during sessions to inform the changes they propose.
## Advanced
The integration connects to a single Snyk **organization**, not a Snyk user. All scanning and issue access happens within that org. To monitor projects across multiple Snyk orgs, install the integration once per org.
Tembo's Snyk integration grants both read and write access to your connected Snyk organization, including the ability to create, edit, and delete ignore rules (which suppress vulnerability findings). **Read and review this list before installing** to be sure what information and data you are sharing.
At install time, Tembo's Snyk App requests the following 11 OAuth scopes on your Snyk organization:
**Read access**
* `org.read` — your Snyk organization's metadata (name, slug, settings)
* `org.project.read` — the list of projects in your org and their details
* `org.project.snapshot.read` — historical scan snapshots (vulnerability findings over time)
* `org.report.read` — org-level reports (aggregated vulnerability and compliance data)
* `org.project.ignore.read` — which vulnerabilities you've configured Snyk to ignore
**Write access**
* `org.project.test` — trigger Snyk to re-test (re-scan) a project on demand
* `org.project.attributes.edit` — edit project attributes (e.g., business criticality, environment, lifecycle)
* `org.project.tag.edit` — add, modify, or remove tags on projects
* `org.project.ignore.create` — create new ignore rules (suppress specific vulnerability findings)
* `org.project.ignore.edit` — modify existing ignore rules
* `org.project.ignore.delete` — delete ignore rules
Tembo cannot modify Snyk organization membership, change billing settings, or create or delete Snyk projects.
If you're redirected back to Tembo but the integration still shows as uninstalled, the most common cause is the OAuth flow being cancelled or rejected on Snyk's side. Try the install again and make sure you click **Authorize** on the Snyk consent screen.
# Stripe
Source: https://docs.tembo.io/integrations/stripe
Payments, billing, and customer operations via Stripe MCP.
## Features
* Read/write access to your connected Stripe account through the Stripe MCP server
* Coverage across accounts, customers, products, pricing, payments, invoicing, subscriptions, payment links, and disputes
* Search and lookup any Stripe object by ID or query syntax
* Generic Stripe API escape hatch — execute any Stripe API call
* Built-in Stripe documentation search and integration recommender
## Installation
In the Tembo app, go to **Settings → Integrations**.
Scroll to the **Business Operations** group and click **Install** next to Stripe.
Sign in with your organization email using an approved auth method.
If you don't have a Stripe account yet, you'll be guided through business setup with Stripe. After creating the account, return to **Settings → Integrations** in Tembo and click **Install** again to complete the connection.
Stripe will request information from your account. Click **Authorize**.
If you see **"Enable MCP Access"** below your account name, [MCP access must be enabled on the Stripe account](https://docs.stripe.com/mcp?mcp-client=other#access) before the integration will work. Enable it as a Stripe administrator, or ask an admin to enable it for you.
After authorizing, you'll be redirected to the Tembo Integrations page. Stripe will switch from uninstalled to installed.
## Usage
Once installed, Tembo agents automatically have access to the Stripe MCP server during sessions. No further configuration is needed inside Tembo — agents can read account data, manage customers and products, query payments and invoices, and call any Stripe API operation on your behalf.
## Advanced
When connected, a Stripe MCP server is automatically available to agents. They can query account info, search customers and charges, manage products and subscriptions, handle disputes, and fall back to the generic Stripe API for anything not covered by a dedicated tool.
If MCP access is not enabled on the Stripe account, the integration will not function. This is a Stripe-side setting and is admin-only. See [Stripe's MCP access documentation](https://docs.stripe.com/mcp?mcp-client=other#access).
If you created a new Stripe business during the install flow, the install state in Tembo may not auto-complete. Return to **Settings → Integrations** in Tembo and click **Install** again to finish the connection.
# Supabase
Source: https://docs.tembo.io/integrations/supabase
Database performance monitoring and optimization.
## Features
* Monitor slow queries and suggest optimizations
* Detect missing and unused indexes
* Open PRs with migration scripts
## Installation
Go to [Integrations](https://app.tembo.io/integrations) and click **Install** next to Supabase.
Authorize Tembo to access your Supabase account.
Select which Supabase projects to monitor.
Map projects to the repository where migrations are stored.
## Usage
Tembo monitors your Supabase database using `pg_stat_statements`. When it finds optimization opportunities, it opens PRs with migration scripts and performance metrics.
## Advanced
Wait 2-5 minutes for initial sync. Verify you authorized access and projects are active (not paused). Try the sync button.
Verify `pg_stat_statements` is active. Generate some query traffic and wait 24-48 hours for new projects to collect data.
# Tailscale
Source: https://docs.tembo.io/integrations/tailscale
Connect Tembo sandbox sessions to your private network (tailnet) with on-demand, single-use ephemeral keys.
## Overview
The Tailscale integration lets Tembo agent sessions join your
[tailnet](https://tailscale.com/kb/1136/tailnet) so they can reach private
resources — internal databases, staging hosts, admin APIs — that aren't
exposed to the public internet.
It is designed to be safe by default:
* **Opt-in per task** — sessions never join your tailnet automatically. An
agent connects only when a task needs private-network access, using the
managed `/tailscale` skill the integration installs.
* **Single-use, ephemeral keys** — each join uses a short-lived, single-use
auth key minted on demand. Your Tailscale OAuth credentials never enter a
sandbox, and ephemeral nodes remove themselves from your tailnet when the
session ends.
* **Your ACLs decide access** — a joined session is just a tagged device on
your tailnet. What it can reach is governed entirely by your Tailscale ACL
policy for the tag you assign. No inbound access to the session is required
or expected.
* **Unprivileged** — inside the sandbox, Tailscale runs in userspace
networking mode with no root access and no kernel networking changes.
## Prerequisites
You need admin access to your Tailscale organization to complete the setup:
Sessions join your tailnet as tagged devices. We recommend a dedicated
tag such as `tag:tembo-session` so you can scope access rules to Tembo
sessions only.
In the [Tailscale admin console](https://login.tailscale.com/admin/acls),
declare the tag in `tagOwners`:
```jsonc theme={null}
"tagOwners": {
"tag:tembo-session": [],
},
```
Add ACL rules for what Tembo sessions may reach. This is entirely your
choice — start narrow. For example, to allow sessions to reach a staging
database subnet and hosts tagged `tag:staging`:
```jsonc theme={null}
"acls": [
{
"action": "accept",
"src": ["tag:tembo-session"],
"dst": ["tag:staging:*", "10.20.0.0/16:5432"],
},
],
```
If you want agents to SSH into hosts via
[Tailscale SSH](https://tailscale.com/kb/1193/tailscale-ssh), add an
`ssh` rule as well:
```jsonc theme={null}
"ssh": [
{
"action": "accept",
"src": ["tag:tembo-session"],
"dst": ["tag:staging"],
"users": ["ubuntu"],
},
],
```
In [**Settings → Trust credentials**](https://console.tailscale.com/admin/settings/trust-credentials),
click **+ Credential**, select **OAuth**, and continue. Under **Keys →
Auth keys**, select the **Write** scope — read access is not enough,
because Tembo has to create keys. Then assign the client the tag you
created (`tag:tembo-session`). Tembo uses this client to mint short-lived
auth keys — it can only create keys for the tags it owns.
Copy the **client ID** and **client secret**; you'll enter them in Tembo
next.
## Installation
In the Tembo app, go to **Settings → Integrations**.
Find **Tailscale** in the **Developer Tools** group and click
**Install**.
Fill in a connection name, the OAuth **client ID** and **client secret**,
and the device tag(s) sessions should advertise (for example
`tag:tembo-session`).
Tembo validates the credentials against the Tailscale API before saving
— if the client ID or secret is wrong, you'll see an error immediately.
Installing the integration also creates a managed **`/tailscale`** skill for
your organization. This skill teaches agents how to join the tailnet and how
to reach hosts through it; you don't need to configure anything else.
## Usage
Ask an agent to do something that requires your private network, and mention
the tailnet or Tailscale if you want to be explicit:
* "Use tailscale to query the staging database and summarize yesterday's failed jobs."
* "SSH into the metrics host on our tailnet and check disk usage."
* "Hit the internal admin API and pull the feature-flag config."
The agent invokes the `/tailscale` skill, requests a one-time key from the
Tembo API, joins your tailnet as `tembo-session-`, and does the
work. Sessions appear in your Tailscale admin console as tagged devices
while active and remove themselves when the session ends.
## Advanced
* Your OAuth client credentials are stored encrypted with the integration
and used only server-side by the Tembo API. They are never sent to a
sandbox.
* When a session joins, the Tembo API mints a **single-use, ephemeral,
pre-authorized** auth key restricted to your configured tags, with an
expiry of minutes. That key is the only credential the sandbox ever
sees.
* Sessions are outbound-only participants on your tailnet. Nothing on
your tailnet needs to (or should) connect into a session.
* Removing the integration deletes the managed skill; you can also revoke
the OAuth client in Tailscale at any time to cut off all key minting.
Sandboxes run `tailscaled` in userspace networking mode (no root, no TUN
device). Traffic to your tailnet flows through Tailscale's encrypted
WireGuard tunnel, typically relayed over HTTPS (DERP) since sandboxes
don't accept inbound UDP. Agents reach your hosts via Tailscale SSH, a
local SOCKS5/HTTP proxy, or TCP tunneling — the managed skill covers all
of this so agents handle it automatically.
You can list multiple tags when installing (all must be owned by the
OAuth client). The integration connects to the OAuth client's tailnet;
to serve multiple tailnets, install the integration once per tailnet.
* **Install fails with "Invalid Tailscale credentials"** — the client ID
or secret is wrong, or the OAuth client lacks the **Keys → Auth keys**
**Write** scope.
* **Agent reports `requested tags are invalid or not permitted`** — the
tag you configured in Tembo isn't assigned to the OAuth client in
Tailscale (check both `tagOwners` and the client's tag assignment).
* **Agent reports connections to a host time out** — your ACL policy
doesn't allow `tag:tembo-session` to reach that host and port. This is
Tailscale working as intended; extend your ACLs if the access is
wanted.
* **A skill named `tailscale` already exists** — the integration installs
a managed `/tailscale` skill and won't overwrite a skill you authored
with the same name. Rename or delete yours and install again.
# Microsoft Teams
Source: https://docs.tembo.io/integrations/teams
Trigger sessions by mentioning @Tembo in any Microsoft Teams chat or channel.
Tembo for Microsoft Teams is currently in **sideload pilot**. The app is not yet published to the Microsoft Teams Store — partner organizations install it directly via a `.zip` package. A full marketplace listing is in progress.
## Features
* Create sessions by mentioning `@Tembo` in any chat or channel
* Specify repos, branches, and agents inline
* Thread context is automatically read
* PR notifications posted back to the originating Microsoft Teams thread
* Works in personal chats, group chats, and team channels
## Installation
The Microsoft Teams integration is currently available on a limited basis. To get started, [please reach out to the team at Tembo.io](https://book.avoma.com/tembo/tembo-demo/) to schedule setup for your organization.
## Usage
### Basic
```
@Tembo Fix the authentication bug in the login flow
```
### With options
```
@Tembo In owner/webapp on branch dev, add password strength validation
```
**You can specify:** repository, branch, and agent in plain text (for example: `owner/webapp`, `branch dev`, `agent gpt-5.4`).
### Multiple repositories
```
@Tembo Add user authentication in owner/frontend and owner/backend
```
Tembo creates separate PRs for each repo and coordinates changes.
### Thread context
Mention `@Tembo` in a thread reply and it reads the full conversation history for context.
### Iterate in Microsoft Teams
After Tembo opens a PR, you can keep mentioning `@Tembo` in the same Microsoft Teams thread to give feedback and iterate. No need to leave comments on the PR itself.
### Help
```
@Tembo help
```
Shows the available commands and supported options.
## Agents
See [Agents](/features/agents) for available Microsoft Teams event triggers.
## Supported environments
| Cloud | Supported |
| ------------------------ | --------- |
| Microsoft 365 Commercial | Yes |
| GCC | Yes |
| GCC High | No |
| DoD | No |
| 21Vianet (China) | No |
## Advanced
Verify the app is installed in your Microsoft Teams scope (personal / team / chat). If you installed it for **personal** only and are trying to use it in a team channel, install it again with the **team** scope.
Also confirm the bot is allowed in your channel — some org policies restrict bot interactions in specific channels.
Your Microsoft Teams admin has not enabled custom app uploads for your tenant. Send them the link to the [Microsoft Teams admin center setup policies](https://admin.teams.microsoft.com/policies/manage-app-setup-policies) and ask them to enable **Upload custom apps** on your setup policy. Changes may take up to 24 hours to take effect.
Also be sure to check that the button is toggled to 'on' in your settings once it is located by your admin.
Set a default repository in your Tembo workspace settings, or specify the repository directly in your message (for example: `owner/repo`).
When a new version of the Tembo Microsoft Teams package is released, download the latest `.zip` and repeat the upload steps. Microsoft Teams will detect it as an update rather than a new install as long as the app ID is unchanged.
Tembo for Microsoft Teams is not currently certified for GCC High, DoD, or 21Vianet clouds. If your organization needs Tembo in one of these environments, [contact us](https://tembo.io/contact).
# Fix bugs
Source: https://docs.tembo.io/learn/fix-production-bugs
Detect errors from Sentry, analyze the root cause, and open fix PRs automatically.
Tembo monitors your error tracking tools and automatically generates [pull requests](/features/pull-requests) to fix bugs as they happen in production.
## How it works
Sentry captures an error in your application and sends a webhook to Tembo.
Tembo retrieves the full error context (stack traces, breadcrumbs, environment details) and analyzes your codebase to understand the root cause.
A coding agent writes the fix in an isolated [sandbox](/features/sandbox/overview), runs tests, and opens a PR with the change and full context.
You review the PR and use the [feedback loop](/features/feedback-loop) to iterate if needed. Merge when ready.
## Set up automatic bug fixes
### 1. Connect Sentry
Navigate to the [Integrations page](https://app.tembo.io/integrations) and connect your Sentry account. Map your Sentry projects to the repositories where errors occur.
See the full [Sentry integration guide](/integrations/sentry) for details.
### 2. Create an agent
Go to **Agents** in your dashboard and create a new agent with a Sentry event trigger.
**Trigger**: `sentry.issue.created` or `sentry.issue.regression`
**[MCP Servers](/integrations/mcp)**: GitHub + Sentry
Example instructions:
```text theme={null}
When a new Sentry error is detected:
1. Retrieve the full stack trace and error context
2. Identify the root cause in the codebase
3. Write a fix and add tests
4. Open a PR with a clear description of what went wrong and how it's fixed
```
Use the **Auto Fix Sentry Errors** template to automatically diagnose new errors, identify the root cause, and open a fix PR.
### 3. Fine-tune with rule files
Add [rule files](/features/rule-files) to your repo so the agent follows your coding standards, test patterns, and PR conventions when generating fixes.
## Best practices
* **Map projects accurately**: Connect [Sentry](/integrations/sentry) projects to the correct repos, especially for monorepos.
* **Enable rich context**: Turn on source maps, breadcrumbs, and custom tags in Sentry so the agent has more to work with.
* **Review before merging**: Always review the PR. Use the [feedback loop](/features/feedback-loop) to refine the fix.
* **Test in staging first**: Validate fixes in a staging environment before merging to production.
# Implement issues
Source: https://docs.tembo.io/learn/implement-from-issues
Assign issues from Linear, Jira, or GitHub and get code written for you.
Tembo picks up issues from your project management tools and writes code to solve them, whether it's a bug, a feature, or a refactor.
## How it works
Create or assign an issue in [Linear](/integrations/linear), [Jira](/integrations/jira), [GitHub](/integrations/github), or mention it in [Slack](/integrations/slack). Tembo picks it up via webhook or [agent](/features/agents) trigger.
Tembo reads the issue description, pulls in related code, linked docs, and conversation history to understand the full picture.
A [agent harness](/features/agents#agent-harness) works in an isolated [sandbox](/features/sandbox/overview), implements the solution, and opens a [PR](/features/pull-requests) linked back to the original issue.
Review the PR. Use the [feedback loop](/features/feedback-loop) to request changes. The agent iterates until the solution is right.
## Set up issue-to-PR workflows
### Connect your issue tracker
Navigate to the [Integrations page](https://app.tembo.io/integrations) and connect one or more of:
* [Linear](/integrations/linear)
* [Jira](/integrations/jira)
* [GitHub Issues](/integrations/github)
* [Slack](/integrations/slack)
* [Notion](/integrations/notion)
### Create an agent
**Trigger**: Issue created, issue assigned, or label added
**[MCP Servers](/integrations/mcp)**: GitHub + your issue tracker
Example instructions:
```text theme={null}
When a new issue is assigned to Tembo:
1. Read the issue description and any linked context
2. Identify the relevant files in the codebase
3. Implement the solution following our coding standards
4. Write tests for the changes
5. Open a PR and link it to the original issue
```
## Your team stays in control
Tembo generates solutions autonomously, but your team decides what gets deployed:
* Review PRs using your standard review process
* Mention `@tembo` in PR comments to request changes. It iterates on the feedback
* Approve and merge when you're satisfied
## Best practices
* **Write clear issue descriptions**: The more context in the issue, the better the implementation.
* **Use labels**: Trigger [agents](/features/agents) only on specific labels (e.g., `tembo`, `auto-implement`) to control which issues get picked up.
* **Start with small sessions**: Begin with well-scoped bugs and small features before tackling larger work.
# Update docs
Source: https://docs.tembo.io/learn/keep-docs-in-sync
Keep documentation in sync with your codebase as code changes.
Tembo monitors your codebase for changes and automatically updates your documentation repo to keep features well-documented.
## How it works
A PR is merged or code is pushed to your main branch. Tembo detects the change via webhook.
The agent compares the code changes against your existing documentation to identify gaps, outdated sections, or missing pages.
A [PR](/features/pull-requests) is opened in your docs repo with updated content that reflects the code changes.
## Set up a docs agent
### On PR merge
**Trigger**: PR merged to main
**[MCP Servers](/integrations/mcp)**: [GitHub](/integrations/github)
```text theme={null}
When a PR is merged:
1. Analyze the changes for user-facing impact
2. Check if existing docs cover the changed functionality
3. If docs are outdated or missing, open a PR in the docs repo with updates
4. Match the existing docs style and formatting
```
### Weekly docs review
**Trigger**: Weekly
**[MCP Servers](/integrations/mcp)**: [GitHub](/integrations/github), [Notion](/integrations/notion), [Slack](/integrations/slack)
```text theme={null}
Compare the codebase against the docs repo:
1. Find new features or API changes that aren't documented
2. Identify docs pages that reference removed or renamed functionality
3. Open a PR with updates for the most impactful gaps
4. Post a summary to #engineering in Slack
```
## Best practices
* **Use a separate docs repo**: Tembo can open PRs across repositories, so keep docs in their own repo for clean separation.
* **Add [rule files](/features/rule-files)**: Include a rule file in your docs repo with style guidelines, formatting conventions, and tone.
* **Start with API docs**: API documentation is the easiest to keep in sync since changes are mechanical and well-scoped.
# Reduce tech debt
Source: https://docs.tembo.io/learn/reduce-technical-debt
Scan for vulnerabilities, stale TODOs, and refactoring opportunities on a schedule.
Tembo periodically analyzes your codebase to find technical debt, security vulnerabilities, and refactoring opportunities, then submits [PRs](/features/pull-requests) for quick wins.
## How it works
An [agent](/features/agents) runs on a schedule (daily, weekly, or monthly) and scans your codebase for issues.
The agent finds stale TODOs, security vulnerabilities, outdated dependencies, duplicated code, and other debt.
For quick wins, the agent opens PRs with fixes. For larger issues, it creates tickets in [Linear](/integrations/linear) or [Jira](/integrations/jira) with implementation plans.
## Set up a tech debt agent
### Security vulnerability scan
**Trigger**: Daily or weekly
**[MCP Servers](/integrations/mcp)**: [GitHub](/integrations/github), [Linear](/integrations/linear)
```text theme={null}
Scan the codebase for:
- SQL injection vulnerabilities
- XSS vulnerabilities
- Hardcoded secrets or credentials
- Authentication and authorization flaws
Create Linear tickets for each finding with severity ratings.
Generate fix PRs for critical issues.
```
[Browse all templates →](https://tembo.io/for)
### Stale TODO cleanup
**Trigger**: Weekly
**[MCP Servers](/integrations/mcp)**: [GitHub](/integrations/github)
```text theme={null}
Find all TODO, FIXME, and HACK comments in the codebase.
For each one that's older than 30 days:
1. Determine if it's still relevant
2. If it's a quick fix, open a PR to resolve it
3. If it needs discussion, create an issue
```
### Dependency updates
**Trigger**: Monthly
**[MCP Servers](/integrations/mcp)**: [GitHub](/integrations/github)
```text theme={null}
Check for outdated dependencies.
For each outdated package:
1. Check the changelog for breaking changes
2. Update the dependency
3. Run tests to verify compatibility
4. Open a PR with a summary of changes
```
## Best practices
* **Start weekly**: Run scans weekly to build a habit of reviewing and merging debt-reduction PRs.
* **Prioritize security**: Set security scans to run more frequently than cosmetic cleanup.
* **Scope by directory**: Focus on one area of your codebase at a time rather than scanning everything at once.
# Review changes
Source: https://docs.tembo.io/learn/review-changes
Get automated code reviews on every PR with inline comments.
Tembo reviews [pull requests](/features/pull-requests) automatically, checking for bugs, security issues, and style guide compliance, then leaving inline comments on specific lines.
## How it works
A pull request is opened or updated in your repository. Tembo picks it up via webhook.
The agent reads the diff, understands the context of the changes, and evaluates them against your coding standards.
Inline comments are added to specific lines in the PR. If no issues are found, the PR can be auto-approved.
## Set up automated PR reviews
### 1. Connect your source control
Navigate to the [Integrations page](https://app.tembo.io/integrations) and connect [GitHub](/integrations/github), [GitLab](/integrations/gitlab), or [Bitbucket](/integrations/bitbucket).
### 2. Create an agent
Go to [Agents](/features/agents) in your dashboard and use the **PR Review** template, or create one from scratch.
**Trigger**: PR opened / PR updated (webhook from [GitHub](/integrations/github), [GitLab](/integrations/gitlab), or [Bitbucket](/integrations/bitbucket))
Example instructions:
```text theme={null}
Review this PR for:
- Bugs and logic errors
- Security vulnerabilities
- Performance issues
- Style guide compliance
Leave inline comments on specific lines.
Auto-approve if no issues found.
```
[Browse all templates →](https://tembo.io/for)
### 3. Customize with rule files
Add [rule files](/features/rule-files) to your repo so the reviewer knows your team's conventions: naming patterns, test requirements, forbidden patterns, and more.
## What gets checked (depends on your instructions)
| Category | Examples |
| --------------- | ----------------------------------------------------- |
| **Correctness** | Logic errors, off-by-one bugs, null handling |
| **Security** | SQL injection, XSS, hardcoded secrets |
| **Performance** | N+1 queries, unnecessary allocations, missing indexes |
| **Style** | Naming conventions, formatting, import order |
| **Testing** | Missing tests, untested edge cases |
## Best practices
* **Add [rule files](/features/rule-files)**: The more context the reviewer has about your standards, the better the review.
* **Start with one repo**: Test the review quality on a single repo before rolling out to all.
* **Combine with human review**: Use automated reviews to catch the obvious stuff so human reviewers can focus on architecture and design.
# Quickstart
Source: https://docs.tembo.io/quickstart
Get up and running with Tembo in minutes.
Go to [Integrations](https://app.tembo.io/integrations) and connect GitHub, GitLab, or Bitbucket. Select the repositories you want Tembo to access.
Open the [Tembo Dashboard](https://app.tembo.io) and click **New Session**. Pick one or more repositories, choose your [agent harness](/features/agents#agent-harness), and describe the work. Tembo can also use connected integrations and [MCP servers](/integrations/mcp) for extra context during the session.
Tembo works in a [sandbox](/features/sandbox/overview), writes the code, and opens a pull request. Review it, then mention `@tembo` in PR comments to request changes.
Go to [Agents](https://app.tembo.io/agents) and pick a template or create your own with custom triggers and schedules. See [Agents](/features/agents).
***
## Where to tag @tembo
**Tag required:** PR comments, GitHub issues, Slack messages.
**No tag needed:** Dashboard sessions, Linear/Jira issues assigned to Tembo.
## Writing good prompts
Include: **what** needs to change, **where** (file paths), **why**, and **how you'll know it's done**.
```text theme={null}
Fix memory leak in workers/job-processor.ts
Heap grows from 512MB to 4GB and crashes after ~6 hours.
Likely in cleanup logic around line 156. See Sentry #12345.
Done when: memory stable over 24+ hours, no queued jobs lost.
```
**Avoid:** "Fix the bug", "Make it faster", "Update the app and add new features". Be specific, scope to one session, and include acceptance criteria.
| Type | What to include |
| ------------ | ------------------------------------------------------------------- |
| **Bug** | Steps to reproduce, expected vs actual, error messages, Sentry link |
| **Feature** | Requirements, file locations, edge cases, dependencies |
| **Refactor** | Current problems, desired state, constraints, specific files |
## Next steps
Choose the right harness and model.
Define coding standards for agents to follow.
# Pricing
Source: https://docs.tembo.io/resources/pricing
Understand Tembo plans, model and compute rates, usage allowances, prepaid balance, and overages.
Tembo gives your workspace a dollar-denominated usage allowance. Tembo Gateway usage and cloud VM compute draw from the same balance.
## Plans
* **Free**: \$10 one-time usage allowance, up to 3 users, sandbox size up to `micro`
* **Pro (\$60/month)**: \$60 monthly usage allowance, up to 5 users, sandbox size up to `medium`, with overage billing
* **Max (\$200/month)**: \$200 monthly usage allowance, up to 10 users, sandbox size up to `xl`, with overage billing
Pro and Max can use overage billing so your work can continue after you use your monthly allowance and prepaid balance. You can set a maximum overage limit to control spend. On Free, new sessions are blocked when the allowance and prepaid balance are exhausted until you upgrade or add funds.
Standard BYOK (Anthropic, OpenAI), agent keys (Amp, Cursor), and ChatGPT/Codex OAuth subscription access are available on every plan, including Free. Cloud BYOK (AWS Bedrock, GCP Vertex AI) requires Pro, Max, or Enterprise.
## How the usage allowance works
Two usage categories draw from the same balance:
* **Tembo Gateway**: model input, output, and cache usage is charged at the rates in [Tembo Gateway pricing](#tembo-gateway-pricing).
* **Cloud VM compute**: metered from the CPU, memory, and runtime used by each session.
BYOK and ChatGPT/Codex OAuth inference cost \$0 through Tembo because you provide the model access. The cloud VM running the session continues to draw from your usage allowance.
Included monthly allowance expires at the end of each billing cycle and does not roll over. Prepaid balance does not expire.
## Cloud VM compute rates
VM compute is a separate usage category from Tembo Gateway. It draws from the same dollar-denominated allowance at **\$0.0403/vCPU-hour + \$0.0130/GiB-RAM-hour**.
| Resource | Rate |
| -------- | ------------------------: |
| vCPU | \$0.0403 per vCPU-hour |
| Memory | \$0.0130 per GiB RAM-hour |
The per-size hourly prices below apply those resource rates to each VM configuration.
| Size | vCPU | Memory | Price per hour |
| ------ | ---: | ------: | -------------- |
| Nano | 2 | 2 GiB | \$0.1066 |
| Micro | 2 | 4 GiB | \$0.1326 |
| Medium | 4 | 8 GiB | \$0.2652 |
| Large | 8 | 16 GiB | \$0.5304 |
| XL | 16 | 32 GiB | \$1.0608 |
| XXL | 16 | 64 GiB | \$1.4768 |
| Ultra | 32 | 128 GiB | \$2.9536 |
**Don't see the VM size you want?** Larger VM sizes are available upon request. Contact [support@tembo.io](mailto:support@tembo.io) to discuss your requirements.
Tembo measures each running VM in seconds and bills its actual running time at the per-second equivalent of the hourly rate. Stopped, snapshotted, and otherwise non-running VMs do not accrue compute.
See [Sandboxes](/features/sandbox/overview) for more about the execution environment.
## Tembo Gateway pricing
Pricing is shown in USD per 1M tokens.
| Provider | Model | Input | Output | Cache create | Cache read |
| --------- | ------------------------------- | -------: | ------: | -----------: | ---------: |
| Anthropic | `claude-fable-5` | \$11.50 | \$57.50 | \$14.375 | \$1.15 |
| Anthropic | `claude-opus-4-8` | \$5.75 | \$28.75 | n/a | n/a |
| Anthropic | `claude-opus-4-7` | \$5.75 | \$28.75 | \$7.1875 | \$0.575 |
| Anthropic | `claude-opus-4-6` | \$5.75 | \$28.75 | \$7.1875 | \$0.575 |
| Anthropic | `claude-sonnet-4-6` | \$3.45 | \$17.25 | \$4.3125 | \$0.345 |
| Anthropic | `claude-opus-4-5` | \$5.75 | \$28.75 | \$7.1875 | \$0.575 |
| Anthropic | `claude-4-5-haiku` | \$1.15 | \$5.75 | \$1.4375 | \$0.115 |
| OpenAI | `gpt-5.5` | \$5.75 | \$34.50 | n/a | \$0.575 |
| OpenAI | `gpt-5.4` | \$2.875 | \$17.25 | n/a | \$0.2875 |
| OpenAI | `gpt-5.4-mini` | \$0.2875 | \$2.30 | n/a | \$0.02875 |
| OpenAI | `gpt-5.4-nano` | \$0.0575 | \$0.46 | n/a | \$0.00575 |
| OpenAI | `gpt-5.3-codex` | \$2.0125 | \$16.10 | n/a | \$0.20125 |
| OpenAI | `gpt-5.3-codex-spark` | Missing | Missing | Missing | Missing |
| OpenAI | `gpt-5.2-codex` | \$2.0125 | \$16.10 | n/a | \$0.20125 |
| OpenAI | `gpt-5.2` | \$2.0125 | \$16.10 | n/a | \$0.20125 |
| Tembo | `kimi-k3` | \$3.45 | \$17.25 | n/a | \$0.345 |
| Tembo | `kimi-k2p6` | \$0.69 | \$3.45 | n/a | \$0.115 |
| Tembo | `kimi-k2p7-code` | \$1.0925 | \$4.60 | n/a | \$0.2185 |
| Tembo | `glm-5p2` | \$1.61 | \$5.06 | n/a | \$0.299 |
| Tembo | `minimax-m2p7` | \$0.345 | \$1.38 | n/a | \$0.0345 |
| Tembo | `minimax-m3` | \$0.345 | \$1.38 | n/a | \$0.0345 |
| Tembo | `deepseek-v4-pro` | \$2.001 | \$4.002 | n/a | \$0.16675 |
| Tembo | `deepseek-v4-flash` | \$0.161 | \$0.322 | n/a | \$0.0345 |
| Tembo | `nvidia-nemotron-3-ultra-nvfp4` | \$0.69 | \$2.76 | n/a | \$0.138 |
## What consumes the allowance
Tembo Gateway and VM compute are metered while Tembo runs work such as:
* Creating pull requests from assigned issues (Linear, Jira, Slack)
* Fixing production errors from Sentry
* Optimizing database queries and indexes
* Processing pull request feedback through the [Feedback Loop](/features/feedback-loop)
## When the allowance runs out
What happens when your balance reaches zero depends on your plan and overage setting:
* **Free**: new sessions are blocked until you upgrade or add prepaid balance.
* **Pro or Max with overages enabled**: sessions continue and are billed as overage after the included allowance and prepaid balance are used, up to the maximum overage limit you set. Once that limit is reached, new sessions are blocked.
* **Pro or Max with overages disabled**: new sessions are blocked as soon as the included allowance and prepaid balance are exhausted.
When work is blocked, the request is rejected immediately rather than queued. Work that has already started can continue its current session so its compute and inference are accounted for correctly.
## Usage bursts
Some integrations can create a large batch of work at once — for example, a repository or integration sync, or a token refresh that triggers a backlog of issues. Tembo does not cap or rate-limit how much work an integration enqueues; the batch is processed as worker capacity becomes available, and each resulting session records dollar usage when it runs. The same allowance and overage limits above apply, so a burst cannot spend beyond your available balance plus your overage limit. To absorb large bursts without interruption, enable overages with an appropriate limit.
## Usage refunds
Tembo Gateway usage may be refunded automatically in some cases:
* **Failed sessions**: if Tembo cannot complete a session because of an internal error
* **Duplicate issues**: if the same issue is queued more than once
* **Invalid inputs**: if a session fails due to missing access or configuration problems
## Usage and monitoring
You can track Tembo Gateway usage, compute, total usage, VM resource-hours, and daily spend in the [Billing dashboard](https://app.tembo.io/settings/billing). Overage invoices list Tembo Gateway and compute separately.
## Prepaid balance and on-demand usage
* **Free plan**: upgrade to Pro or Max for overages, or add prepaid balance
* **Pro and Max**: enable overage billing and set a monthly spend limit
* **Prepaid balance**: does not expire
To change plans, open [Billing settings](https://app.tembo.io/settings/billing).
## Troubleshooting
**Payment failed**: confirm the card is valid and has available funds.
**Prepaid balance did not appear immediately**: billing updates can take a few minutes.
Need help? Contact [hi@tembo.io](mailto:hi@tembo.io).
## Enterprise pricing
If you need custom pricing, reach out to [support@tembo.io](mailto:support@tembo.io) for:
* Custom usage allowances
* Custom or unlimited sandbox sizing
* Volume pricing
* Custom inference configuration
* Dedicated support
* Flexible billing options
# PWA
Source: https://docs.tembo.io/resources/pwa
Install Tembo as a Progressive Web App for quick access from your home screen.
Install Tembo as a Progressive Web App (PWA) for quick access from your home screen with an app-like experience. PWAs combine the best of web and native apps, giving you instant access without app store downloads.
## Installation
1. Open [app.tembo.io](https://app.tembo.io) in your browser
2. Access the share or install menu (look for an install icon in the address bar or use the browser menu)
3. Select "Add to Home Screen" or "Install" and confirm the installation
Once installed, Tembo appears on your home screen or app launcher just like a native application.
## Benefits
* **Quick access:** Launch directly from your home screen or dock
* **Full-screen mode:** Distraction-free experience without browser UI
* **Offline resilience:** Core functionality remains available with spotty connectivity
* **Push notifications:** Stay updated with important alerts (coming soon)
## Troubleshooting
**Install option not visible?**
* **Chrome Desktop:** Look for the install icon in the address bar (computer with down arrow)
* **Safari iOS:** Tap the Share button at the bottom, then scroll to "Add to Home Screen"
* **Chrome Android:** Tap the three-dot menu and select "Add to Home Screen" or "Install app"
* **Edge:** Tap the three-dot menu, go to "Apps," then select "Install Tembo"
**Supported browsers:** Chrome and Edge on all platforms, Safari on iOS 14.3 and later, Firefox with limited support.
**PWA not updating?** Remove or uninstall the app from your device, clear your browser cache if needed, then reinstall from your browser.
# Support
Source: https://docs.tembo.io/support
Get help with Tembo through in-app chat, email, and dedicated Slack channels.
All customers get access to support through in-app chat and email. Enterprise accounts also get a dedicated Slack channel for direct access to the Tembo team.
## How to reach us
| Channel | Details |
| --------------- | ------------------------------------------------------------ |
| **In-App Chat** | Behind the **Help** button at the bottom of the left sidebar |
| **Email** | [support@tembo.io](mailto:support@tembo.io) |
| **Slack** | Dedicated channel (enterprise plans) |
## Support tiers
Standard – Free and Pro}>
**Channels:** In-app chat, Email
**Hours:** Monday–Friday, 9am–6pm ET
**First Response:** Within 1 business day
Priority – Max, Unlimited, and Annual Agreements}>
**Channels:** In-app chat, Email, Slack
**Hours:** Monday–Friday, 9am–6pm ET
**First Response:** Within 6 business hours
**Extras:** Dedicated Slack channel
+ Premiere – Add-on for Enterprise plans}>
Everything in Priority, plus:
**Channels:** + Video, Phone
**Hours:** 8am-8pm ET for critical issues
**First Response:** Within 1 hour (critical), 4 hours (standard)
**Extras:** Named account manager, quarterly reviews, custom SLA
[Contact sales](mailto:sales@tembo.io) to add Premiere support.
## Response times by severity
| Issue Type | Standard | Priority | Premiere |
| ------------------------------- | --------- | -------- | -------------- |
| **Critical** — Production down | \< 8 hrs | \< 2 hrs | \< 1 hr (24/7) |
| **High** — Major feature broken | \< 1 day | \< 4 hrs | \< 2 hrs |
| **Medium** — Minor issue | \< 2 days | \< 8 hrs | \< 4 hrs |
| **Low** — Question/guidance | \< 3 days | \< 1 day | \< 8 hrs |
*Times shown are targets for first response during business hours unless noted.*
## What's a critical issue?
* Production environment completely unavailable
* Data loss or corruption
* Security vulnerability
* No workaround available
## Upgrade your support
Need faster response times, a named account manager, or 24/7 critical issue coverage? [Contact us](mailto:sales@tembo.io) to learn about Premiere support.