Skip to main content

Connecting a HackerAI Agent to Your Local Machine

A simple guide for enabling local command execution from HackerAI.

HackerAI lets you connect your machine to Agent Mode. Once linked, you can run commands on your device—useful for local tooling, automation, and testing assets on your machine.

Available on every plan, including Free.

What the local client does

The HackerAI Local Client (@hackerai/local) opens a secure connection between your computer and HackerAI. While it's running, Agent Mode can:

  • Execute terminal commands on your computer in real time

  • Use your machine's visibility for scanning and testing (subject to your OS and permissions)

Commands run directly on your host OS—there is no container isolation layer in the current client.

There are two ways to connect: the Desktop App (easiest) or the CLI client.

Option A: Desktop App (Recommended)

1. Download the HackerAI Desktop App

2. Sign In

Open the app and sign in with your HackerAI account. The connection is established automatically once you're authenticated—no token or manual setup needed.

3. Select Local

The app defaults to Cloud execution. To run commands on your machine, switch from Cloud to Local using the sandbox selector in the chat input area, or under Settings → Agents → Default execution environment.

Option B: Remote Control (CLI Client)

1. Get Your Token

  1. Log in to HackerAI.

  2. Open Settings (from the sidebar or your account menu).

  3. Open the Agents tab.

  4. Click Generate Token or copy an existing token.

That token links this machine to your HackerAI account.

2. Install and Start the Local Agent

Quick Start (recommended)

npx @hackerai/local@latest --token YOUR_TOKEN

Or install globally:

npm install -g @hackerai/local

hackerai-local --token YOUR_TOKEN

3. Usage Examples

npx @hackerai/local@latest --token hsb_abc123 --name "My Laptop"

  • --name is optional; if omitted, the client defaults to your hostname.

4. Select Your Machine

Once connected, switch to your machine under the Remote control section using the sandbox selector in the chat input area, or under Settings → Agents → Default execution environment.
​

5. Options

Option

Description

--token TOKEN

Required authentication token

--name NAME

Name shown in HackerAI

--help, -h

Show help message

Security Overview

  • Commands run on your OS without isolation. Only run the client (app or CLI) on machines you trust and control.

  • The client exits automatically after about 1 hour of inactivity to reduce long-lived sessions.

  • The Desktop App will show a disconnected status but can be reconnected with one click.

Did this answer your question?