Teaflask turns your codebase and documentation into an agent that understands your product and can act on a user's behalf. Your users interact with that agent through an assistant embedded in your app.

## Prerequisites

- A GitHub repository containing your product's code, with permission to install the Teaflask GitHub App.
- Access to your app's frontend code to embed the assistant.

## Connecting your codebase

Your code is where Teaflask learns what your product does. It uses your connected repositories to discover actions and to draft and verify documentation.

1. Open **Settings → Integrations → GitHub**.
2. Install the GitHub App and choose the repositories Teaflask may read. Selection happens on GitHub, and you can change it there at any time.
3. Set each repository's **production branch**, the branch Teaflask treats as your live product. Docs are drafted and verified against it.

The GitHub integration is read-only and cannot write to your repositories. See [GitHub](/github) for more about repository permissions and security.

## Building your knowledge base

Docs are how the agent understands your product, not just a source of answers. They explain how features work, how workflows fit together, and which rules apply when the agent acts on a user's behalf.

An agent can still run without docs, using its prompt and the tools you grant it. Docs give it the product-specific context that those instructions and API definitions may not capture.

1. Open **Docs** and choose **New doc**.
2. Give the doc a title and write or paste its content.
3. Review the doc and **release** it when it is ready.

Releasing makes that version available to agents with access to the doc. You can keep editing without changing what those agents read; they continue to use the released version until you release an update.

See [Drafting](/drafting) for more ways to create docs, including generating them from your codebase, and [Verification](/verification) for how code-backed docs are checked as your product changes.

## Registering actions

Actions are API calls an agent can make on a user's behalf. When you run a scan, Teaflask automatically discovers these calls from your connected codebase and prepares a proposed catalog for review.

1. Open **Actions** and start a scan.
2. Review the discovered actions and approve the ones you want in your catalog.
3. Set each action's policy:
   - **Allow:** the agent can run the action without asking for approval.
   - **Ask:** the user must approve the action before it runs.
   - **Deny:** the agent cannot run the action.

Approving an action only adds it to your organization's catalog. You separately choose which agents can use it, so discovering or approving an action does not automatically give every agent access.

A useful starting point is **Allow** for read-only actions and **Ask** for actions that change data. You can adjust these policies as you review how your agents are being used.

See [Actions](/actions) for the full catalog and approval model.

## Configuring your agent

Open **Agents** and select an existing agent or create a new one. Choose its **model** and write a **prompt** describing its role, what it should help users with, and how it should behave. Type `@` in the prompt to reference available tools, actions, or skills.

Then choose what the agent can access:

- **Knowledge:** enable **Search docs** to find relevant documentation. Add **Browse docs as files** to let the agent read complete docs. Use tag or folder filters if it should only see part of your knowledge base.
- **Actions:** grant the actions this agent may perform. The catalog's policies still apply; granting an action does not override a requirement for approval or a denial.

Other capabilities let the agent [navigate and interact with your app](/access), follow reusable [skills](/skills), retain [memory](/memory), work in an isolated [workspace](/workspace), or [delegate work to subagents](/delegation). Enable the capabilities that fit its role.

Use the **Playground** to see how the agent follows your instructions and uses your docs. Actions and navigation need to be tried in your app, where the integration can execute them.

**Publish** the agent to make its configuration available to the embedded assistant. Later edits do not affect that published version until you publish again. See [Revisions](/revisions) for version history and restoring earlier configurations.

## Installing the assistant in your app

The assistant is an embeddable widget. Installing it is a frontend-only change: add a React component or a script tag to your app. Teaflask hosts the agent, so you do not need to build a chat backend or run the model yourself.

The assistant uses a **publishable key** to connect to your agent:

1. Open the agent's **Install** section and select **New key**.
2. Choose **test** or **live** mode and add your app's **allowed origins**, such as `https://app.example.com`. An origin includes the protocol, hostname, and port if present, but no page path.
3. Copy the publishable key.

The key is public by design and safe to include in browser code. Mount the assistant once in the shared layout that wraps your pages, so it stays available as users move through your app.

### React

Install the package:

```sh
npm install @teaflask/assistant
```

Import the component and its styles, then render it near your app's root:

```tsx
import { TeaflaskAssistant } from "@teaflask/assistant";
import "@teaflask/assistant/styles.css";

<TeaflaskAssistant publishableKey="YOUR_PUBLISHABLE_KEY"/>;
```

### Other stacks

The script tag works with server-rendered apps, static sites, and other frontend frameworks. Add the loader and element to your shared HTML layout, before `</body>`:

```html
<script
  type="module"
  src="https://app.teaflask.com/assistant/v1/assistant.js"></script>

<teaflask-assistant
  publishable-key="YOUR_PUBLISHABLE_KEY"></teaflask-assistant>
```

Replace `YOUR_PUBLISHABLE_KEY` with the key you created. Both options embed the same assistant interface. See [Install](/install) for more details, including navigation and Content Security Policy configuration.

### Connecting actions to your app

The **actions adapter** is a small piece of frontend code that connects the assistant to your existing API. Configure it once to use your app's session cookies, authentication headers, or API client; you do not need to build a new endpoint or handler for every action.

When the agent requests an action, Teaflask builds the API request from your approved catalog and passes it to the adapter in the user's browser. The request goes to the API destination you configured, not an arbitrary server chosen by the model.

This keeps API actions within the operations you have approved and granted to the agent. Configure the adapter to use the current user's authentication, so your API applies the same permissions it would to that user's other requests. The integration does not require separate administrator credentials or direct database access.

See [Adapters](/adapters) for setup instructions. Without an adapter, the assistant can use its knowledge but cannot execute your catalog's API actions.

### Identifying users and customizing the assistant

The basic embed works without identifying visitors to Teaflask. To associate conversations with signed-in users and let them access their history across devices, follow [Identity](/identity). This adds a backend step to issue signed user tokens; it is separate from the authentication your API already uses for actions.

You can match the assistant to your product's colors, fonts, logo, and light or dark mode. See [Appearance](/appearance) for customization, [Surfaces](/surfaces) for a dedicated assistant page alongside the widget, and [Tool views](/tool-views) for displaying action results in your own components.

## Next steps

- [Production checklist](/production-checklist): what to review before making the assistant available to your users.
- [How Teaflask works](/fundamentals): how the agent uses knowledge, chooses actions, and handles requests.
- [Glossary](/glossary): the terminology used throughout these docs.
- [Conversations](/conversations): what users asked and what the agent did.
- [Billing](/billing): your balance, top-ups, and using your own model provider keys.
- [Troubleshooting](/troubleshooting): help with setup and runtime problems.