# Connector

> An agent in your network: a git bridge and an integration host. Tokens, keys and network access stay with you.

The connector is a small agent that you run **on your own machine, in your own network**.
It does two things:

- **git bridge** — carries repositories that are not reachable from the internet over to us and brings
  pull requests back;
- **integration host** — runs [plugins](/en/docs/connector/marketplace) from our
  catalogue: [task trackers](/en/docs/connector/trackers),
  [knowledge sources](/en/docs/connector/knowledge) (Confluence, Notion, Google Drive, Figma,
  folders and network drives), [the web](/en/docs/connector/web) — and
  [your own MCP servers](/en/docs/connector/custom-mcp).

_Illustration: The “Connectors” section in the app: the agents, their status, the repositories they serve and the installed integrations._

## What it is

The connector’s core is **only the git bridge**. It is deliberately small: you can read it
in full before letting it into your network, and it does not grow with every new
integration. Everything else is plugins: signed bundles that the connector
downloads from the catalogue, verifies by signature and runs **as separate processes under
separate OS users**.

```
      your network                              │        our side
                                                │
 your git ◀──locally──┐                         │
                      │                         │
 your tracker ◀locally┤   CONNECTOR             │
                      ├── core: git bridge ─────┼──outbound──▶ Buff platform
 (Jira, GitLab, …)    └── plugin ──┐            │
                          plugin ──┴─ own uids, │
                                     own hosts  │
```

Three properties of this picture hold everything else up:

1. **Outbound connections only.** The connector calls out by itself; nothing connects into your
   network. You do not need to open a port to the outside — not even for tracker events
   ([polling always works](/en/docs/connector/trackers#events-polling-and-webhooks)). The exceptions are
   GitLab commit comments and Figma without a list of files and projects: they arrive only
   by webhook, and the connector’s event receiver must be reachable by whoever sends it; the
   `FILE_COMMENT` webhook comes from Figma’s cloud, that is, from the internet
   ([more](/en/docs/connector/knowledge#events)).
2. **Secrets do not cross the perimeter.** The git token, the tracker token and the agent’s own key
   stay on your machine. The plugin **does not see** them either: the connector builds the outgoing request
   and inserts the credentials itself —
   [how exactly](/en/docs/connector/isolation#credentials-the-plugin-does-not-see-them).
3. **Boundaries are declared in advance.** Where a plugin may go and which tools it
   gives the model is visible **before installation**, in the catalogue, and later — in the app.

## What leaves and what does not

| | |
|---|---|
| **Never leaves** | access tokens (git, tracker), the agent’s key, the contents of your secrets, any addresses and systems that are not on the allowed list |
| **Leaves on your command** | the contents of the repositories you selected: the import carries them into your isolated space on our side — without that there is nothing to develop |
| **Leaves when the bot is addressed** | the text of the request, the ticket title and link, the name of the request’s author, the ticket key and — for a question from a pull request — the branch name |
| **Leaves at the model’s request** | the content the model read with the connection’s tools for a specific answer: pages, files, tickets, a pull request diff, web pages found — exactly what the tool returned; every call is recorded in the connection’s log |
| **Leaves constantly** | the agent’s state: version, online/offline, the list of repositories it serves, the list of connections with their tools and allowed addresses |

Everything that comes to us is then processed by the model according to the organisation’s plan: on OpenRouter plans — a third-party provider; on dedicated capacity and in a custom setup — a dedicated machine, without third-party providers. See [Plans](/en/docs/tariffs).

None of this is collected “just in case”: tracker events are read only in
the selected projects and only when the bot is addressed directly, and the status report is
exactly what you see in the app in the “Connectors” section.

## Where to start

1. [Download and install the agent](/en/docs/connector/install) on a machine that has
   access to your git and outbound internet access.
2. In the Buff app open **“Connectors” → “Add connector”** and get
   a one-time pairing code.

_Illustration: The pairing code is valid for 15 minutes and is used once._

3. Set up the agent — through the [local page](/en/docs/connector/web-setup) or the
   [terminal](/en/docs/connector/cli-setup): the git provider, token, repositories and the pairing
   code.
4. Need a tracker — install the integration [from the catalogue](/en/docs/connector/marketplace) and
   create a connection. How it works from the team’s side — in the
   [“Tracker integrations”](/en/docs/connector/trackers) section.

You can add a repository, change a token or adjust a connection later **without
a restart** — changes apply on the fly.

## Pages

| Page | About |
|---|---|
| [Installation](/en/docs/connector/install) | the binary and the image, signature check, privileges, the plugin runtime |
| [Local page](/en/docs/connector/web-setup) | the six sections of the setup page: overview, connection, repositories, catalogue, integrations, your own MCP |
| [Terminal](/en/docs/connector/cli-setup) | the same with commands — a full reference, no graphics |
| [Catalogue and plugin installation](/en/docs/connector/marketplace) | what is visible before installation, signature, versions, updates, revocation |
| [Isolation and access boundaries](/en/docs/connector/isolation) | a process per connection, a separate uid, allowed addresses, credentials |
| [Tools and the model](/en/docs/connector/tools) | how a plugin’s tools reach the model, in which modes, and why writing ones never do |
| [Tracker integrations](/en/docs/connector/trackers) | requests, commands, visibility scope, the pull request branch, events |
| [Knowledge sources](/en/docs/connector/knowledge) | Confluence, Notion, Google Drive, Figma and files as context for answers: read tools, questions on a page and on a mock-up, parameters instead of pictures |
| [Notion](/en/docs/connector/notion) | pages and databases as context; questions in comments; the research report as a child page; scope, webhook and polling |
| [Google Drive](/en/docs/connector/google-drive) | documents, spreadsheets and presentations as context; questions in comments; the report as a document; a service account or your own account |
| [Files on disk](/en/docs/connector/files) | folders on a server and SMB network folders as context: Word, Excel, PowerPoint, PDF and text; read-only, no index |
| [The web](/en/docs/connector/web) | searching and reading public pages within the administrator’s allow and block lists; DuckDuckGo, SearXNG or Brave |
| [Jira](/en/docs/connector/jira) | Data Center, Server and Cloud: versions, access, specifics |
| [Custom MCP servers](/en/docs/connector/custom-mcp) | an MCP server from an archive, a GitHub repository or by address: what will run, consent, only read-only tools — as you mark them |
| [Config by hand (YAML)](/en/docs/connector/yaml) | the full reference of the settings file for Ansible and CI |
| [Management and removal](/en/docs/connector/manage) | connectivity check, log, updates, shutdown, revocation |