Install WebCodex for ChatGPT and Claude with Localtonet

What this guide covers and what is currently verified

This article covers the yyjeqhc/webcodex repository. Its stated purpose is to give cloud AI agents access to repositories, Git checkouts, compilers, tests, and other development tools on machines controlled by the user. It is not the similarly named xq3427/WebCodex npm project. Do not mix commands, package names, credentials, or connection procedures from those two repositories.

WebCodex describes an architecture in which an MCP client communicates with a WebCodex Server over HTTPS. WebCodex then coordinates work on the machine that owns the repository and its toolchain. A single-computer installation can place Desktop, CLI, Server, and Runner on the workstation containing the project. A multi-computer deployment can place the Server on one machine and Runners on machines that own repositories.

Localtonet addresses the remote network path rather than the WebCodex application lifecycle. Our client establishes an outbound connection to a Localtonet relay server and publishes a configured local HTTP target through a public HTTPS address. This does not install WebCodex, start its Server or Runner, register a project, or configure WebCodex authentication. The tunnel is available only while the selected Localtonet client is connected and the tunnel is running.

The repository links its Unified installation, Using Desktop, MCP, Authentication, Deployment, Security, and Troubleshooting documentation from the WebCodex documentation index. Review those current links for the exact revision you intend to evaluate. The repository also provides a dedicated WebCodex security model.

Release v0.4.6 wording

The WebCodex v0.4.6 release says that it is intended to be a long-lived stable release and that its public tool names are expected to remain stable. That statement concerns the release and its tool names. It does not establish that all six unified installer targets have completed native build and installation acceptance.

The release page reports 17 assets, but the supplied release snapshot does not expose their filenames or establish which assets correspond to accepted unified installers. For that reason, this article does not fabricate artifact names or claim that a particular Windows, macOS, Debian, or Ubuntu package is available. Select an installer only when the release page lists the exact artifact and the current validation documentation accepts that platform and architecture.

Prerequisites and deployment decisions

Start by deciding which machine will run the WebCodex Server and which machine owns the repository. A single-computer setup is easier to evaluate because the Server, Runner, repository, and Localtonet client can share one host. In a multi-computer setup, the Localtonet client may run on the Server host or another device, but it must be able to reach the configured WebCodex listener.

What you need

• A machine matching an artifact that is actually published and accepted for evaluation by the current WebCodex documentation.
• A repository or project directory that you are prepared to authorize.
• Version control so that changes can be reviewed, committed, or reverted.
• An operating-system account with only the filesystem and command permissions required by the project.
• A documented WebCodex authentication choice suitable for remote access.
• A Localtonet account and client on a device that can reach the WebCodex listener.
• Claude Code, ChatGPT, or another MCP client with a currently supported remote HTTP connection surface.

Do not infer architecture from the operating system alone. On Windows and Linux, check whether the system is x64 or arm64. On macOS, distinguish Apple silicon from Intel hardware. Then compare that result with the complete asset name and validation entry published by WebCodex.

Prepare the repository

• Commit or stash unrelated changes before connecting an AI client.
• Confirm that private keys, access tokens, environment files, cloud credentials, and production data are outside the registered project or adequately protected.
• Review ignored and untracked files, not only committed Git content.
• Run the intended tests and development tools under the same account that will run WebCodex.
• Remove deployment, publication, infrastructure, or destructive database privileges that are unnecessary for the task.

Install or evaluate the WebCodex unified package

The repository describes the unified installer workflow as under development. Therefore, installation begins with artifact and acceptance verification, not with an assumed download command. If the matching installer has not been published and accepted, stop. Use only a deployment path documented by WebCodex for the exact revision, such as its advanced self-hosting, runtime archive, Docker, source-preview, or temporary trial instructions.

Starting WebCodex

The repository says the unified package includes Desktop, CLI, Server, and Runner. Open Desktop first and use its current status surfaces to determine whether the local Server and required Runner are active. Do not assume that launching the graphical application proves the MCP listener is running.

The supplied evidence does not establish a universal service name, CLI startup command, background-service command, default port, or installation directory. It would be unsafe to invent those values. If Desktop does not expose an active Server and Runner, use the startup sequence in the current Using Desktop or deployment documentation linked from the repository's documentation index.

Register a project and identify the MCP endpoint

Installing WebCodex does not automatically authorize every local directory. Register only the repository required for the intended task. A project root should normally be the repository itself, not a home directory, entire drive, broad workspace parent, or shared folder containing unrelated projects.

Project registration checklist

1. Open the project management area in the installed WebCodex Desktop version.
2. Choose the current control for adding or registering a project.
3. Select the narrow repository root you prepared earlier.
4. Associate it with the local Runner that can access that path, if the deployment requires a Runner selection.
5. Confirm that the project appears in Desktop and that WebCodex can inspect it without granting access to its parent directory.

Exact control labels can change between WebCodex revisions, and the supplied evidence does not expose the current interface fields. Follow the current Using Desktop documentation for the installed revision rather than selecting a similarly named global workspace or broad filesystem root.

Discover the exact listener and path

Use the Desktop connection view, MCP view, runtime output, or documented configuration for the installed revision to copy the complete local MCP URL. Do not infer a default port or assume the path is /mcp. Record these parts separately:

• The local scheme, which may be HTTP or HTTPS according to the WebCodex configuration.
• The listener address or hostname.
• The local TCP port.
• The complete MCP path after the host and port.
• The authentication mode and credential requirements.

The local transport and public transport are separate. For example, Localtonet can present a public HTTPS URL while forwarding to a local HTTP listener. That does not mean the local service has become HTTPS. Conversely, if WebCodex requires HTTPS between the Localtonet client and the local target, verify that the selected Localtonet tunnel configuration supports that exact upstream behavior before proceeding.

Verify WebCodex locally before exposing it

Local verification separates application failures from tunnel failures. A Localtonet tunnel forwards requests to the target you configure. It cannot start WebCodex, repair authentication, choose the MCP path, or register a repository.

Reproducible local test procedure

1. Confirm in WebCodex Desktop that the required Server and Runner components are active.
2. Copy the exact local MCP URL from the installed configuration rather than reconstructing it from memory.
3. Configure the authentication method documented by WebCodex for that endpoint.
4. Connect using a compatible local MCP client or WebCodex's documented MCP diagnostic workflow.
5. Confirm that MCP initialization and tool discovery complete successfully.
6. Request a harmless read operation inside the registered project, such as inspecting Git status or reading a non-sensitive file.
7. Attempt no destructive changes during the connectivity test.
8. Confirm through WebCodex activity, Runtime Console, or workflow evidence that the operation reached the intended Runner and project.
9. Verify that an unrelated directory is not registered or exposed as a project.

The test is successful only when authentication, MCP initialization, tool discovery, project selection, and a harmless project operation all work. A browser response from the host is not enough. MCP requests can require specific methods, headers, session behavior, and protocol messages that an ordinary browser navigation does not provide.

Expose the verified endpoint with a Localtonet HTTP tunnel

The following sequence follows our documented HTTP tunnel lifecycle. The Localtonet-specific behavior in this article was checked against current product context on 2026-08-20. Available relay servers, regions, options, and plan availability can change, so select values displayed by the current dashboard.

See the Localtonet HTTP tunnel documentation for the current dashboard workflow. Build the remote MCP URL by combining the assigned public HTTPS origin with the exact path copied from WebCodex.

Connect Claude Code or an eligible ChatGPT surface

Claude Code remote HTTP connection

Anthropic documents remote HTTP as the recommended option for connecting Claude Code to remote MCP servers. Use the complete public WebCodex URL:

claude mcp add --transport http webcodex "PASTE_THE_EXACT_PUBLIC_MCP_URL_HERE"

Replace the placeholder with the Localtonet public HTTPS origin plus the exact WebCodex MCP path. The name webcodex is a local connection label. If WebCodex requires an authorization header, follow the authentication instructions for both products and avoid placing the secret in shell history where possible.

Anthropic's Claude Code MCP reference also explains header-based authentication and JSON configuration. A URL-based JSON entry must include an HTTP-compatible type. Claude Code treats an entry with a URL but no type as an invalid stdio configuration.

After adding the connection, inspect Claude Code's MCP status, confirm tool discovery, and request a narrow read-only operation. Compare the result with WebCodex's Runtime Console or activity view before allowing modifications.

ChatGPT connection scope and restrictions

WebCodex states that it can connect ChatGPT and other MCP clients to local development environments. However, the official OpenAI material supplied for this revision does not establish one universal ChatGPT button sequence, plan requirement, workspace entitlement, or authentication flow for arbitrary self-hosted remote MCP servers.

OpenAI documents MCP across several product surfaces, including APIs, agents, tools, integrations, plugins, and ChatGPT-related experiences. Those surfaces are not interchangeable. The presence of MCP documentation does not prove that every ChatGPT account can add an arbitrary remote MCP URL directly in the consumer chat interface.

Before attempting a ChatGPT connection, consult the current ChatGPT Model Context Protocol documentation and the OpenAI developer MCP documentation. Confirm all of the following:

• The ChatGPT or OpenAI surface you are using supports a custom remote MCP server.
• Your account or workspace is eligible for that feature.
• A workspace administrator has permitted the connection where administrative controls apply.
• The surface accepts the transport exposed by WebCodex.
• Its authentication options are compatible with the mode configured in WebCodex.
• The connection can use the complete Localtonet HTTPS URL and WebCodex MCP path.

If the current OpenAI interface presents an approved remote MCP connection form, enter the complete public URL, configure authentication using the supported mechanism, and verify tool discovery with a harmless project request. If the control is absent or the workspace blocks custom connections, stop. Do not expose additional ports, disable WebCodex authentication, or switch to another repository's tunnel workflow in an attempt to make the control appear.

Refresh tools after upgrading to v0.4.6

WebCodex v0.4.6 includes a specific upgrade instruction. If you previously installed or connected an older release, reconnect the application or MCP connection and refresh its tool schema. Existing conversations or cached client schemas can continue to expose retired tool names. Start a new conversation if refreshing and reconnecting do not update the visible tools.

Security and authority boundaries

WebCodex can read and modify files and execute commands inside configured project boundaries. Repository location alone does not prevent selected content from leaving the machine. Requested file excerpts, command output, Git information, and other tool results may be returned to the connected AI client.

Apply least privilege at every layer

• Operating-system account: Run WebCodex with only the permissions required by approved projects and tools.
• Project registration: Register the narrowest repository roots possible.
• Repository hygiene: Keep credentials out of prompts, Git, source files, logs, fixtures, and generated output.
• WebCodex authentication: Use the mode documented for the installed version and protect its credentials.
• Client eligibility: Connect only approved AI clients and workspaces.
• Tunnel lifecycle: Start remote access when required and stop or delete it afterward.
• Human review: Inspect Git diffs, commands, tests, jobs, and runtime evidence before accepting changes.

Prompt injection is relevant whenever an AI client reads repository files, issue descriptions, downloaded documents, dependency output, or external pages. Treat retrieved content as untrusted data. Closely review requests to reveal credentials, change access controls, download executables, publish packages, modify infrastructure, or run destructive commands.

Keep secrets separate

A Localtonet device token identifies the client that runs the tunnel. A WebCodex credential controls access to the application. An OpenAI or Anthropic credential belongs to its respective client or account. These secrets serve different purposes. Do not reuse them, embed them in the public URL, commit them to a repository, or copy them into AI prompts.

Routine operation, shutdown, and upgrades

Before each remote session

• Confirm the intended branch and understand the existing working-tree state.
• Start WebCodex and confirm Server and Runner status.
• Verify that only the intended project root is registered.
• Run the local MCP test with authentication.
• Start the Localtonet client and explicitly start the tunnel.
• Connect the approved remote client and repeat a harmless tool-discovery test.

During the session

Monitor WebCodex's available Runtime Console, Workflow Session evidence, Jobs, activity, Git status, and diffs. Long-running work should remain observable. Investigate unexpected commands, access outside the requested project, unexplained network activity, or changes unrelated to the task.

At the end of the session

• Review the final Git diff and untracked files.
• Run the project's normal tests and checks.
• Commit accepted work or revert unwanted changes.
• Disconnect the remote MCP client when appropriate.
• Stop the Localtonet tunnel.
• Delete the tunnel if the public endpoint should not be reused.

Creating, starting, stopping, and deleting a Localtonet tunnel are separate lifecycle actions. The public endpoint is available only while the selected device remains connected and the tunnel is running.

Upgrade procedure

Before upgrading WebCodex, preserve the project state and record non-secret configuration details. Confirm that the new release publishes an artifact matching the operating system and architecture, then review its platform acceptance and upgrade notes. Test Server and Runner startup, authentication, local MCP initialization, tool discovery, and project access before restoring the public tunnel.

Do not assume reboot persistence across all unified installer targets. The repository explicitly says this behavior has not been accepted across all three platforms. Test a real restart on the exact operating system and artifact before relying on unattended recovery.

Troubleshooting WebCodex and remote MCP access

No accepted installer is available

A defined target is not proof of a published, accepted installer. Recheck the release assets and current validation checklist. If the matching variant is absent or unaccepted, do not download a similarly named artifact from another project. Use an advanced path documented by WebCodex for the exact revision or wait for an accepted package.

Desktop opens, but the MCP listener does not work

Confirm Server and Runner status independently. Copy the exact scheme, address, port, and path from WebCodex. Verify authentication and inspect the Runtime Console or troubleshooting guidance. A running graphical interface does not prove that the MCP listener initialized.

The local client reaches the host but finds no tools

Check that the client is using the complete MCP path and the correct HTTP transport. Verify authentication and inspect WebCodex activity for the request. If you upgraded to v0.4.6, reconnect and refresh the tool schema. Start a new conversation if an old one retains cached definitions.

The tunnel exists but the public URL is unavailable

Confirm that the selected Localtonet device is connected and the tunnel was explicitly started. Verify that the Localtonet client device can reach the configured IP address and port. An address that works only inside the WebCodex host may not work from a container, virtual machine, or separate tunnel device.

The public origin responds but the MCP connection fails

Compare the public client URL with the verified local URL. The origin changes, but the WebCodex MCP path must remain intact. Recheck transport compatibility and authentication. A response from the public origin alone does not prove that the MCP endpoint initialized.

Claude Code reports a URL configuration error

Use the documented remote HTTP form with --transport http. For JSON configuration, include an HTTP-compatible type. Anthropic documents that a URL with no type is interpreted as an invalid stdio configuration.

ChatGPT has no custom MCP connection control

Confirm the current product surface, account eligibility, workspace policy, and administrator settings using OpenAI's current documentation. Do not change a known-good WebCodex endpoint or weaken authentication because a particular ChatGPT interface does not expose the required feature.

WebCodex can access too many files

Stop the remote session and tunnel. Replace broad project registration with the narrow repository root. Review operating-system permissions, symlinks, mounts, generated workspaces, and tool configuration that may reference locations outside the project.

The setup fails after reboot

Check each component separately: Desktop, Server, Runner, registered project, local MCP connection, Localtonet client, selected device, and tunnel state. Do not assume identical startup or persistence behavior across Windows, macOS, Debian, and Ubuntu targets.

Frequently asked questions