> ## Documentation Index
> Fetch the complete documentation index at: https://trytilde.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Embedding overview

> Put Tilde spaces, agent chats, and connection setup inside your own application, for your application's signed-in users.

Embedding puts Tilde inside your product. Your users see spaces, chat with agents, and connect their own accounts on your pages, signed in with your application's login, not with Tilde.

Two SDK packages do the work:

| Package | Runs in | What it does |
| - | - | - |
| `@trytilde/embed-server` | Your server | Holds your embed key, reads your session to say who the user is, and serves the browser package's requests. |
| `@trytilde/embed` | The browser | Mounts spaces and connection setup, and re-exports the chat components (`@trytilde/embed/react`). |

The browser only talks to your server. Your key never reaches the browser, and the browser can never choose who it is.

## Your users

Your server describes the signed-in user with three fields:

* `id`: a stable identifier, unique in your application (1 to 256 characters).
* `groups`: optional group names, for example the customer the user belongs to.
* `attributes`: optional key and value strings, for example `{ customer: "acme", plan: "pro" }`.

The same `id` is the user everywhere: in spaces it is the principal `ext:<id>`, and in agent chats it is the user's conversation identity. A user who chats with an agent and opens a space is one person in both.

In a project's policies, groups appear as `ext:<group>` and attributes as tags:

```cedar theme={"system"}
permit(principal, action == Action::"OpenSpace", resource == Space::"pipeline")
when { principal in Group::"ext:acme" };

permit(principal, action == Action::"CustomerOverview", resource)
when { principal.type == "ext" && principal.getTag("customer") == resource.customerId };
```

Handlers read the same attributes from `ctx.principal.attrs`, so a read can scope its rows to the user's customer. Many customers can share one environment: the policies keep them apart.

## Set up embedding CLOUD

**1. Allow your site to frame spaces**

Open the project in **Ontology**, select the **Embed** tab, and add your site's origins under **Allowed origins**, for example `https://app.example.com`. Changes apply to the next space load.

**2. Create an embed key**

Under **Embed keys**, select **Create key**. Name it, then choose the environments, spaces, and agents it may open. Copy the key: it is shown once. Store it as a server secret, for example `TILDE_EMBED_KEY`.

**3. Mount the server handler**

Install `@trytilde/embed-server` and route `/api/tilde/*` to it. See [Embed spaces](https://trytilde.ai/docs/embed/spaces.md).

**4. Mount components in your pages**

Install `@trytilde/embed` and mount [spaces](https://trytilde.ai/docs/embed/spaces.md), [chat](https://trytilde.ai/docs/embed/chat.md), and [connection setup](https://trytilde.ai/docs/embed/connections.md).

An embed key opens only what it names. Revoke a key on the **Embed** tab and it stops working at the next request.

## Editions

Spaces and embed keys are Tilde Cloud features. With Tilde OSS, embed agent chats with `@trytilde/chat-proxy` and each agent's chat key. See [Embed chat](https://trytilde.ai/docs/embed/chat.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.