> 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/6.-updating-the-agent-and-credentials.md).

# 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
```

{% hint style="warning" %}
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.
{% endhint %}

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.

<figure><img src="https://3057781534-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5KAIOUWph0JLSgQqbzyT%2Fuploads%2FPlma1lcTVNqMiEDtZ51W%2Fimage.png?alt=media&amp;token=51f6405a-9fc8-47a8-a7d7-052c4ff16d42" alt="" width="563"><figcaption></figcaption></figure>

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

<figure><img src="https://3057781534-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F5KAIOUWph0JLSgQqbzyT%2Fuploads%2F6BEh3yH3jq00mJSj7DsW%2FUntitled%20design.png?alt=media&amp;token=22a21ebb-3255-4d1b-83a5-11b5721a3be6" alt=""><figcaption></figcaption></figure>

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

```
HIVEL_API_TOKEN=HIVEL_xxxx
```

**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](/integrations/project-management/jira.md)                                      |
| `GITHUB_TOKEN`         | [GitHub](/archive/github.md)                                                          |
| `GITLAB_TOKEN`         | [GitLab](/integrations/version-control/gitlab.md)                                     |
| `BITBUCKET_TOKEN`      | [Bitbucket](/integrations/version-control/bitbucket.md)                               |
| `AZURE_TOKEN`          | [Azure DevOps](/integrations/version-control/azure/azure-devops-cloud-recommended.md) |
| `CLAUDE_ADMIN_API_KEY` | [Claude](/integrations/ai-tools/claude-integrations/enterprise-plan.md)               |

Validate after rotating any token:

```
./hivel-agent --config config.yml --env-file .env validate --provider <name>
```

#### 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`:

```
jira:
  - instance_slug: jira-1
    url: https://team-a.atlassian.net
    email: ${JIRA_EMAIL}
    token: ${JIRA_TOKEN}
    earliest_issue_date: "2025-01-01"
  - instance_slug: jira-2
    url: https://team-b.atlassian.net
    email: ${JIRA_EMAIL}
    token: ${JIRA_TOKEN}
    earliest_issue_date: "2025-01-01"
```

**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:

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

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:

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

#### 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

{% columns %}
{% column %} <a href="/hybrid-hivel-agent/5.-configuration-reference/full-config-example.md" class="button primary" data-icon="backward">Full config example</a>
{% endcolumn %}

{% column %}

{% endcolumn %}

{% column %} <a href="/hybrid-hivel-agent/7.-troubleshooting-and-security-notes.md" class="button primary" data-icon="forward">Troubleshooting</a>
{% endcolumn %}
{% endcolumns %}