> For the complete documentation index, see [llms.txt](https://docs.hivel.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hivel.ai/hybrid-hivel-agent/1.-overview.md).

# 1. Overview

Hivel supports two ways to connect to your Jira, GitHub, GitLab, Bitbucket, Azure DevOps and Claude instances. In the standard model, Hivel's infrastructure connects directly to your tools using a token you provide. Alternatively, **hivel-agent can run entirely within your own infrastructure, so your credentials never leave your network.** This document describes the self-hosted setup, intended for organizations that prefer to retain full control of their credentials rather than share them with Hivel.

### What is hivel-agent?

hivel-agent is a single, statically-linked binary you run on your own infrastructure (a VM, container, or scheduled job - no Docker required). It connects outbound to the engineering tools you configure (Jira, GitHub, GitLab, Bitbucket, Azure DevOps), pulls metadata about your projects/repos/issues/commits/pull requests, and uploads a compressed, normalized copy of that metadata to the Hivel platform for analytics.

It is not a persistent agent, proxy, or listener. It runs, does one pass of work, and exits. Nothing runs continuously unless you schedule it to (via your own cron/systemd timer - the agent has no built-in scheduler and cannot re-invoke itself, the scheduler setup is mentioned in the later of the documentation).

### Data flow - what talks to what?

Every arrow above originates from your network. None originate from Hivel. The agent makes outbound HTTPS calls.

| **Property**                   | **Value**                                                                                                        |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| Inbound ports required         | 4317 - gRPC (only if claude code is being integrated)                                                            |
| Outbound protocol              | HTTPS (TLS) only, port 443                                                                                       |
| Connections initiated by       | The agent, always outbound                                                                                       |
| Connections initiated by Hivel | None (*the Claude OTel Collector's inbound traffic originates from your own developer machines, not from Hivel*) |

### **Destinations the agent connects to**

<table data-header-hidden data-search="false"><thead><tr><th></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Destination</strong></td><td><strong>When</strong></td><td><strong>Purpose</strong></td></tr><tr><td>api.hivel.ai</td><td>Always</td><td>Sync watermark, presigned upload URLs, upload acknowledgement</td></tr><tr><td>*.s3.amazonaws.com (or regional equivalent)</td><td>Always</td><td>Direct upload of the compressed metadata payload</td></tr><tr><td>Your Jira URL</td><td>Only if Jira is configured</td><td>Read-only Jira REST calls</td></tr><tr><td>api.github.com or your GitHub Enterprise Server URL</td><td>Only if GitHub is configured</td><td>Read-only GitHub REST/GraphQL calls</td></tr><tr><td>gitlab.com or your self-hosted GitLab URL</td><td>Only if GitLab is configured</td><td>Read-only GitLab REST calls</td></tr><tr><td>api.bitbucket.org</td><td>Only if Bitbucket is configured</td><td>Read-only Bitbucket REST calls</td></tr><tr><td>dev.azure.com or your on-prem Azure DevOps Server collection URL</td><td>Only if Azure DevOps is configured</td><td>Read-only Azure DevOps REST calls</td></tr></tbody></table>

The agent only connects to the tool hosts you explicitly configure. If you don't configure GitLab, it never makes a single request to gitlab.com or anywhere else.

### Supported integrations

Hivel-agent currently supports the following data sources. Each is optional and independently configured:

| **Provider**                            | **Deployment models supported**                                                                                                                          |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Jira                                    | Cloud, Server, Data Center                                                                                                                               |
| GitHub                                  | github.com (cloud), GitHub Enterprise Server (self-hosted)                                                                                               |
| GitLab                                  | gitlab.com (cloud), self-hosted GitLab (15.6+)                                                                                                           |
| Bitbucket                               | Bitbucket Cloud only                                                                                                                                     |
| Azure DevOps                            | Azure DevOps Services (cloud), Azure DevOps Server / TFS (on-prem)                                                                                       |
| Claude Code - via a separate claudeotel | config block (not an API token like the sources above). See [Claude Code](/integrations/ai-tools/claude-integrations.md) Settings for the config fields. |

\
No other integrations exist in the agent today. If a source isn't listed above, the agent has no code path that talks to it, regardless of what may appear in other reference material - this document reflects the current, running implementation.

{% columns %}
{% column %} <a href="/hybrid-hivel-agent/hybrid-hivel-agent-quick-guide-tl-dr.md" class="button primary" data-icon="backward">TL;DR (Hybrid Agent)</a>
{% endcolumn %}

{% column %}

{% endcolumn %}

{% column %} <a href="/hybrid-hivel-agent/2.-getting-started.md" class="button primary" data-icon="forward">Getting Started</a>
{% endcolumn %}
{% endcolumns %}