> 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/hybrid-hivel-agent-quick-guide-tl-dr.md). # 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. {% hint style="warning" %} #### 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. {% endhint %} #### Step 1: Install the Binary **Linux / macOS / Windows (Git Bash or WSL):** ```bash curl -fsSL https://getagent.hivel.ai/get-agent.sh | bash ``` Or inspect first: ```bash 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: ```bash ./hivel-agent version ``` **Windows (native PowerShell):** ```powershell Invoke-WebRequest -Uri https://getagent.hivel.ai/get-agent.ps1 -OutFile get-agent.ps1 .\get-agent.ps1 .\hivel-agent.exe version ``` {% hint style="info" %} macOS: if you see "could not verify," run `xattr -d com.apple.quarantine hivel-agent`. {% endhint %} #### 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):** ```bash # Hivel, from Hivel dashboard > Settings > API Tokens HIVEL_API_TOKEN=hvl_xxxx # Jira Cloud JIRA_EMAIL=you@yourcompany.com 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=you@yourcompany.com 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:** ```yaml 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: ```yaml 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: ```yaml 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:** ```yaml 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:** ```bash ./hivel-agent --config config.yml --env-file .env validate ``` To validate one provider only: ```bash ./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. ```bash ./hivel-agent --config config.yml --env-file .env config fields ``` For multiple Jira instances, add `--instance `. 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: ```yaml 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: ```bash ./hivel-agent --config config.yml --env-file .env config check ``` ### Step 8: Run First Sync **On the agent host:** ```bash ./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. ```bash # 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): ```bash # 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:** ```bash 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: ```bash # 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. *** {% columns %} {% column %} Hybrid (Hivel agent) {% endcolumn %} {% column %} {% endcolumn %} {% column %} Overview {% endcolumn %} {% endcolumns %}