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

> Easily access your Hyperresearch vault via the web UI. Simply run hyperresearch serve and navigate to the provided URL for seamless data management.

- Repository: [Jordan Gibbs/hyperresearch](https://github.com/jordan-gibbs/hyperresearch)
- Tags: how-to-guide
- Published: 2026-09-13

---

**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:

```bash
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)](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:

```bash
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](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/serve/server.py#L605) in [[`src/hyperresearch/serve/server.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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)](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](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/serve/server.py#L365) of [[`src/hyperresearch/serve/server.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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:

```text
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)](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

```bash
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:

```bash
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:

```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)](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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/serve/server.py) handles the custom binding and starts the HTTP server on the specified port.