Self-Host codebase-memory-mcp with Localtonet

What this workflow runs and exposes

codebase-memory-mcp is an open-source structural-analysis backend for MCP-compatible coding agents. It parses a repository and creates a persistent knowledge graph containing entities and relationships such as functions, classes, call chains, HTTP routes, and cross-service links. An MCP client can query that graph instead of repeatedly opening and searching individual files for every structural question.

The project is not a chatbot and does not contain an embedded large language model. Your coding agent remains the intelligence layer. codebase-memory-mcp supplies the agent with indexed structural information and graph-query tools. The native installation does not require Docker, a separate language runtime, a hosted analysis service, or a codebase-memory-mcp API key.

Current project documentation states that processing happens locally and that the native executable serves a built-in 3D graph visualization at localhost:9749. The current repository identifies this UI as part of the binary itself. That resolves the older ambiguity around a separate UI variant: the standard installer and standard platform archives documented below install the executable that serves the UI. You do not need to select a separate UI archive or add an undocumented installer argument for this workflow.

Separate the MCP service from the graph UI

This distinction is essential. The coding agent communicates with codebase-memory-mcp through its configured MCP integration. Separately, the executable serves a browser interface on local port 9749. This tutorial tunnels only that browser interface.

Port 9749 should not be treated as a remote MCP endpoint merely because it belongs to an MCP server. The available project documentation identifies it as the graph visualization endpoint, not as a documented network transport for remote MCP clients. If your objective is to connect an MCP client running elsewhere, follow a transport specifically supported by the project and your client rather than assuming the graph UI port provides that capability.

Prerequisites and host planning

Choose a host that can read the repository and remain active while you use the MCP integration or graph UI. A development workstation is appropriate for temporary use. A longer-running development machine requires additional planning around updates, account permissions, repository access, sleep behavior, and service lifecycle.

• A supported macOS, Linux, or Windows host matching an available release architecture.
• A user account permitted to download software, execute the installer, and update the relevant client configuration.
• An MCP-compatible coding agent supported by the installer or configurable through documented MCP settings.
• A local source repository that the installation account is authorized to read.
• A browser on the host for testing localhost:9749.
• For remote access, a Localtonet account and a Localtonet client running on the graph host or another device that can reach it.
• A device-specific Localtonet authentication token obtained from your account and handled as a secret.

Prefer the same host for Localtonet

The project documents the graph UI on localhost. Installing our client on that same computer is therefore the clearest topology. On that host, the Localtonet client can target the same local service that the browser has already verified.

If our client runs on another computer, localhost:9749 refers to that other computer, not to the codebase-memory-mcp host. A separate-device arrangement works only if the graph service is intentionally listening on a network address reachable from the Localtonet client device. The current project evidence does not establish that as the default configuration, so this tutorial does not assume it.

Review installation trust

The macOS and Linux quick-start command downloads a script and passes it directly to Bash. That is convenient, but the retrieved script executes with your user permissions. If your security policy requires inspection, download the script first, review the saved file, and execute that reviewed copy.

The Windows procedure already separates downloading from execution and includes an optional review step. Manual release installation provides another review-friendly path because you select an archive from the project’s current release page, extract it, and run the included platform installer.

Install the current UI-enabled codebase-memory-mcp release

Use one installation path, not all of them. The current project repository documents two installer options: --skip-config for binary-only installation and --dir=<path> for a custom location. Neither option is needed for the normal workflow below. In particular, the current repository identifies the graph UI as built into the standard executable, so no separate UI package selection is required.

The project website and repository can change independently. Before installing a future release, compare the current project documentation, repository quick start, and release notes. If a future release introduces a distinct UI package again, use the exact syntax published for that release rather than carrying forward an old option.

macOS and Linux: standard installer

The current repository quick start uses this command for the native installation, including the built-in graph visualization:

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

Read the installer output before proceeding. It should identify installation or configuration failures such as an unsupported architecture, a failed download, insufficient permissions, or an MCP client configuration problem.

For a review-first workflow, download the same script, inspect it, and run the local copy:

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh -o install.sh
less install.sh
bash install.sh

Review the file before the final command. Do not assume a previously downloaded installer still matches the current release or documentation.

On macOS, the project installer handles the quarantine behavior described by the project. If the executable remains blocked, do not disable platform protections globally. Verify the download source, review the installer output, and follow the platform guidance attached to the current project release.

Windows: standard PowerShell installer

Open PowerShell in a directory where you can save and review the installer. The current project workflow downloads install.ps1, optionally opens it for inspection, removes the downloaded-file restriction, and executes it:

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1" -OutFile "install.ps1"
notepad .\install.ps1
Unblock-File .\install.ps1
.\install.ps1

The standard Windows installation receives the same current executable capability, including the graph UI. There is no separate Windows UI archive identified by the current repository documentation.

If PowerShell reports a script execution policy error, the project documents a process-scoped bypass:

Set-ExecutionPolicy -Scope Process Bypass
.\install.ps1

A process-scoped setting applies only to the current PowerShell process. On a managed computer, organizational policy takes precedence. Do not override an administrator-controlled restriction without approval.

Manual installation from a release archive

Open the project’s latest release and select the standard archive matching the host operating system and processor architecture. Current documentation uses codebase-memory-mcp-<os>-<arch>.tar.gz for macOS and Linux, and a ZIP archive for Windows. The normal platform archive contains the executable with the built-in graph UI and includes the corresponding installer script.

On macOS or Linux, change to the download directory, extract the archive you actually downloaded, and run its included installer:

tar xzf codebase-memory-mcp-<os>-<arch>.tar.gz
./install.sh

Replace the placeholders with the exact operating-system and architecture values shown on the release page. Do not type the angle brackets literally. If the release asset name differs from the documented pattern, use the actual downloaded filename.

On Windows amd64, the current manual-install documentation uses the standard Windows ZIP:

Expand-Archive .\codebase-memory-mcp-windows-amd64.zip -DestinationPath .
Unblock-File .\install.ps1
.\install.ps1

If a newer release changes the filename or adds another Windows architecture, select the exact asset published for that release. Do not rename an incompatible archive merely to match the example.

Alternative package channels

The project currently lists npm, pip, Homebrew, Scoop, Winget, Chocolatey, AUR, and go install as additional installation routes. Each channel has its own package name, permissions, update schedule, and packaging decisions. This tutorial uses the release-owned installer and archives because those are the cross-platform paths for which the current UI behavior is explicit.

If you choose another package channel, verify that its current package includes the same UI-serving executable before continuing. A package being listed by the project does not establish that every channel publishes every release at the same time.

Configure and restart the MCP client

The standard installer attempts to configure detected coding-agent clients. The current project documents automatic and conditional client surfaces, but behavior still depends on the client, operating system, existing configuration, and whether the installer can find the required markers or paths.

Automatic detection is not the same as universal configuration. Some clients require an existing configuration path, an explicit option, or manual setup through their own interface. If the installer does not configure your client, use the current client-specific instructions from the project and the MCP configuration format published by that client. Do not infer one client’s JSON schema or configuration path from another.

The project states that the installer writes to agent configuration files. Review those changes if the machine has customized MCP settings. Preserve unrelated server entries and client preferences, and keep a backup if that is part of your normal configuration-management process.

If you deliberately installed with --skip-config, automatic client configuration is not expected. Complete the manual setup for your exact client before attempting to index a repository.

Index the intended project

Open the coding agent with the target repository as its active project or workspace. The operating-system account running the agent must be able to read that repository. Avoid launching from a broad parent directory containing unrelated projects or confidential material outside the intended indexing scope.

The project’s documented first request is:

Index this project

Send that request to the MCP-enabled coding agent. The agent should invoke codebase-memory-mcp for the current repository. The first index can require more time and memory than later incremental work because the initial graph must be constructed.

Completion time depends on repository size, language mix, file complexity, available memory, hardware, and whether an older index requires migration. Treat benchmark numbers published for other repositories as project measurements, not as deadlines or guarantees for your codebase.

Confirm the workspace before trusting the result

A technically successful index can still target the wrong directory. This can happen when an application restores an older workspace, a terminal starts from the home directory, or a multi-root client selects an unexpected folder.

Ask a simple structural question whose answer you already know, such as the location of a major entry point, a known class, or a central module. The response should match the intended repository. This checks the client configuration, local server, working directory, and graph data together.

Verify the graph UI locally before exposing it

Keep the coding agent and server process active. On the same computer, open the documented graph endpoint:

localhost:9749

The current project identifies this endpoint as the built-in 3D graph visualization served by the executable. A successful check should display the interface and graph data for the intended repository. Do not stop after confirming that some web page responds. Inspect the project identity, graph contents, and basic navigation.

Check for a port conflict

If another application already owns port 9749, the graph UI may fail to start or the browser may show an unrelated service. The available project evidence establishes the default port but does not establish a supported port-changing option for this tutorial. Identify the conflicting process and decide which application should use the port. Use a different graph port only if your exact installed release documents the required configuration.

Do not create the Localtonet tunnel while this local check is failing. A public tunnel forwards requests to a target, but it does not start the UI, add missing application features, rebuild the graph, or resolve a local listener conflict.

Expose only the working graph UI with Localtonet

After the graph works locally, an HTTP tunnel can make that browser interface reachable from outside the host network. Our client establishes an outbound connection to a Localtonet relay server, so the workflow does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address.

Before starting, create a Localtonet account if needed and install the current Localtonet client for your operating system using the resources presented in your account. Client installation details can vary by operating system and client release, so use the current download and installation instructions rather than copying an unverified command from an older article.

The configuration sequence below follows our documented HTTP tunnel workflow. You can also consult the current Localtonet HTTP tunnel documentation while working in the dashboard.

Test the public address from outside

Open the assigned HTTPS address from a separate device or network. A mobile browser using cellular data is one practical test. Compare the result with the locally verified graph.

If the public address fails while localhost:9749 remains healthy, focus on the Localtonet client connection, selected device, relay selection, local address, port, and tunnel state. If the public page opens but shows an unexpected graph, the network path is probably working and the active repository or index requires attention.

The endpoint remains usable only while every dependency is active: the host is awake and connected, codebase-memory-mcp is serving the UI, the Localtonet client is connected, and the tunnel is running.

Secure the graph and public access window

The current evidence does not establish built-in authentication, per-user authorization, or a public-deployment access-control model for the codebase-memory-mcp graph UI. Treat the interface as potentially unauthenticated unless the exact installed release explicitly documents and demonstrates otherwise.

Apply least exposure

• Keep the graph local unless remote browser access is genuinely required.
• Review the graph before sharing it with another person.
• Expose only the UI port, not the repository directory or unrelated services.
• Start the tunnel immediately before the remote session.
• Share the URL only through an approved channel.
• Stop or delete the tunnel as soon as the session is complete.
• Do not publish the URL in issues, logs, screenshots, documentation, or source files.
• Run indexing with an account limited to the repositories it needs to read.
• Follow repository licensing, customer confidentiality, and organizational security requirements.

Protect the Localtonet device token

A Localtonet authentication token identifies the device that runs the tunnel. Obtain it from your account and handle it as a credential. Never use a token copied from an example, place it in a public command transcript, or expose it in a dashboard screenshot. If disclosure is suspected, use the account controls available to replace or revoke the affected credential.

The absence of a codebase-memory-mcp API key does not make the surrounding workflow credential-free. Your coding agent may use separate provider or account credentials. Keep those credentials out of application output, graph captures, tunnel configuration, and troubleshooting material.

Operate, stop, and upgrade the installation

Understand the runtime chain

Remote availability depends on several separate components. The coding-agent or server process must keep the graph UI running. The host must remain awake and connected. The Localtonet client must stay connected to its selected relay, and the tunnel must remain started.

Creating either the local index or the tunnel configuration does not make the complete chain permanent. If the host sleeps, the process exits, the client disconnects, or the tunnel is stopped, the public UI becomes unavailable.

Stop exposure when the session ends

Stop the Localtonet tunnel first so that the public route is removed before you change or stop the application. You can then close the coding agent or server process according to your normal workflow. Delete the tunnel if you do not expect to reuse the configuration.

Read release notes before upgrading

Project upgrades can change installation behavior, client support, output contracts, or the persistent index format. Review the notes for the version you are installing rather than assuming that every update is an in-place binary replacement with no graph changes.

The v0.11.0 release notes, for example, document a one-time full reindex for indexes created by v0.10.8 or earlier. File-node identity changed so filenames with different extensions could remain distinct. The release stamps the on-disk format and performs one full rebuild because an older collided database cannot reconstruct information it previously combined.

That first post-upgrade run can take as long as a cold index, especially for a large monorepo. After the one-time rebuild, incremental indexing resumes. The release notes state that ADRs and index metadata are preserved during this process.

Troubleshooting installation, indexing, and remote access

The coding agent cannot find the MCP server

Restart the agent completely and review the installer output. Confirm that the installer detected the intended client and that the executable exists where the client expects it. If you used --skip-config, automatic MCP configuration was intentionally omitted.

For conditional or manual clients, use the current client-specific instructions. Do not copy a configuration path or schema from a different application merely because both support MCP.

The indexing request does nothing

Confirm that the agent shows codebase-memory-mcp as available and that the active workspace is the intended repository. Reissue Index this project after restarting the client. Inspect startup, filesystem permission, memory, and repository-path errors before reinstalling.

The graph UI does not open on localhost:9749

Keep the agent and server process active. Confirm that installation completed and that the repository was indexed. The current standard executable includes the UI, so a separate UI package should not be required for the documented installer and release-archive routes.

Check whether another process owns port 9749. If a conflict exists, stop the unintended listener or follow a port configuration method explicitly documented by your installed project release. Do not invent an environment variable or command-line flag.

The browser shows the wrong application

Another process may be listening on port 9749. Stop the Localtonet tunnel while investigating so the unintended service is not left publicly reachable. Identify the listener, restore the graph UI, and repeat local verification before restarting the tunnel.

The graph is empty or belongs to another project

Return to the coding agent and inspect the active workspace. Open the intended repository and request indexing there. Ask a structural question about a known module before retesting the graph interface. Changing the tunnel cannot correct the active graph.

The first run after an upgrade is unusually slow

Review the release notes for an index-format migration. Version 0.11.0 specifically requires a one-time full rebuild for indexes created by v0.10.8 or earlier. Let the rebuild finish unless the process reports a concrete failure.

Windows blocks the script

Review the downloaded installer and apply the documented Unblock-File step. If script execution policy blocks it, the project documents a process-scoped bypass. Managed-device policy still takes precedence.

The project also discusses antivirus false positives for release binaries. Do not approve a detected file solely because false positives are possible. Confirm the release source, use the project’s current integrity information, and follow your organization’s malware-review process.

The local UI works but the public address fails

Confirm that our client is connected, the intended device is selected, an available relay is selected, and the tunnel has been started. Creating a configuration is not the same as starting it.

Recheck the target address and port. The port for this workflow is 9749. If our client runs on another machine, its localhost cannot reach the development host unless the service is deliberately available over the local network.

The remote address stops working later

Check every lifecycle dependency: the host must be awake, codebase-memory-mcp must still be serving the UI, our client must remain connected, and the tunnel must remain running. A failure at any point interrupts the public route.

Frequently asked questions