Build the OpenCodex development branch locally, confirm the dashboard, and then make it remotely reachable
OpenCodex is a self-hosted LLM proxy that serves its HTTP API and web dashboard from the same local service. This installation-first guide walks through cloning the official repository, installing its dependencies with Bun, starting the source build, and verifying the dashboard locally. After the local deployment works, we show how to connect it to a Localtonet HTTP tunnel as a separate remote-access step. We also cover port detection, tunnel lifecycle, and the security implications of publishing an administrative dashboard.
What you are installing
OpenCodex is a local proxy designed to translate requests between coding clients and multiple LLM provider formats. Its documented capabilities include streaming responses, tool calls, reasoning tokens, and image handling. The proxy and its browser-based management dashboard are served through one local HTTP port. This guide covers the project maintained in the lidge-jun/opencodex repository, not other similarly named repositories or packages.
Running OpenCodex from source is different from installing its published npm package. The npm quick start requires Node.js 18 or newer and installs @bitkyc08/opencodex globally. By contrast, the official source workflow clones the repository and uses Bun to install dependencies and execute the TypeScript CLI entry point. A source installation follows the latest development branch, so it can include changes that have not reached a published package.
Installing from the repository is appropriate when you want to inspect the code, contribute changes, or test the latest development work. It can also expose you to unreleased changes and behavior that differs from the latest npm release. For a production-oriented deployment, review the current project documentation and release notes before choosing between a source checkout and the published package.
Prerequisites and deployment choices
The official source instructions use Git to clone the repository and Bun to install and run it. The documented source workflow is available for macOS, Linux, and Windows PowerShell. Ensure that Git is available before beginning. On macOS and Linux, the documented Bun installation command places the executable under the user’s home directory and the subsequent commands invoke it using that path. Windows PowerShell uses bun after running the Bun installer.
OpenCodex also needs access to whichever LLM providers you configure. Provider credentials, OAuth sessions, account details, and model choices are configured separately from the source installation. Do not paste credentials into shell history, commit them to the cloned repository, or embed them in a Localtonet tunnel configuration.
@bitkyc08/opencodex globally and requires Node.js 18 or newer. The npm package bundles the Bun runtime automatically.
http://localhost:10100, although an unpinned start can select another free port if that port is occupied.
Install OpenCodex from source on macOS or Linux
Run these commands from a normal user account. The commands install Bun using its official installer, clone the OpenCodex repository, install project dependencies, and start the development checkout. Review downloaded installation scripts according to your organization’s software installation policy before executing them.
Install Bun
Use the Bun installer documented by OpenCodex. This is required for the source workflow even though the published npm package bundles its own Bun runtime.
curl -fsSL https://bun.sh/install | bashClone the official OpenCodex repository
Clone the repository identified in the project’s installation documentation, then enter the new checkout.
git clone https://github.com/lidge-jun/opencodex.git
cd opencodexInstall the project dependencies
Invoke the Bun binary at the path used by the documented macOS and Linux source procedure.
~/.bun/bin/bun installStart OpenCodex from the checkout
Run the TypeScript CLI entry point with the start action. Keep this terminal open while performing the first local verification.
~/.bun/bin/bun run src/cli/index.ts startInstall OpenCodex from source on Windows
The Windows source workflow uses PowerShell. Run the commands in a location where your user account can create and modify the repository directory. The documented workflow does not require WSL.
Install Bun from PowerShell
Run the Bun PowerShell installer documented by the OpenCodex project. Review your execution policy and organizational controls before running a remote installation script.
irm bun.sh/install.ps1 | iexClone the repository
Retrieve the official source checkout with Git and move into its directory.
git clone https://github.com/lidge-jun/opencodex.git
cd opencodexInstall dependencies
Use Bun to resolve and install the dependencies declared by the checkout.
bun installStart the source build
Start the proxy and dashboard through the project’s TypeScript CLI entry point.
bun run src/cli/index.ts startVerify the local dashboard before creating a tunnel
Open http://localhost:10100 in a browser on the same computer. A successful response confirms that the OpenCodex process is running and that its dashboard is reachable locally. Complete this test before adding any remote-access layer. If the page does not load, inspect the startup output rather than assuming that Localtonet or the network is responsible.
Port 10100 is the documented default, but it is not safe to assume that every unpinned start will use it. If that port is already occupied, OpenCodex may select another available port. Read the process output and confirm the actual listening address. The same confirmed port must later be used as the Localtonet HTTP tunnel’s local target.
A tunnel pointed at 10100 will not reach OpenCodex if the process selected a different port. Verify the dashboard in a local browser and record the active port first. If OpenCodex chooses a new port after a later restart, update the tunnel target or adjust the OpenCodex configuration using currently documented project options.
What successful local verification proves
A working local dashboard proves that the source checkout started, the HTTP listener is active, and the browser can reach it on the host. It does not prove that a provider is fully configured or that every routed model works. Provider setup and request testing should be completed according to the current OpenCodex dashboard and provider documentation.
OpenCodex exposes management functions through the dashboard, including provider configuration, model selection, account management, OAuth status, and request information. Treat it as an administrative interface rather than a public website. Verify what authentication and authorization protections your current OpenCodex version provides before publishing it.
Choose the correct Localtonet connection type
OpenCodex serves an HTTP dashboard and API, so an HTTP tunnel is the natural match for browser-based remote access. With Localtonet, the client on the OpenCodex host establishes an outbound connection to one of our relay servers. The tunnel provides a public address without requiring inbound router port forwarding, a public IP address, firewall changes, or VPN setup.
| Localtonet option | Target behavior | Fit for this tutorial |
|---|---|---|
| HTTP tunnel | Points to a local HTTP service using an IP address and port and serves it from a public HTTPS address. | Appropriate for the OpenCodex dashboard and HTTP API. |
| TCP tunnel | Forwards a raw TCP service to a public host and port. | Not needed for the documented browser dashboard workflow. |
| File Server | Publishes a local folder path rather than an HTTP application port. | Not appropriate for an already running OpenCodex web service. |
| VPN Manager | Creates a private mesh VPN with firewall rules and can bridge local LANs. | A separate private-network approach, not the standard HTTP tunnel described here. |
Connect the verified OpenCodex service with Localtonet
Only begin these steps after the dashboard works locally. Exact available relay servers, regions, process options, and plan availability can change, so select values shown in the current Localtonet dashboard rather than copying hardcoded values from a tutorial. Keep the device authentication token private because it identifies the client device that runs the tunnel.
Install and run the Localtonet client
Install our client on the computer running OpenCodex, or on a device that can reach the OpenCodex listener. Keep the client running because it establishes the outbound connection used by the tunnel.
Authenticate and select the device
Use the device-specific authentication token through the supported Localtonet workflow, then select that connected device for the tunnel. Never place the token in documentation, source control, screenshots, or shared command history.
Select an available relay server
Choose a server or region currently offered in the dashboard. Do not hardcode a server code from an old guide because available values can vary by product state, deployment, or plan.
Create an HTTP tunnel to the verified local target
Configure an HTTP tunnel using the local IP address reachable from the client and the port confirmed during local verification. If the client and OpenCodex run on the same host, use the appropriate loopback target shown by your working local setup. Use the actual OpenCodex port, which may differ from 10100.
Start the tunnel
Creating a tunnel does not start it. Press the Start button and wait until the selected client and tunnel are connected. The tunnel is available only while the client remains connected and the tunnel is running.
Test the assigned public address
Open the assigned public HTTPS address from a separate browser or network and confirm that it reaches the expected OpenCodex interface. Stop or delete the tunnel when remote access is no longer required.
For the current product workflow and interface details, consult our Localtonet documentation while configuring the tunnel. HTTP process types can provide a random subdomain, a supported custom subdomain, or a custom domain. Because custom-domain DNS requirements can change, verify the current instructions before configuring DNS.
The OpenCodex dashboard can expose operational information and provider-management functions. Before sharing its public address, confirm the access controls supported by your current OpenCodex and Localtonet configuration. Use authentication, least privilege, IP restrictions, and other available safeguards where applicable. Do not treat an unguessable URL as authentication, and do not expose a dashboard containing active credentials unless its protections have been reviewed.
Operational checks and troubleshooting
The local page works but the public address does not
Confirm that the Localtonet client is connected, the HTTP tunnel has been started, and its target exactly matches the locally verified address and port. Remember that saving or creating a tunnel is not the same as starting it. Also confirm that OpenCodex is still running in the source terminal.
OpenCodex moved to another port
If the default port was occupied, the process may have selected another free port. Read the current startup output, test that port locally, and update the HTTP tunnel target. Recheck this after restarting OpenCodex if the selected port was not pinned through a documented project configuration.
The public dashboard opens but provider requests fail
Tunnel reachability and provider functionality are separate. A working public dashboard confirms that HTTP traffic reaches OpenCodex, but it does not validate provider credentials, OAuth state, model mappings, provider policies, or upstream availability. Diagnose those items within OpenCodex and the relevant provider documentation.
The public address stopped responding
A Localtonet tunnel remains available only while the chosen client device is connected and the tunnel is running. Also verify that the OpenCodex process itself has not exited. For unattended operation, consult OpenCodex documentation for its supported background-service workflow rather than inventing a custom startup command.
Frequently asked questions
Does installing OpenCodex from source require Node.js?
The documented source workflow uses Bun to install dependencies and run the TypeScript CLI directly. Node.js 18 or newer is explicitly required for the published npm package workflow. Follow the current project documentation if its source prerequisites change.
Is the OpenCodex dashboard always on port 10100?
No. 10100 is the documented default, but an unpinned start can choose another free port when that port is already occupied. Verify the actual listener from the startup output and test it locally before configuring Localtonet.
Do I need router port forwarding for the Localtonet HTTP tunnel?
No. Our client establishes an outbound connection to a Localtonet relay server, so the workflow does not require inbound router port forwarding, a public IP address, firewall changes, or VPN setup.
Does creating a Localtonet tunnel make it immediately available?
No. The tunnel must be started with the Start button. It remains available only while the selected client device is connected and the tunnel is running. You can stop or delete it when remote access is no longer needed.
Should I expose the OpenCodex dashboard publicly without authentication?
No. Treat the dashboard as an administrative interface because it can include provider configuration, account information, OAuth status, model controls, and request data. Review the authentication and access restrictions available in your current deployment, apply least privilege, and expose it only to intended users.
Can the Localtonet client run on a different device?
Yes, provided that the client device can reach the OpenCodex local IP address and port. If OpenCodex listens only on a loopback address, a different device will not ordinarily be able to reach that listener. Change binding behavior only through options documented by OpenCodex, and consider the resulting network exposure before doing so.
Connect your verified OpenCodex dashboard
After OpenCodex is installed, running, and tested locally, create a Localtonet account and configure an HTTP tunnel to the confirmed listener. Keep the device token private, start the tunnel only when needed, and protect the dashboard with appropriate access controls.
Get Started Free →
