Self-Host no_human from Source and Build the Board

What no_human does and what this installation includes

no_human is an open-source AI coding workflow that runs on the operator's machine. Its intended loop starts with a task or tracker ticket, develops a plan from that request and the selected repository, makes changes, runs available tests, subjects the result to an independent review, and prepares a pull request for human approval. The board provides a visual place to follow that work, while the command-line interface supports task intake, status inspection, review, diff inspection, approval, and rejection.

The project places several checks between generated code and approval. Its documented workflow can prepare an explicit plan before code is written, use a separate reviewer that did not see the coding session, detect suspicious test changes, and verify reproduction evidence by checking whether a proposed test fails at the merge base and passes on the changed tree. If no test command is available, the resulting work reports that tests were not run rather than presenting an empty result as success. If the automation cannot complete a task, it can stop and record why instead of manufacturing a plausible result.

Those controls improve the evidence available to a reviewer, but they do not eliminate the need for human judgment. The final diff, test evidence, repository permissions, provider usage, and approval decision remain operational concerns. A successful installation only proves that the software and its immediate configuration work. It does not prove that every connected repository, tracker, model provider, CI system, or notification integration is configured correctly.

Why a source installation requires an extra build

The packaged installation and the source installation are not identical. The packaged command-line installation ships the board with the Python wheel. A fresh source checkout does not ship a prebuilt web/dist directory. The web application must therefore be built with npm before the board can render.

If that build is skipped, nh start can still serve the API, but there will be no board UI to display. This is one of the most important distinctions in the source workflow. A responding API does not by itself prove that the browser board was built successfully.

Prerequisites for building no_human from source

Prepare the machine before cloning the project. The documented source workflow requires Python 3.12 or newer, uv, Git, and Node.js with npm. Node.js is needed specifically for the board build. The repository contains the Python project metadata and a uv lock file, while the web directory contains the browser application and its npm dependencies.

Check the toolchain without assuming installation paths

The following version checks do not install anything and do not depend on a particular operating system package manager:

python --version
uv --version
git --version
node --version
npm --version

Some operating systems expose Python 3 as python3 rather than python. That command naming difference does not change the no_human requirement. What matters is that uv can select a compatible Python version for the project. Installation commands for Python, uv, Git, or Node vary by operating system and package manager, so they should be taken from the respective official installation instructions rather than guessed from a generic shell example.

Choose the host with the execution model in mind

no_human runs code and tests against repositories on the host. That means the account running it may need access to source code, Git remotes, model credentials, test tools, and any local services required by a repository's test suite. Treat this as a development execution environment, not merely a read-only dashboard.

Start with the least privilege practical for the repositories involved. Avoid running the application under an account with unrelated administrative access. Review how your Git credentials are scoped, decide whether the test repository can safely execute its own build and test commands, and keep production credentials out of the environment unless a specific workflow genuinely requires them.

Clone no_human and build the web board

Run the source installation in a terminal under the account that will operate no_human. Keep the repository directory after installation because subsequent uv run nh commands in this guide execute the project entry point from that checkout.

git clone https://github.com/no-human-ai/no_human.git
cd no_human

uv sync

cd web
npm install

npm run build

cd ..

For a compact copy of the same documented sequence, the build portion can be expressed as:

git clone https://github.com/no-human-ai/no_human.git
cd no_human
uv sync
(cd web && npm install && npm run build)

The subshell around the web commands returns the terminal to the repository root after the frontend build completes. If you prefer running each command separately, use the five-step version above because it makes the current directory explicit.

How to interpret a successful build

A successful uv sync establishes the Python environment and project entry point. A successful npm install establishes the frontend dependency tree. A successful npm run build compiles the web board. All three outcomes are required for the complete source installation described here.

Do not treat warnings and failures as interchangeable. A warning may still produce a usable build, while a nonzero command exit normally means that stage did not complete. Read the first meaningful error in the command output, not only the final summary. Dependency download problems, an incompatible runtime, or being in the wrong directory can produce many secondary messages after the original cause.

Initialize no_human and validate its configuration

With the Python environment synchronized and the board compiled, initialize no_human from the repository root. The documented initialization flow handles the token, configuration, and first repository. The exact credential prompts and integration choices can evolve, so follow the prompts shown by the installed version rather than copying secrets into a generic configuration example.

uv run nh init

uv run nh doctor

Treat nh doctor as a required verification stage, not a cosmetic check. If it reports a failed requirement, resolve that result before adding important work. Re-running the same diagnostic after a correction gives you a cleaner signal than proceeding until a later task fails for an unrelated-looking reason.

Credentials and configuration hygiene

no_human can connect to model providers, Git hosts, ticket trackers, notification systems, and CI platforms depending on how you configure it. The project documents integrations for Jira Cloud, Linear, monday.com, GitHub and GitLab workflows, Slack, Teams, Jenkins, and CircleCI. None of those integrations should be assumed to be active merely because the core application starts.

Add integrations deliberately and test them individually. Use credentials with only the permissions each integration needs. Do not place tokens in shell history, commit configuration containing secrets to a repository, or paste credentials into a tunnel definition. A Localtonet device token also identifies the device that runs a tunnel and must be kept private.

Start the board and verify the local service

The documented start command runs the board and worker on the loopback HTTP endpoint 127.0.0.1:8420. Loopback binding means the service is addressed from the same host and is not directly listening on every network interface.

uv run nh start

What local verification should prove

A useful local acceptance check has several parts. The start command should remain running rather than exiting immediately. The browser should connect to the documented loopback address. The board should render its UI, proving that the npm build produced usable assets. The worker and configuration should not show an immediate blocking failure. Finally, nh doctor should complete without an unresolved prerequisite that affects the intended workflow.

Perform these checks before introducing Localtonet. This isolates application and build problems from tunnel configuration. If the board does not work on 127.0.0.1:8420 locally, an HTTP tunnel cannot repair the underlying application.

Common no_human operations after installation

Once the board and worker are healthy, the CLI provides direct access to the task lifecycle. When operating from a source checkout, prefix the project command with uv run so it executes the synchronized entry point without requiring you to activate the virtual environment manually.

Open the interactive shell

uv run nh

Running nh without arguments opens the shell. It presents lanes, a live event tail, and an intake where a task can be described in plain language. The individual commands remain available if you prefer explicit terminal operations or automation.

Inspect current task status

uv run nh status

Status distinguishes work that needs human input, is actively working, is waiting, or is done. Check status before assuming that a quiet task has failed. It may be waiting for an external operation, parked for a specific answer, or finished and awaiting review.

Review evidence and inspect a proposed diff

uv run nh review TASK_ID
uv run nh diff TASK_ID

Replace TASK_ID with the real identifier shown by no_human. The review command displays the reviewer's evidence checklist. The diff command shows the change proposed for delivery. Use both. Review evidence describes why the work claims to be acceptable, while the diff shows what will actually change.

Approve or reject the result

uv run nh approve TASK_ID
uv run nh reject TASK_ID --reason "Explain what must change"

Approval is consequential because the documented workflow squash-lands the pull request using the configured approval identity. Do not use it as a way to dismiss a notification. Inspect the diff, tests, reproduction evidence, review findings, and target branch first.

Rejection sends the work back with feedback. Make the reason specific enough to guide the next attempt. State the incorrect behavior, missing acceptance criterion, unsafe change, or evidence gap instead of providing only a generic rejection.

Add remote HTTP access with Localtonet

Remote access should be a separate step after the board works locally. With Localtonet, the client on the host establishes an outbound connection to one of our relay servers. An HTTP tunnel can then provide a public HTTPS address for the local HTTP target without inbound router port forwarding, firewall changes, VPN setup, or a public IP address.

For this workflow, the intended local target is 127.0.0.1 on port 8420. The Localtonet client must run on the same machine as no_human, or on a device where that target address actually reaches the board. Remember that 127.0.0.1 always refers to the network namespace of the process using it. A client running on another computer or in an isolated container will not automatically reach the host's loopback service.

Choose the public address first

HTTP tunnels with Localtonet can use a random subdomain, a custom subdomain where supported, or a custom domain. All of these process types serve the same local content through a public HTTPS address. Available options can vary, and custom-domain DNS requirements should be checked against the current dashboard and documentation before making changes.

Because no_human validates the host used to address the board, decide which public hostname you intend to use before finalizing its allowed-host configuration. Avoid repeatedly changing between generated and custom hostnames during testing because every hostname change may require corresponding application configuration and verification.

Create and start the HTTP tunnel

For current dashboard guidance, consult our Localtonet HTTP tunnel documentation. Exact dashboard options, server choices, and domain requirements should be taken from the current product interface rather than assumed from an older deployment.

Understand the tunnel lifecycle

A Localtonet tunnel is available only while the selected client device is connected and the tunnel is running. If no_human stops, the tunnel may remain active but have no healthy local target. If the Localtonet client disconnects or the tunnel is stopped, the public address will no longer provide the active path to the board.

Stop the tunnel when remote access is no longer required. Delete it if the endpoint should not be retained. Stopping no_human alone is not a substitute for disabling an unnecessary public tunnel, and stopping the tunnel is not a substitute for safely shutting down application work in progress.

Security considerations for a localhost-oriented board

The central security fact for this deployment is straightforward: the board was designed to remain on localhost and does not supply user authentication. An HTTP tunnel changes who can reach the network endpoint. It does not add a login screen to no_human, does not create application roles, and does not make every board action safe for anonymous public access.

The no_human 0.2.0 release documents several protections at the local board boundary. Requests whose Host is not an allowed loopback host or the configured server.host are refused, which helps defend against DNS rebinding. Cross-origin browser writes to state-changing routes are refused, CORS is restricted to exact allowed hosts, and the WebSocket handshake applies Host and Origin checks. The board also serves a strict Content Security Policy, and board Markdown is hardened against cross-site scripting.

These are important browser and request-boundary defenses, but they are not a substitute for authenticating remote users. Configuring a public hostname as an allowed host means the application can recognize requests for that host. It does not prove who is making those requests.

A safer decision process

First ask whether the board must be remotely interactive. If the objective is merely to know when a task needs attention, a configured notification integration may be safer than exposing the full operator interface. If interactive access is necessary, limit it to the shortest practical period and to authorized users.

Next, review the actions visible through the board. A remote user may be able to see repository information, task descriptions, diffs, review findings, or operational status. Depending on the configured workflow, the interface may also expose state-changing operations. Do not publish it as an unrestricted convenience dashboard.

Finally, verify the entire request path. Check the public hostname, no_human's allowed-host setting, browser Origin behavior, WebSocket updates, and any access restrictions in front of the application. Test denied access as well as successful access. A control that has never been tested from an unauthorized context should not be assumed to work.

Troubleshooting the build, board, and tunnel

uv sync fails before installing the entry point

Confirm that the terminal is in the cloned repository root and that uv is available. Check that the Python version selected for the environment satisfies the Python 3.12 or newer requirement. Read the earliest dependency or interpreter error, correct it, and run uv sync again. Do not proceed to initialization if the project entry point was never installed into .venv.

npm cannot find the package or build definition

Confirm that the terminal is inside the repository's web directory before running npm install or npm run build. Running those commands from the repository root targets the wrong directory. Also verify that both Node.js and npm are present. The supplied project evidence establishes that Node with npm is required, but it does not establish a universal Node version for every future release, so consult the checked-out project's current metadata if npm reports an engine mismatch.

The API responds but the browser board does not render

This usually points back to the source-specific frontend requirement. A checkout without a successful web build has no web/dist, so nh start can serve the API while providing no UI. Return to the web directory, run npm install, run npm run build, and inspect any errors. Then restart no_human from the repository root.

The v0.2.0 release also notes that nh start can rebuild, or warn about, a stale web/dist. Do not depend on that behavior as a replacement for observing a clean initial board build. If you update the checkout and frontend source changes, rebuild and verify the board again.

nh doctor reports a failure

Use the diagnostic message to identify whether the problem belongs to the runtime, configuration, repository, credential, or integration layer. Correct one issue at a time and rerun the doctor command. Avoid masking the problem by starting the board repeatedly. A board process that launches does not invalidate a diagnostic warning about a workflow dependency.

Nothing listens on 127.0.0.1:8420

Confirm that uv run nh start is still running and did not exit after printing an error. Make sure you launched it from the source checkout containing the synchronized environment. Do not create the tunnel until the local browser can connect to http://127.0.0.1:8420.

The Localtonet tunnel is created but the public address is offline

Check each lifecycle dependency separately. The no_human process must be running. The Localtonet client must be connected on the selected device. The HTTP tunnel must have been started, because creating it does not start it. Its local target must be 127.0.0.1 and port 8420 from the client's own network context.

If the Localtonet client runs in a container or on another device, its 127.0.0.1 does not refer to the no_human host. Move the client to the host that runs no_human or design an explicitly reachable local target according to the security requirements of your environment. Do not broadly bind no_human to every interface as an improvised fix.

The public URL returns 400 or a bad-host response

This is consistent with no_human's Host boundary. Its allowed hosts include loopback and the configured server.host. Configure the exact public hostname according to the no_human documentation for the installed version, restart as required by that version, and test again. Do not disable Host validation. It exists in part to defend against DNS-rebinding attacks.

The page opens, but buttons or live updates fail

A partial success can indicate Origin or WebSocket validation rather than a basic TCP connection problem. The board applies Host and Origin checks to browser writes and its WebSocket handshake. Inspect the browser's developer tools for rejected HTTP requests or WebSocket connections, confirm that the public hostname exactly matches the allowed application configuration, and make sure you are consistently using the HTTPS public address rather than mixing local and public origins.

The local board works until the terminal closes

The documented start command runs the application as an active process. If that process is stopped, the board and worker stop. The evidence supplied for this guide does not establish a canonical background-service or operating-system service definition, so we do not invent one. If persistent startup is required, consult the no_human documentation for the installed version and use a process-management approach appropriate to your operating system.

A task is quiet and appears stuck

Run uv run nh status and inspect the event stream before restarting the application. The task may be working, waiting, requesting human input, parked by a quota condition, or stopped with a structured explanation. Restarting blindly can hide the distinction between expected waiting and an actual process failure.

Frequently asked questions