Build and verify a local HackerAI development environment before making its web interface remotely reachable
HackerAI is an AI-powered penetration testing web application built with Next.js and backed by several hosted services. This guide follows the installation sequence documented in its official repository, explains the required accounts, and shows how to verify the local development service without assuming a hostname or port. Once the application works locally, we will connect that confirmed endpoint to a Localtonet HTTP tunnel as a separate remote-access step. Because HackerAI is security-sensitive, the guide also covers credential handling, authorization, and exposure boundaries.
What this installation actually provides
The HackerAI repository describes the project as an AI-powered penetration testing assistant that helps users find and fix vulnerabilities by working with AI. The installation covered here is its local development workflow. It starts a Next.js development server together with a Convex development server, while Agent mode requires an additional Trigger.dev worker.
This distinction matters because the repository is not a completely self-contained offline stack. The application depends on accounts and credentials for hosted services, including AI model access, moderation, cloud execution, data storage, authentication, and durable agent tasks. Running the source code on your computer does not remove those dependencies. It gives you a local development instance whose supporting services still need to be configured correctly.
Penetration testing tools can generate requests, execute tasks, and interact with systems in ways that may be disruptive or unlawful without permission. Restrict all testing to systems you own or environments for which you have clear written authorization. A Localtonet tunnel provides reachability to the local web service, but it does not grant permission to test another system or replace the application’s authentication and access controls.
Prerequisites and service dependencies
Before cloning the repository, install Git and a Node.js environment capable of running the project’s pnpm-based workflow. The repository provides a pnpm lockfile and documents pnpm commands, so use pnpm rather than substituting another package manager unless the project maintainers explicitly document that alternative. The available evidence does not establish a specific Node.js or pnpm version, so check the current repository files and documentation for version constraints before installation.
You will also need accounts for the required hosted services. Keep API keys and service credentials out of terminal transcripts, screenshots, shared chat messages, and version control. The repository includes an environment example file, but values must come from your own service accounts and current project configuration. Do not copy placeholder values into a production-like environment without understanding what each variable controls.
Install HackerAI from the official repository
Follow the repository’s documented order. Do not start by creating a public tunnel. First complete setup, start the development services, and verify that the application responds locally. This separation makes troubleshooting easier and prevents an incomplete or misconfigured service from being exposed unnecessarily.
Confirm the required accounts and local tools
Prepare Git, the project-compatible Node.js environment, pnpm, and the required hosted accounts. Obtain credentials directly from the relevant service dashboards, but do not place secrets in shell history or commit them to the repository.
Clone the HackerAI repository
Clone the official public repository to your development machine.
git clone https://github.com/hackerai-tech/hackerai.gitEnter the project directory
Change into the cloned repository before running dependency or setup commands.
cd hackeraiInstall the project dependencies
Use the package manager documented by the project so that dependency resolution follows the repository’s pnpm configuration and lockfile.
pnpm installRun the setup script
Launch the repository-provided setup process. Follow its current prompts and instructions rather than guessing environment values. Service credentials must come from your own accounts.
pnpm run setupStart the Next.js and Convex development servers
Start the combined development workflow. According to the repository documentation, this command runs both the Next.js and Convex development servers.
pnpm run devAlternative startup and Agent mode
If you need to inspect or troubleshoot each development service separately, the repository also documents separate commands for Next.js and Convex. Run these in two terminals from the project directory:
pnpm run dev:nextpnpm run dev:convexAgent mode adds another component. Create a Trigger.dev project, place your Trigger.dev development secret in the local environment under the variable name documented by the repository, and configure the worker-side environment variables in the Trigger.dev dashboard. The worker needs the relevant Convex, OpenRouter, OpenAI, and cloud sandbox configuration, plus any optional integration keys used by your tasks.
The Trigger.dev development secret, AI provider keys, Convex service credentials, authentication configuration, and optional integration credentials are sensitive. Never paste their values into a tutorial, public issue, tunnel URL, or committed configuration file. A public HTTP endpoint and a private backend credential solve different problems. Keep credentials private even when the web interface requires remote access.
Start the default Trigger.dev worker in a third terminal when local Agent requests require it:
pnpm dev:triggerThe repository also documents a branch-routing override, but it should be used only when the request path is configured to target the same stable Trigger.dev branch. For a standard local setup, start with the default worker command and introduce branch routing only when you have a specific development requirement.
Verify HackerAI locally before creating a tunnel
Watch the development-server output after running the startup command. The available project evidence confirms that a Next.js development server is started, but it does not establish a fixed hostname or port. Use the exact local URL printed by your current development process. Do not assume a conventional framework default, because repository settings, environment configuration, or another process on the machine may change the listening address or port.
Open the reported URL in a browser on the same machine. Confirm that the application loads and that the authentication flow reaches the expected state. If you intend to use Agent mode, verify that the Convex service and Trigger.dev worker remain running and inspect each terminal for configuration or connection errors.
If the application does not work through the local URL, adding Localtonet will not repair its dependencies, authentication, or application configuration. Resolve local errors first. Once the endpoint works on the machine running the Localtonet client, tunnel troubleshooting can focus only on target selection and connectivity.
Choose the correct Localtonet access method
HackerAI exposes a browser-based Next.js interface, so an HTTP tunnel is the appropriate Localtonet tunnel family for this workflow. Our client establishes an outbound connection to a Localtonet relay server. This makes the local web service reachable through a public URL without inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
The Localtonet client must run on the development machine or another device that can reach the confirmed HackerAI endpoint. The local target consists of the IP address and port shown by the development server. The public tunnel remains available only while the selected client is connected and the tunnel is running.
| Component | Purpose | What to verify |
|---|---|---|
| HackerAI Next.js server | Provides the local browser interface | Use the hostname and port printed by the running development server |
| Convex development server | Supports the application database and backend workflow | Keep it running and resolve backend configuration errors locally |
| Trigger.dev worker | Runs local Agent tasks when Agent mode is used | Start it separately and configure the required worker environment |
| Localtonet HTTP tunnel | Publishes the verified local web endpoint | Select the correct device, local address, local port, and available relay server |
Set up Localtonet remote access
Complete these steps only after HackerAI works through its local URL. Available relay servers, regions, and account options can vary, so select current values from our dashboard rather than copying a hardcoded server code from an article. For the current interface and configuration details, consult our HTTP tunnel documentation.
Install and run the Localtonet client
Run our client on the HackerAI development machine or on a device that can reach the verified Next.js endpoint over the local network.
Authenticate and select the client device
Use the device-specific authentication token associated with the client that will carry the tunnel. Keep that token private and never include it in screenshots, commands, or shared configuration examples.
Select an available relay server
Choose a currently available server or region from the dashboard. Do not rely on a hardcoded server value because availability can change.
Create the HTTP tunnel configuration
Configure an HTTP tunnel whose local target matches the IP address and port reported by the HackerAI Next.js server. Do not substitute an assumed framework port.
Start the tunnel
Creating a tunnel does not start it. Use the Start button, then confirm that the selected client remains connected and the tunnel reports that it is running.
Test the assigned public URL
Open the assigned public HTTPS address from an authorized remote device. When testing is complete, stop or delete the tunnel so the development interface is no longer publicly reachable.
Security practices for remote development access
Treat the public URL as internet-facing even when you share it with only one person. Keep HackerAI’s authentication enabled, use least-privilege accounts, and avoid exposing administrative or debugging functionality unnecessarily. Review the application terminals while remote access is active so that authentication failures, backend errors, and unexpected requests are visible.
A tunnel controls network reachability, not application authorization. It does not automatically make a development server suitable for unrestricted production use. Development services may produce verbose errors or depend on credentials intended only for testing. Limit the tunnel’s lifetime to the remote session and stop it when it is no longer required.
If a remote request reaches the Localtonet URL but the page does not function correctly, retest the local endpoint and inspect the Next.js, Convex, and Trigger.dev processes independently. If the public URL does not connect at all, confirm that the correct Localtonet device is online, the tunnel is started, and its target exactly matches the working local address and port.
Frequently asked questions
Is HackerAI fully self-contained when installed locally?
No. The documented development setup runs application components locally but still requires hosted accounts for OpenRouter, OpenAI, E2B, Convex, WorkOS, and Trigger.dev. Optional capabilities can require additional services.
What port does the HackerAI development server use?
The supplied official evidence does not establish a fixed hostname or port. Read the URL printed by the active Next.js development process and use that exact address for local verification and the Localtonet target.
Do I need the Trigger.dev worker for the basic web interface?
The repository specifically requires the Trigger.dev worker for local Agent mode because agent tasks run through Trigger.dev. Start it in a separate terminal when you need those Agent requests.
Why should I verify HackerAI locally before using Localtonet?
Local verification confirms that Next.js and the required backend components are configured correctly. Localtonet publishes a reachable service, but it does not repair application startup, authentication, dependency, or credential errors.
Does creating a Localtonet tunnel immediately make it available?
No. After creating the configuration, you must start the tunnel. The selected client must remain connected, and the tunnel must remain running for its public URL to work.
Does a public tunnel replace HackerAI authentication?
No. The tunnel provides network reachability to the local endpoint. Keep the application’s authentication and authorization controls enabled, protect all credentials, and expose the development service only for the time and users required.
Connect your verified HackerAI development service
Once HackerAI loads correctly through its reported local URL, use our HTTP tunneling workflow to provide controlled remote reachability without configuring inbound router port forwarding.
Get Started Free →
