Advanced troubleshooting

If the normal setup procedure fails, use these instructions.

CAUTION: Do not share passwords, pairing links, model keys, or device credentials. This information can give another person access.

Connection status

Run the status command:

hermes-connector status

Exit code	Meaning
0	The Connector is connected.
1	The Connector has a paired identity but no connection.
2	The Gateway refused the device credential. The device credential can be revoked.
3	The Connector has no paired identity.
4	The Connector and Gateway use incompatible protocol versions.

The status shows the Gateway address, agent identity, and connection state. The status does not show the device credential.

The network connection of the App does not prove that Hermes is online.

The user service

The Connector runs as your systemd user service. The Connector makes an outbound connection. The Connector opens no inbound network port.

To see the service state, run:

systemctl --user status aamg-hermes-connector

To see the service logs, run:

journalctl --user -u aamg-hermes-connector

The Connector records a recovery summary at each start.

CAUTION: Do not share service.env. This file contains a device credential.

Hermes is not available to the service

CAUTION: A service restart interrupts active tasks. Before you continue, wait until no tasks are active.

In your terminal, run hermes --version.
Make sure that the command succeeds.
From the same terminal environment, run hermes-connector service install.
Run systemctl --user restart aamg-hermes-connector.
Run hermes-connector status.

The installation command saves the current PATH for the service.

Service start and stop

To start the service, run:

systemctl --user start aamg-hermes-connector

To stop the service, run:

systemctl --user stop aamg-hermes-connector

If your machine has no working user service manager, ask your machine administrator to enable one.

Do not install the Connector as root to bypass this requirement.

The machine configuration controls whether the service continues after logout or a machine restart.

Pair the device again

A normal connect command refuses to replace an existing device credential.

The --re-pair option permits the Connector to replace its local device credential.

CAUTION: Do not install the service before pairing is complete. The service can keep an older device credential for another Gateway.

CAUTION: A service restart interrupts active tasks. Before you pair the device again, wait until no tasks are active.

Run the pairing command:

hermes-connector connect --re-pair

Make sure that the App shows the intended agent identity.
Make sure that the Gateway address matches the address in the terminal.
Approve the pairing request.
Wait for successful pairing in the terminal.
Wait for the command to return.
Run hermes-connector service install.
Run systemctl --user restart aamg-hermes-connector.
Run hermes-connector status.
Make sure that the agent identity and Gateway address are correct.

A revoked device credential stays revoked.

Interrupted tasks

A Connector restart does not automatically repeat an accepted task. This restriction prevents duplicate tool actions.

Before any recovery command, select the journal files used by the installed service.

If the service uses a custom Connector home, set HERMES_CONNECTOR_HOME to that actual path first.

The following commands use HERMES_CONNECTOR_HOME or its default, $HOME/.aamg/hermes-connector.

CAUTION: Do not source or print service.env. This file contains a device credential.

Run these commands in the same terminal that you use for recovery:

export HERMES_CONNECTOR_HOME="${HERMES_CONNECTOR_HOME:-$HOME/.aamg/hermes-connector}"
export DISPATCH_JOURNAL_PATH="$HERMES_CONNECTOR_HOME/dispatch-journal.json"
export RESPONSE_JOURNAL_PATH="$HERMES_CONNECTOR_HOME/response-journal.json"

To see the interrupted entries, run:

hermes-connector recover --list

CAUTION: Use --confirm only after you prove that the runtime did not execute or forward the entry.

Clearing an uncertain entry can cause duplicate actions. If you cannot prove non-execution, keep the entry.

For assistance with an uncertain entry, use the contact instructions.

After you prove non-execution, run:

hermes-connector recover <run_id> --confirm

Recovery clears the recorded entry. Recovery does not restart a process that stopped.

Native session recovery

The recover --list output also shows incomplete native-session reservations. A native session is the conversation history that Hermes stores.

Use the exact recovery token from this output. Do not use a guessed Run ID.

If the native session exists, use its exact session ID:

hermes-connector recover <token> --confirm --hermes-session-id <exact-session-id>

The Connector makes sure that the session exists. The Connector also makes sure that the reserved title matches.

Without --hermes-session-id, recovery can leave a later turn without provable native history. The Connector refuses that turn instead of creating replacement context.

CAUTION: Do not delete journals or session bindings to force a retry. This action can cause duplicate tool effects.

Pairing errors and Gateway errors

Symptom	Action
`no Gateway origin is configured`	Install the production Connector from the setup instructions. For a custom Gateway, run `hermes-connector connect --gateway-url https://<your-gateway>`. HTTP is not permitted.
`the release-configured Gateway origin is the staging endpoint`	Install the production package. Do not bypass the origin requirement. A staging address is not a valid production default.
The App and terminal show different Gateway addresses.	Cancel the pairing request. Use an App and Connector for the same Gateway.
The pairing link is rejected or expired.	Start a new pairing request. Approve only the intended agent. Do not reuse the old link. Each link expires after five minutes or one use.
`status` exits with code 2.	If the device credential is revoked, run `hermes-connector connect --re-pair`. Approve a new pairing request.
`status` exits with code 4.	Install the version from the current production setup instructions. Do not downgrade only the Connector or only the Gateway.
The App cannot reach the Gateway.	Make sure that the phone has a network connection. Make sure that the pairing screen shows the correct Gateway address. On the agent machine, run `curl https://aamg-api-staging.azuddin.com/healthz`.

The health response proves network access to the Gateway. The response does not prove account access or an agent connection.

Notifications and background tasks

Permit Android notifications for the App. Keep the agent machine online.

Android force-stop prevents normal push delivery until you open the App again.

A background-process kill is not the same as Android force-stop.

Even if no notification arrives, read the task result in the App.

A machine failure or Connector failure can interrupt a task. Uncertain tool effects prevent automatic task repetition.

Read about data, access removal, and assistance.