ButterStack Connector Guide

The ButterStack Connector is a small, outbound-only daemon your studio runs on its own network so ButterStack can reach a private, on-premises tool that has no public endpoint: Perforce (Helix Core), Jenkins, TeamCity, or GitHub Enterprise Server.

Where the CLI and MCP server let you and your AI agents reach into ButterStack, the Connector is the reverse arrow: it lets ButterStack reach into your network to read build status, changelists, and job results, without you opening any inbound ports or exposing an internal server to the internet.

How it works

The Connector opens a single outbound WebSocket connection from inside your network to ButterStack. It follows the same pattern as GitHub self-hosted runners, Cloudflare Tunnels, the Datadog Agent, and Fivetran hybrid agents:

• No inbound ports. The connection is initiated from your side, over 443. Nothing on your network is exposed publicly.
• Local credential custody. Your P4 user and ticket, Jenkins API token, TeamCity token, and GHES token live only in the Connector’s local config on the host that runs it. ButterStack never receives them; our side stores only a hashed digest of the Connector’s own token.
• Per-project. A Connector belongs to one ButterStack project. You can run more than one per project - for example, a separate Connector for Perforce and another for Jenkins - so different tools stay isolated on their own outbound connection and token. Integrations in that project attach to a Connector as a transport.
• Typed command allowlist. The Connector only executes a fixed, allowlisted set of read-oriented commands (p4.*, jenkins.*, teamcity.*, ghes.*). It is not a shell.

Create a Connector

1. Open your project and go to Integrations, then the Connectors tab.
2. Choose Create connector and give it a name (for example, studio-build-01).
3. Copy the token shown on the next screen. It is displayed once and never again. It is stored on our side only as a SHA-256 digest, so we cannot show it to you later.
4. Save the generated connector.yml on a host inside your network, mode 0600, and start the Connector with the shown docker run command.

The connector list shows a masked hint for each token (bsc_<project-id>_...<last4>) so you can tell connectors apart without ever revealing the secret. To rotate a token, revoke the Connector and create a new one; revoking closes its connection.

Example connector.yml

endpoint: wss://connect.butterstack.com/connect
token: bsc_<project-id>_<your-secret>
connector_id: "studio-build-01"

The token goes in connector.yml (or an Authorization: Bearer header), never in a URL query string. Keep connector.yml at mode 0600 on the host that runs it.

Source and downloads

The Connector is open source. You can read the code, verify the protocol, and build it from source, or pull a signed release image:

• Repository: github.com/ButterStack/butterstack-connector
• Container image: ghcr.io/butterstack/connector (pin the digest from the release notes)

See the protocol reference in the repository for the full wire format and the per-tool command vocabulary.

Security posture

• The Connector token is stored on our side only as a SHA-256 digest and shown to you exactly once.
• Revoking a Connector closes its connection; your local tool credentials are untouched.
• The Connector runs as a non-root container user and reads its credentials from local config, with *_file indirection available so secrets never sit in the process environment.
• Every command the Connector runs is scoped to the project that owns it, so a misconfigured or compromised Connector can never serve another project’s commands.