Hybrid Hivel Agent Quick Guide (TL;DR)

hivel-agent is a single static binary you run on your own infrastructure so your Jira/GitHub/GitLab/Bitbucket/Azure DevOps credentials never leave your network. Only compressed metadata is uploaded to Hivel. No Docker or other runtime needed. It runs once, does a sync, and exits; you schedule repeats yourself via cron/systemd (Step 9). Every connection is outbound HTTPS to Hivel and whichever tools you configure. What leaves your network: issue/PR/commit metadata and commit/PR message and comment text by default. What never leaves: source code, diffs, attachments, and your tool credentials.

Prerequisites

Before you start, confirm you have:

• A host to run the agent on: 2+ CPU cores, 4GB+ RAM (8GB+ for large orgs), 50GB+ disk, Linux/macOS/Windows, outbound HTTPS (443) only

• curl and jq (brew install jq / apt install jq)

• A Hivel API token (Settings > API Tokens in the Hivel dashboard)

• A token for each tool you're integrating: Jira (API token for Cloud, PAT for Server/Data Center), GitHub (Personal Access Token), GitLab (PAT with read_api scope), Bitbucket (repository access token), Azure DevOps (PAT)

• If any tool sits behind a firewall or IP allowlist (Jira Server/DC, GitHub Enterprise Server, self-hosted GitLab, Bitbucket Server, Azure DevOps Server): add this host's IP to that tool's allowlist. Cloud/SaaS versions need no allowlisting.

Step 1: Install the Binary

Linux / macOS / Windows (Git Bash or WSL):

curl -fsSL https://getagent.hivel.ai/get-agent.sh | bash

Or inspect first:

curl -fsSL https://getagent.hivel.ai/get-agent.sh -o get-agent.sh
bash get-agent.sh

For a specific version: bash get-agent.sh v1.0.0

Confirm it works:

./hivel-agent version

Windows (native PowerShell):

Invoke-WebRequest -Uri https://getagent.hivel.ai/get-agent.ps1 -OutFile get-agent.ps1
.\get-agent.ps1
.\hivel-agent.exe version

macOS: if you see "could not verify," run xattr -d com.apple.quarantine hivel-agent.

Step 2: Create Your Hivel API Token

In the Hivel dashboard:

1. Go to Settings > Integrations, scroll to "Hivel Agent"

2. Click Generate Key

3. Copy the token for your .env file in Step 3

Step 3: Create Credentials File

On the agent host, create .env (never commit this file):

# Hivel, from Hivel dashboard > Settings > API Tokens
HIVEL_API_TOKEN=hvl_xxxx

# Jira Cloud
JIRA_EMAIL=[e-mail]
JIRA_TOKEN=your_atlassian_api_token

# GitHub (if syncing GitHub)
GITHUB_TOKEN=ghp_xxxx

# GitLab (if syncing GitLab)
GITLAB_TOKEN=glpat_xxxx

# Bitbucket (if syncing Bitbucket)
BITBUCKET_EMAIL=[e-mail]
BITBUCKET_TOKEN=your_bitbucket_token

# Azure DevOps (if syncing Azure DevOps)
AZURE_TOKEN=your_azure_devops_pat

# Claude Enterprise (if using Claude Enterprise plan)
CLAUDE_ADMIN_API_KEY=your_claude_admin_api_key

Jira Server/Data Center with PAT: omit JIRA_EMAIL, set only JIRA_TOKEN. With basic auth: use JIRA_USERNAME + JIRA_PASSWORD instead.

Only fill in blocks for tools you're integrating; delete or ignore the rest.

Step 4: Create config.yml

On the agent host:

hivel:
  api_token: ${HIVEL_API_TOKEN}

jira:
  - instance_slug: jira
    url: https://your-org.atlassian.net
    email: ${JIRA_EMAIL}
    token: ${JIRA_TOKEN}
    earliest_issue_date: "2025-01-01"

Add more blocks for other tools you're integrating, each is a list, so you can combine multiple instances of the same tool. Minimal per-tool blocks:

github:
  - instance_slug: github-main
    token: ${GITHUB_TOKEN}
    earliest_data_date: "2025-01-01"
    include_orgs:
      - your-github-org

gitlab:
  - instance_slug: gitlab-main
    token: ${GITLAB_TOKEN}
    earliest_data_date: "2025-01-01"
    include_groups:
      - your-gitlab-group

bitbucket:
  - instance_slug: bitbucket-main
    email: ${BITBUCKET_EMAIL}
    token: ${BITBUCKET_TOKEN}
    earliest_data_date: "2025-01-01"
    include_workspaces:
      - your-workspace

azure:
  - instance_slug: azure-main
    token: ${AZURE_TOKEN}
    earliest_data_date: "2025-01-01"
    organization: your-org

Azure DevOps Server (on-prem): add is_server: true and point url at the full collection URL:

azure:
  - instance_slug: azure-onprem
    token: ${AZURE_TOKEN}
    is_server: true
    url: https://host/tfs/CollectionName
    earliest_data_date: "2025-01-01"

Tracking Claude Code usage:

claudeotel:
  - instance_slug: acme-claude
    base_url: https://otel-collector.hivel.ai/api
    api_key: dummy-value
    org_id: "1132"

Add only the blocks you need. Multiple providers sync in parallel. Give each instance a distinct instance_slug if configuring multiple instances of the same tool (e.g., jira-1/jira-2).

Alternatively, omit token from any provider block and the agent fetches it from Hivel using your HIVEL_API_TOKEN instead.

Step 5: Validate Connectivity

On the agent host:

./hivel-agent --config config.yml --env-file .env validate

To validate one provider only:

./hivel-agent --config config.yml --env-file .env validate --provider jira

(Same pattern for github, gitlab, bitbucket, azure, claudeotel.)

Fix any reported errors before continuing.

Step 6: Discover Jira Custom Fields (Jira Only)

Skip if not syncing Jira.

./hivel-agent --config config.yml --env-file .env config fields

For multiple Jira instances, add --instance <slug>. Find field IDs for Hivel semantic types in the output's hivel_suggestion column: STORY_POINTS, SPRINT, PRODUCT, ALLOCATION, EPIC.

Step 7: Add Jira Custom Fields to Config (Jira Only)

Skip if not syncing Jira. Using field IDs from Step 6, add them to your jira: block:

jira:
  required_hivel_types:
    - STORY_POINTS
    - SPRINT
    - PRODUCT
    - ALLOCATION
    - EPIC
  extra_fields:
    - customfield_10016 - STORY_POINTS  # replace with your actual field IDs
    - customfield_10020 - SPRINT
    - customfield_10042 - PRODUCT
    - customfield_10044 - ALLOCATION
    - customfield_10014 - EPIC

Validate the config:

./hivel-agent --config config.yml --env-file .env config check

Step 8: Run First Sync

On the agent host:

./hivel-agent --config config.yml --env-file .env sync --verbose

A TUI dashboard launches automatically in interactive terminals. To disable: add --no-progress instead of --verbose. To sync one provider only: add --provider github.

Step 9: Set Up Scheduling

hivel-agent has no built-in scheduler. Use cron or systemd timer for recurring syncs.

# crontab -e : sync, once daily at midnight UTC
0 0 * * * cd /opt/hivel-agent && ./hivel-agent --config config.yml --env-file .env sync --no-progress >> /var/log/hivel-agent.log 2>&1

Each run pulls only incremental changes; daily is sufficient.

If using the optional work-metrics classification job (Bitbucket/Azure DevOps/GitHub/GitLab only):

# crontab -e : work-metrics, hourly at 15 minutes past
15 * * * * cd /opt/hivel-agent && ./hivel-agent --config config.yml --env-file .env work-metrics >> /var/log/hivel-agent-work-metrics.log 2>&1

Default --time-budget is 50 minutes, designed to finish before the next hourly run starts.

Check whether a scheduled run happened:

pgrep -f hivel-agent              # is a run in progress right now?
tail -100 /var/log/hivel-agent.log            # did the last sync succeed?
tail -100 /var/log/hivel-agent-work-metrics.log
crontab -l                        # confirm the cron entry exists

Step 10: Verify What Was Sent

Inspect the literal payload before trusting the agent:

# 1. Pull data to local disk only, no Hivel credentials needed, nothing uploaded
./hivel-agent --config config.yml --env-file .env download --output-dir /tmp/snapshot

# 2. Inspect exactly what would be sent
gunzip -c /tmp/snapshot/jira/jira_issues.json.gz | jq '.[0]'

# 3. Only once satisfied, upload the inspected snapshot
./hivel-agent --config config.yml --env-file .env send --input-dir /tmp/snapshot

What never leaves your network: source code, file contents, diffs, attachments, and tool credentials.

What does leave by default: issue/PR/commit metadata and commit/PR message and comment text (unless you enable strip_text_content).

---

For ongoing operations and detailed per-platform config options, see the full guide.

---

Hybrid (Hivel agent)

Overview