User Guide

Prerequisites

This guide assumes you have completed the Quickstart guide.

While hinter-core runs as a headless background service, it is managed entirely through its file structure. Understanding its directories and configuration files is key to managing your network and troubleshooting issues. All of your data is stored in the hinter-core-data/ directory.

Directory Structure

The hinter-core-data/ directory is the heart of your Hinter Net presence. It is created when you run the initialization script, as described in the Quickstart guide.

hinter-core-data/
├── .env                        # Your private keypair
├── hinter.config.json          # Global configuration (optional)
└── peers/
    └── {PEER_ALIAS}/           # Directory for a specific peer
        ├── hinter.config.json  # Configuration for this peer
        ├── incoming/           # Reports received from this peer
        └── outgoing/           # Reports to be sent to this peer

• .env: This file contains your unique PUBLIC_KEY and SECRET_KEY. You should back this file up in a secure location.
  • Share the PUBLIC_KEY with others so they can add you as a peer.
  • Never share your SECRET_KEY. It is the private key that controls your identity.
• peers/: This directory contains a sub-directory for each peer you add.
• peers/{PEER_ALIAS}/incoming/: Contains reports received from this peer. This directory is managed by hinter-core and should be treated as read-only.
• peers/{PEER_ALIAS}/outgoing/: Place files in this directory to send them to this peer. hinter-core will automatically detect and synchronize them. This is intended to be done using the hinter-cline helper tool.

Configuration (hinter.config.json)

You can apply settings globally or on a per-peer basis. Peer-specific settings always override global settings. These are advanced settings and are not typically needed for normal operation.

Global Configuration

Create a file at hinter-core-data/hinter.config.json to set global defaults for all peers.

• disableIncomingReports (boolean, optional, default: false): If true, your hinter-core instance will not listen for or accept any incoming reports from any peer.
• peerSizeLimitMB (number, optional, default: 1024): The maximum size (in megabytes) a peer's incoming/ directory can reach before they are automatically blacklisted to prevent abuse.

Managing Blacklisting

When the peerSizeLimitMB is exceeded, the peer is blacklisted by creating an empty file named .blacklisted in their peer directory. To undo the blacklisting, the conditions that caused the blacklisting must be reversed, and this file needs to be deleted manually.

Peer-Specific Configuration

Each peer's configuration is stored at hinter-core-data/peers/{PEER_ALIAS}/hinter.config.json. This file is created automatically when you add a peer with the hinter-cline helper tool.

It must contain the peer's publicKey. You can also add any of the global configuration keys here to override the default settings for just that peer.

Example:

{
  "publicKey": "a1b2c3d4e5f6...",
  "disableIncomingReports": true,
  "peerSizeLimitMB": 2048
}

How to

Upgrade hinter-core to Latest Version

Stop and remove the container named my-hinter-core that you created while following the Quickstart guide.

docker stop my-hinter-core
docker rm my-hinter-core

Then, start hinter-core using the command provided by the current Quickstart guide, which will use the latest version.

Migrating Through Breaking Changes

Some releases introduce breaking changes that require the user to handle. Always read the respective Release Notes before upgrading.

You can check the logs to ensure the new version started correctly.

docker logs my-hinter-core

Update Keypair

You may want to update your keypair if it is compromised, or as a regular security practice. To do so, Stop the container named my-hinter-core that you created while following the Quickstart guide.

docker stop my-hinter-core

Back up or delete your old keypair, and then generate a new one using the command provided by the current Quickstart guide.

Restart hinter-core.

docker start my-hinter-core

Finally, you must share your new public key with your peers for them to be able to update your peer configuration on their end.

Migrate to Another Machine

Stop and remove the container named my-hinter-core that you created while following the Quickstart guide.

docker stop my-hinter-core
docker rm my-hinter-core

Copy over your hinter-core-data/ directory to the new machine in its entirety.

Follow the Quickstart guide to start hinter-core on the new machine, skipping the initialization step.

Avoid Parallel Instances With the Same Keypair

hinter-core is designed to be operated as a single instance. Avoid running multiple instances with the same keypair.