How to Access the Research Vault via the Web UI in Hyperresearch

To access the research vault via the web UI, run hyperresearch serve in your vault directory and navigate to http://127.0.0.1:8080 in your browser.

The jordan-gibbs/hyperresearch project stores research artefacts in a local Vault—a directory-backed SQLite database. The built-in web interface provides a browser-based view of your notes and sources without requiring external services or internet connectivity.

Initialize Your Vault

If you have not already created a vault, initialize one first:

hyperresearch init /path/to/my-vault
cd /path/to/my-vault

This command creates the folder structure (research/notes, research/sources, etc.) and a SQLite database that backs the vault. The Vault class in [src/hyperresearch/core/vault.py](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/core/vault.py) manages this filesystem layout and the database connection.

Start the Web Server

Launch the local server using the CLI:

hyperresearch serve          # Defaults to port 8080

hyperresearch serve --port 8000   # Custom port

The serve command invokes the run_server helper function defined at line 605 in [src/hyperresearch/serve/server.py](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/serve/server.py). This function:

1. Instantiates a Vault object from the current working directory (as demonstrated in the test suite at [tests/test_serve/test_server.py](https://github.com/jordan-gibbs/hyperresearch/blob/main/tests/test_serve/test_server.py#L52)).
2. Starts an HTTP server (HyperresearchServer) bound to the requested port.

When the server starts, it prints the local URL:

Serving Hyperresearch UI at http://127.0.0.1:8080

Navigate the Web Interface

Open the printed address (default: http://127.0.0.1:8080) in any modern browser. The server uses HyperresearchHandler—a BaseHTTPRequestHandler subclass defined at line 365 of [src/hyperresearch/serve/server.py](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/serve/server.py)—to process requests via its do_GET method.

The web UI exposes the following routes:

Path	Content
/	Home page listing all notes and sources with search
/note/<slug>	Rendered Markdown for a specific note (slug derived from filename)
/source/<id>	Details of a bibliographic source (PDF, DOI, URL)
/static/...	CSS and JavaScript assets

You can deep-link directly to content:

http://127.0.0.1:8080/note/experiment-setup
http://127.0.0.1:8080/source/12345

Interact with Vault Content

The web UI provides read-only access to your research. Key interaction patterns include:

• Full-text search — The search box queries the fts5 virtual table in the SQLite database (implemented in [src/hyperresearch/search/fts.py](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/search/fts.py)).
• Folder navigation — The sidebar displays the hierarchical structure of research/notes and research/sources.
• Wikilink resolution — Internal links written as [[note-name]] are resolved on-the-fly by the request handler and converted to clickable navigation links.

To modify vault contents (create, edit, or delete notes and sources), use the CLI commands (hyperresearch note edit, hyperresearch source add, etc.) rather than the web interface.

Code Examples

Launch the Server from a Specific Directory

cd ~/my-research-vault
hyperresearch serve --port 8080

Open a Specific Note Programmatically

Once the server is running, you can open a specific note directly from the terminal:

xdg-open http://127.0.0.1:8080/note/literature-review

Search the Vault Programmatically

While the web UI handles search interactively, you can also query the vault directly in Python:

from hyperresearch.search import search_fts
from hyperresearch.core.vault import Vault

vault = Vault("/path/to/my-vault")
results = search_fts(vault.db, "asyncio", limit=5)

for row in results:
    print(f"{row['title']}: {row['path']}")

This uses the search_fts function defined in [src/hyperresearch/search/fts.py](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/search/fts.py).

Summary

• Run hyperresearch serve to start a local web server that exposes your vault.
• Access the UI at http://127.0.0.1:8080 by default, or specify a custom port with --port.
• The server relies on HyperresearchHandler in src/hyperresearch/serve/server.py to serve routes like /note/<slug> and /source/<id>.
• All vault data is read-only through the browser; use the CLI for write operations.
• Full-text search leverages SQLite FTS5 via the search module in src/hyperresearch/search/fts.py.

Frequently Asked Questions

What is the default URL for accessing the research vault web UI?

By default, the server binds to port 8080 and prints the address http://127.0.0.1:8080 on startup. Navigate to this URL in your browser immediately after running hyperresearch serve to view your vault.

Is the Hyperresearch web UI read-only?

Yes. The web interface provides read-only access to notes and sources. It renders Markdown, resolves wikilinks, and executes full-text searches, but it does not allow editing. You must use CLI commands like hyperresearch note edit to modify vault contents.

How do I view a specific note directly via URL?

Append /note/<slug> to the base URL, where <slug> corresponds to the note filename without extension. For example, http://127.0.0.1:8080/note/my-research-question renders the note stored at research/notes/my-research-question.md.

Can I change the port when starting the web server?

Yes. Pass the --port flag followed by the desired port number when invoking the serve command: hyperresearch serve --port 8000. The run_server function in src/hyperresearch/serve/server.py handles the custom binding and starts the HTTP server on the specified port.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}