Hollow connector documentation

Overview

A Hollow connector is a manifest-driven integration definition. It describes what the connector does, how it authenticates, what setup data it needs, which actions it exposes, and how Hollow should represent it in the product.

Connectors are meant to be installable by end users. A user can browse a connector, understand what it touches, authenticate their own account, and then let Hollow call the connector’s declared actions.

Connector model

A connector has four core parts:

1. Listing metadata: name, slug, description, category, install copy.
2. Connection model: auth type, auth schema, setup mode, scopes.
3. Action model: one or more actions with input/output schemas.
4. Manifest details: additional structured data Hollow can store and use.

Hollow stores the connector definition, publishes it in the app, records user installs, and executes actions through the connector runtime. Developers do not need direct database or infrastructure access.

What Hollow hosts

What developers host

In the common case, developers do not need to host anything beyond their own product or API. If a connector requires inbound webhooks, signature validation, provider-specific orchestration, or custom runtime logic, the developer should host that logic themselves and let Hollow call it over HTTPS.

Developers do not receive shell, server, or database access to the Hollow backend. The contract is declarative: you provide connector metadata and connection details through the dashboard, and Hollow handles the app-side install and user connection lifecycle.

Required fields

A draft connector can be incomplete, but a published connector must be coherent enough for users and Hollow to work with it safely.

Identifiers

Identifiers are short keywords or phrases that tell Hollow when a connector should be considered. They are not user-facing marketing copy. They are routing hints.

Good identifier examples for a GitHub issue connector:

• github issues
• repo issue
• bug ticket
• open issue
• assign issue

Published connectors currently require at least five identifiers so Hollow has enough metadata to reason about connector relevance.

Actions

Actions are the executable units of a connector. Each action should have a stable key, a plain-English description, and an input shape that Hollow can reliably fill.

Strong action definitions usually include:

• A clear key such as create_issue
• A concise description of what the action does
• An input schema with named fields
• Output structure if the action returns meaningful data
• A scope that matches the actual upstream permission boundary

Auth types

Hollow supports multiple connector auth types.

Setup modes

Setup mode describes the user experience Hollow should show after installation.

• guided: Hollow walks the user through the connection flow.
• manual: The user provides API keys or settings manually.
• external: The user must complete part of setup on the provider side.

In practice, a connector can combine a setup mode with an auth type. For example, oauth plus guided is a common pairing.

Install flow

A typical install flow looks like this:

1. User browses the connector listing in Hollow.
2. User installs the connector.
3. Hollow checks the auth type and setup mode.
4. If needed, Hollow begins a connection flow.
5. Connection state is saved against that specific user install.
6. The connector becomes available for runtime use.

OAuth flow

For OAuth connectors, the user authenticates against the developer’s own product or provider account. Hollow hosts the generic callback endpoint and stores the resulting user connection state.

https://hollow-backend.fly.dev/v1/connectors/oauth/callback

High-level OAuth flow:

1. User installs the connector in Hollow.
2. Hollow starts the connection flow.
3. Hollow redirects the user to the provider authorize URL.
4. The provider redirects back to Hollow’s OAuth callback.
5. Hollow completes the connection and stores the result for that user.

Action invocation

At runtime, Hollow chooses a connector action and invokes it with a normalized input payload. For connectors this generally means:

1. Resolve the installed connector and action key.
2. Verify the user has a valid connection.
3. Build request input from the action parameters.
4. Call the runtime target described by the connector definition.
5. Return output or error state to Hollow.

Publishing

Draft connectors can be incomplete. Published connectors should be ready for real installs. Before publishing, check:

• The listing copy is understandable to non-developers.
• At least one real action exists.
• At least five identifiers exist.
• The auth model matches the real provider flow.
• Scopes and install copy accurately describe access.
• The connector has been tested with a real user account.

Example connector payload

The dashboard is the normal way to manage connectors, but it helps to understand the shape Hollow expects.

{
  "name": "Linear Incident Runner",
  "slug": "linear-incident-runner",
  "tagline": "Create and triage Linear incidents from Hollow.",
  "description": "Connect Linear and let Hollow create incidents, search issues, and update triage state.",
  "category": "productivity",
  "auth_type": "oauth",
  "setup_mode": "guided",
  "visibility": "private",
  "status": "draft",
  "install_copy": "Connect your Linear account so Hollow can search and update incidents.",
  "identifiers": [
    "linear incidents",
    "incident triage",
    "product issue",
    "bug ticket",
    "engineering issue"
  ],
  "scopes": ["read", "write"],
  "auth_schema": {
    "flow": "oauth",
    "authorize_url": "https://provider.example.com/oauth/authorize",
    "token_url": "https://provider.example.com/oauth/token",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  },
  "actions": [
    {
      "key": "search_incidents",
      "name": "Search incidents",
      "description": "Search existing incidents in Linear.",
      "input_schema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" }
        }
      }
    }
  ],
  "manifest": {
    "version": "1.0"
  }
}

OAuth callback reference

Hollow hosts the callback URL. The developer is still responsible for registering that URL with the upstream OAuth provider.

https://hollow-backend.fly.dev/v1/connectors/oauth/callback

If your provider requires a single exact callback value, use that exact URL. If your provider requires app-side deep linking, Hollow handles the app redirect after the callback completes.

Dashboard usage

The dashboard is where connector drafts are created, updated, and published. It is also where auth schema, settings schema, scopes, actions, manifest fields, and identifiers are entered.

Relevant pages:

• Dashboard login
• Private dashboard

Testing checklist

• Install the connector with a fresh user account.
• Complete the auth flow for the configured auth type.
• Confirm the connector shows as connected.
• Invoke every published action with at least one real payload.
• Verify error handling for missing credentials or expired tokens.
• Verify the listing copy still matches the actual permissions used.

Troubleshooting

OAuth redirect mismatch

Make sure the provider has this callback registered exactly: https://hollow-backend.fly.dev/v1/connectors/oauth/callback

Connector installs but cannot connect

Check the configured auth_type, setup_mode, authorize URL, token URL, client ID, and client secret.

Connector publishes but Hollow never chooses it

Check identifiers first. Published connectors should have at least five high-signal identifiers that reflect the actual user requests the connector is meant to handle.

Connector needs custom webhooks or custom server logic

Host that logic yourself and expose a stable HTTPS endpoint. Hollow does not host arbitrary developer code.