Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

6. Updating the Agent and Credentials

This page documents how to update each part of an existing installation: the binary, credentials, config, and schedule.

Hivel-agent is not a persistent process, it runs once and exits, so nothing here needs a "restart", whatever you update just needs to be in place before the next scheduled run fires.

Updating the binary

Re-run the same install method used for the initial installation (Step 1 - Install the Binary). This overwrites ./hivel-agent with the newest release.

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

Confirm the update:

./hivel-agent version

Before replacing the binary, make sure nothing is mid-run:

pgrep -f hivel-agent

If this returns a process ID, wait for that run to finish first.

After updating, run a pre-flight check before trusting the next scheduled sync:

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

Updating credentials

Every credential in .env is rotated at its source, then updated locally. hivel-agent reads .env fresh on every invocation, so there's nothing to restart.

HIVEL_API_TOKEN

The Hivel dashboard only allows one active agent token at a time. Use the Rotate option instead of generating a second one:

  1. Log in to the Hivel dashboard.

  2. Go to Settings → Integrations → scroll down to the "Hivel Agent" section.

  1. Click Rotate. This invalidates the existing token and issues a new one in its place.

  1. Copy the new token and update it in your .env file:

Source tool tokens

Follow the linked guide for each tool, deleting the existing token when you reach it in the flow and creating the new one in its place. Update the matching value in .env once you have it.

Credential
Guide

JIRA_TOKEN

Jira

GITHUB_TOKEN

GitHub

GITLAB_TOKEN

GitLab

BITBUCKET_TOKEN

Bitbucket

AZURE_TOKEN

Azure DevOps

CLAUDE_ADMIN_API_KEY

Claude

Validate after rotating any token:

Updating config.yml

Use this when adding a new source, adding another instance of an existing source, or changing what an existing source syncs. See Configuration Reference for the full key-by-key reference per provider.

Adding a new source

Add a new top-level block (jira:, github:, gitlab:, bitbucket:, azure:, or claudeotel:) following the same shape shown in Step 4 - Create config.yml, plus the matching credential in .env.

Adding another instance of an existing source

Append another entry to the same list with a distinct instance_slug:

Changing sync scope

Edit the relevant field directly: include_orgs, include_groups, include_workspaces, earliest_issue_date, or earliest_data_date.

Updating Jira custom fields

If a Jira admin adds, renames, or removes a custom field, re-run field discovery and update extra_fields in config.yml to match:

See Step 6 - Discover Jira Custom Fields for the full field-type table.

After any config.yml change, check and validate before the next scheduled run:

Updating the schedule

hivel-agent has no built-in scheduler, so there is nothing to update inside the agent itself, edit the crontab or systemd timer entry directly. If you lower work-metrics' --time-budget below the default 50m, you can schedule it more frequently than hourly, if you raise it, widen the interval so runs don't overlap. See Step 9 - Scheduling for the full cron examples.

After any update

Whatever changed, confirm it took effect before trusting a real sync:

  • config check and validate for config or credential changes

  • ./hivel-agent version to confirm a binary update

  • crontab -l or systemctl list-timers to confirm a schedule change is in place

  • tail -100 /var/log/hivel-agent.log on the next run rather than assuming it worked

Full config example

Troubleshooting

Last updated