Skip to main content

Quickstart

This guide will walk you through installing hinter-core and hinter-cline and connecting to your first peer. hinter-core runs natively on your machine, enabling it to manage peer-to-peer connections by accessing your network interface directly. hinter-cline runs inside a Docker container, providing a standardized user environment and sandboxing the AI assistant as a security best practice.

Prerequisites​

  • Node.js (v22 or later) installed.
  • pm2 installed with the following command. 
    npm install -g pm2
  • hinter-core installed with the following command. 
    npm install -g @hinter-net/hinter-core@0.2.1
  • Docker Desktop installed and running.
Verify @hinter-net/hinter-core Integrity

Verify the integrity of the @hinter-net/hinter-core package by checking its provenance on npmjs.com. This shows it was built and published by Github Actions as described in the source repository.

Step 1: Run hinter-core​

hinter-core is the networking engine. It needs to be running in the background to send and receive reports.

  1. Initialize Your Data Directory & Keypair

    Open a terminal and run the following command.

    hinter-core-initialize

    This creates a hinter-core-data/ directory in your home directory, which will store all your data and your unique cryptographic keypair.

  2. Start hinter-core in the Background

    Start hinter-core using pm2.

    pm2 start hinter-core --name my-hinter-core
    Check Your Logs

    You won't see hinter-core output because it's running in the background, but you can check its logs anytime with:

    pm2 logs my-hinter-core

    Configure pm2 to start hinter-core automatically when your machine starts.

    pm2 save
    pm2 startup
    # ...and finally, run the command printed by `pm2 startup`.

Step 2: Run hinter-cline​

hinter-cline is your command center, providing a VS Code interface in your browser. It comes with Cline, an AI assistant extension for VS Code.

  1. Start hinter-cline in the Background

    Run this command to start the hinter-cline container. It's set to always restart, so it will launch automatically even after you restart your computer.

    docker run -d --name my-hinter-cline --restart=always --user $(id -u):$(id -g) -p 8080:8080 -v"$(node -p "require('os').homedir()")/hinter-core-data:/hinter-cline/hinter-core-data" bbenligiray/hinter-cline:0.2.5
    Do not use Command Prompt on Windows

    Use PowerShell or WSL CLI, and not the Command Prompt (CMD) on Windows. For example, the terminal in Docker Desktop uses PowerShell by default and is suitable to run these commands.

    This starts the hinter-cline container and makes it accessible on port 8080. It shares the hinter-core-data/ directory with hinter-core, so it can access your peers and reports.

  2. Open hinter-cline in Your Browser

    Navigate to http://localhost:8080. You should see the VS Code interface.

  3. Configure Cline

    • Click the Cline icon in the VS Code sidebar.

    • Select an AI provider and enter your API key.

      Free OpenRouter Models for Testing

      If you don't have a subscription to an AI provider, you can get a key from OpenRouter and start testing with one of the free models such as deepseek/deepseek-chat-v3-0324:free.

Step 3: Add Your First Peer​

Now you're ready to connect with a peer. You'll need their 64-character public key.

Find Your First Peer

If you don't know anyone to connect with, check out the Get Involved page for tips on how to find your first peers.

  1. Open a Terminal in hinter-cline

    In the browser-based VS Code interface, go to the "Terminal" menu and select "New Terminal".

  2. Run the helper

    In the new terminal panel, type the following command to start the helper tool:

    npm start

  3. Add a Peer

    • Select the "Add a peer" option from the menu.
    • Follow the prompts to enter a unique alias (a nickname) for your peer and paste their public key.

Step 4: Share Your Public Key​

Your peer needs to add you back!

  1. Find Your Public Key

    Your key is in the hinter-core-data/.env file. You can see it in the VS Code file explorer. The file will look like this:

    PUBLIC_KEY=...
    SECRET_KEY=...

    Copy the entire PUBLIC_KEY value.

    Protect Your Secret Key

    Never share your SECRET_KEY with anyone. Sharing it would allow others to impersonate you on the network.

  2. Send It to Your Peer

    Share your public key with your peer. Once they add you using the same steps above, you'll be connected!

Step 5: Send Your First Report​

Now that you're connected, you can send your first report. This is a two-step process.

  1. Create a Report Draft

    • In the hinter-cline terminal, run npm start to launch the helper.
    • Select the "Create a report draft" option.
    • Give your report a title.
    • When prompted to select recipients, choose the alias of the peer you just added.
    • A new Markdown file will be created in your entries/ directory. Add your content to this file and save it.

  2. Sync and Send the Report

    • Go back to the main menu of the helper tool.
    • Select the "Sync reports" option.

    This command detects your draft, prepares it by removing its frontmatter (the header enclosed by ---), and hands it off to hinter-core, which sends it to your peer. That's it!

What's Next?​

You've successfully set up your node and exchanged your first piece of intelligence!

To dive deeper, check out the user guides: