Install Codewhale with npm and Access It Remotely

What this Codewhale and Localtonet workflow does

Codewhale is a local developer agent rather than a conventional public website. The codewhale command starts its interactive terminal client, while codewhale web starts its bundled local browser client. The official project describes that browser client as running on 127.0.0.1, the IPv4 loopback interface. You can review the project, current commands, and development status in the official Codewhale repository and on the Codewhale website.

A service bound to 127.0.0.1 is directly reachable only from the same computer. Another device cannot use its own 127.0.0.1 address to reach the Codewhale host because every computer has a separate loopback interface. This local binding reduces direct network reachability, but it does not provide application authentication.

With Localtonet, our client application runs on the computer that can reach Codewhale. It establishes an outbound connection to a Localtonet relay server. An HTTP tunnel can then map a public HTTPS address to Codewhale's local IP address and port without inbound router port forwarding, a public IP address, VPN setup, or an inbound firewall change. The public endpoint is available only while the selected client is connected and the tunnel is running.

Keep installation, protection, and tunneling separate

Complete the workflow in three phases. First, install Codewhale and prove that its terminal and browser clients work locally. Second, determine what protects the browser client from unauthorized use. Third, configure and start the Localtonet tunnel only after that protection has been tested.

This order makes failures easier to isolate. A tunnel cannot repair an invalid npm installation, a model-provider problem, or an unknown application endpoint. More importantly, testing security only after starting a public tunnel creates an avoidable exposure window.

Prerequisites, supported targets, and setup decisions

Node.js and npm

The npm installation route requires working Node.js and npm installations. The current evidence does not specify a minimum supported Node.js or npm version, so this guide does not invent one. Use a maintained Node.js release supported by your operating system and organizational policy, then check both commands:

node --version
npm --version

Both commands should return version information. If either command is unavailable, install or repair Node.js through an approved operating-system or runtime-management method before continuing.

Platforms represented by current Codewhale release assets

The Codewhale v0.10.1 release publishes matched binaries for Linux x64 and ARM64, macOS x64 and ARM64, Windows x64 and ARM64, and Android ARM64 for Termux. The npm wrapper downloads the matching release binaries. Codewhale describes Android on Termux as a preview, so it should not be treated as equivalent to the primary desktop targets.

Check the Codewhale v0.10.1 release information for the release assets and notes verified for that version. Also review the current Codewhale releases before installing, since the current version and supported packaging can change after this article is published.

Use one Codewhale installation route

Codewhale documents npm alongside its shell installer, winget, Cargo, archives, and other installation routes. The project advises choosing one route because several installations on the same machine can compete through the shell PATH. This article uses npm throughout.

If Codewhale is already installed, determine which executable your shell resolves before adding another copy. Do not assume an npm installation will replace a binary installed by winget, Cargo, a shell script, or a manually extracted archive.

Prepare a low-risk workspace

Start with a disposable or version-controlled test project. Do not use a home directory, filesystem root, production checkout, or folder containing unrelated repositories. Remove private keys, deployment tokens, cloud credentials, customer data, signing material, and production configuration from the test workspace.

Repository ignore rules control version tracking, not process access. A file ignored by Git may still be readable by a local agent if the operating-system account and workspace permit it.

Choose a model route

Codewhale supports hosted provider accounts, OpenAI-compatible endpoints, and local or self-hosted inference through systems such as Ollama, vLLM, and SGLang. Provider accounts, keys, model availability, costs, and self-hosted runtime configuration belong to those respective services.

The terminal and local browser client do not require a Codewhale account. Codewhale also offers an account-based route for managing provider keys. Signing in does not upload existing local keys, and local use remains available without an account.

Prepare Localtonet access

Create a Localtonet account if you do not already have one. From the current Localtonet product interface, obtain the supported client application for the operating system on which Codewhale runs. Install and launch that client on the same computer as Codewhale, then associate it with its device-specific authentication token.

Installer presentation and client packaging can vary by operating system and client release. This article does not invent a shell command or installer URL that is not present in the supplied current documentation. Use the installation option presented by the current Localtonet dashboard or documentation for your operating system.

Install Codewhale globally with npm

The official npm command is:

npm install -g codewhale

A global installation places the codewhale command in npm's global executable location. The package wraps the matched Codewhale release binaries rather than requiring you to build the Rust project from source.

codewhale --version

If the command is not found, reopen the terminal and inspect npm's global executable location and your PATH. Avoid immediately switching to an administrator shell or broadly changing directory ownership. The correct global-package permission fix depends on how Node.js was installed. Follow the operating system's policy or use an approved user-scoped runtime manager.

Configure a model and test the terminal workflow

Start Codewhale from the controlled workspace:

codewhale

In the interactive terminal interface, run /provider or press F3 to add a hosted provider key or select a local runtime. Use /model to change models and /help to inspect the commands and keyboard shortcuts provided by the installed version.

Treat provider credentials as secrets. Enter them only through documented configuration methods. Do not put a model key in a tunnel URL, project file, screenshot, public log, or shell command that will be retained in history.

Review mode and approval posture

Codewhale documents Plan, Work, and Operate modes. Plan explores without making changes. Work can edit files and run commands. Operate can pursue a goal through planned and verified steps. Its approval postures include Ask, Auto-Review, and Full Access.

Begin with a restrictive mode and approval posture. Full Access still follows Codewhale's hard policy boundaries, but it permits more autonomous activity than an unfamiliar remote workflow should normally receive. Codewhale also documents Seatbelt sandboxing on macOS and bubblewrap on Linux when bubblewrap is installed and working. Sandboxing is an additional control, not a replacement for authentication, workspace isolation, or least privilege.

Run a harmless test

Ask Codewhale to explain a file or inspect the test project before requesting modifications. Check the proposed actions, approval prompts, command output, and resulting files. The project provides receipts for file operations, commands, and approvals, plus recovery controls such as /undo and /restore.

This test confirms that the executable runs, the intended workspace is active, the model route works, and approval requests are visible. Troubleshoot any failure here before introducing the web client.

Start and verify the local Codewhale browser client

From the intended project directory, run:

codewhale web

The official project identifies this as the bundled local browser client on 127.0.0.1. Keep the process running while using the browser interface. Stopping the process removes the local HTTP target.

This limitation matters because an HTTP tunnel requires both a local IP address and a local port. Do not enter a port copied from an unofficial tutorial. If you cannot confidently identify the browser client's endpoint, stop here and consult the current Codewhale project information rather than exposing another local service accidentally.

Complete the local browser test

After identifying the endpoint, open its exact 127.0.0.1 address and port in a browser on the Codewhale computer. Confirm all of the following before configuring a tunnel:

• The page belongs to the expected Codewhale process.
• The intended project and session are visible.
• A harmless prompt reaches the configured model.
• Approval requests appear according to the selected posture.
• Stopping codewhale web makes that endpoint unavailable.
• Restarting it does not connect your browser to a different local service.

Recheck the endpoint whenever you restart or update Codewhale. This is a verification requirement, not a claim that the port necessarily changes.

Do not confuse the browser client with the Runtime API

Do not assume that the Runtime API and browser client share a port or security model. If you need API integration rather than browser access, use current official Codewhale documentation and perform a separate local security review.

Establish protection before starting a public tunnel

The supplied Codewhale material does not establish a browser-client authentication mechanism that can safely be assumed across versions and configurations. Therefore, local success alone is not enough to justify public exposure.

Before starting a Localtonet tunnel, verify that an unauthenticated browser cannot reach the agent's control surface. Suitable protection must prevent unauthorized users from reading sessions, viewing project content, submitting prompts, accepting approvals, modifying files, or running commands. Depending on your environment, that can mean verified application authentication or another access-control boundary placed in front of the service.

This tutorial cannot prescribe an undocumented Codewhale authentication switch. If you cannot demonstrate effective protection before exposure, keep the browser client local. Do not start the tunnel for a quick test and plan to inspect anonymous behavior afterward.

Reduce the authority available to the process

• Run Codewhale under a dedicated or otherwise limited operating-system account where practical.
• Use a narrow project directory containing only the files needed for the task.
• Remove unnecessary credentials from the environment and workspace.
• Begin with conservative tool approvals and avoid Full Access for initial remote sessions.
• Disable plugins, MCP servers, hooks, skills, and Computer Use capabilities that are not required.
• Keep backups or version-control recovery available for files the agent may change.

Test the protective boundary locally

Validate the access-control layer before adding the public path. Use a new browser profile or signed-out session and confirm that it cannot reach Codewhale without authorization. Confirm that sessions expire or can be revoked according to the protection you selected. Also test that authorization is required for sensitive actions, not only for the landing page.

Install Localtonet and configure the HTTP tunnel

Install our client on the Codewhale host. Since Codewhale documents its browser client on 127.0.0.1, a Localtonet client running on another computer cannot normally reach that loopback interface. The supplied Codewhale evidence does not establish a supported option for changing the bind address, so this procedure keeps both processes on the same machine.

The current Localtonet HTTP workflow uses the client device's authentication token, an available relay server, an HTTP process type, and the local IP address and port. Dashboard wording and the options available to an account may vary by client version, plan, region, or product update. Obtain server choices from the current dashboard rather than copying a server code from an old tutorial.

For the current interface and available HTTP options, use the Localtonet HTTP tunnel documentation. Custom-domain DNS requirements should be checked there before changing DNS records. Do not assume that every process type, server, region, or option is included in every plan.

Verify the public result safely

Use an authorized remote browser session. Confirm that the access-control challenge appears before Codewhale content and that invalid or missing credentials are rejected. After authenticating, perform only a harmless read-only task. Check that the workspace, model, mode, and approval posture match the local session.

Stop the tunnel immediately if a fresh unauthenticated browser can see the workspace or control the agent. Do not leave a partially working interface online while investigating.

Routine operation, updates, and troubleshooting

Use a repeatable startup sequence

1. Open the intended project and check it for unnecessary secrets.
2. Start Codewhale and confirm the model, mode, and approval posture.
3. Start codewhale web.
4. Determine and locally verify its exact loopback endpoint.
5. Confirm that the authentication or access-control boundary is active.
6. Confirm that the Localtonet target matches the verified endpoint.
7. Start the tunnel and test it as an authorized remote user.
8. Stop the tunnel when the remote session is finished.

Update Codewhale carefully

Codewhale documents this update command:

codewhale update

Review current Codewhale release notes before updating, especially changes involving the browser client, permissions, approvals, provider handling, or installation. Keep your chosen installation route in mind and do not accidentally create a second installation through another package manager.

After an update, run codewhale --version, test the terminal workflow, restart the browser client, re-identify its exact endpoint, and retest access control before starting the tunnel.

The codewhale command is not found

Reopen the terminal and verify that npm --version works. Inspect npm's global executable directory and confirm that it is present in PATH. Check whether another Codewhale installation is shadowing the npm-installed command.

The terminal starts but cannot use a model

Use /provider to inspect the provider route and /model to choose an available model. For hosted providers, verify the credential and model access. For local inference, test the inference service independently. Do not diagnose the tunnel until the model works locally.

The browser client does not load locally

Confirm that codewhale web is still running. Verify the endpoint using current official guidance or a trusted local listener inspection. Remember that 127.0.0.1 is local to the Codewhale host, so the first browser test must occur on that machine.

The public URL fails while local access works

Confirm that the Localtonet client is connected and that the HTTP tunnel has been started. Compare its local IP and port with the currently verified Codewhale endpoint. Confirm that the protective proxy or other access-control layer, if used, is also running and that the tunnel targets the protected endpoint rather than an unprotected backend.

The public page loads but agent functions fail

The supplied evidence does not define every HTTP interaction used by the browser client. Compare local and remote behavior without assuming a particular streaming transport, route, or protocol upgrade. Check visible Codewhale errors, verify that both tests use the same process, and stop the tunnel while investigating unexpected session or approval behavior.

The tunnel later stops responding

Check each dependency in sequence: the remote browser, public address, tunnel state, Localtonet client, protective boundary, local Codewhale listener, Codewhale engine, and model provider. Host sleep, a stopped process, an expired access-control session, or a disconnected client can interrupt the chain.

Frequently asked questions