# How to Use Context Hub Offline with Local Documentation Sources

> Use Context Hub offline with local documentation. Configure local directories or download content bundles for air-gapped access without remote CDN calls.

- Repository: [Andrew Ng/context-hub](https://github.com/andrewyng/context-hub)
- Tags: how-to-guide
- Published: 2026-03-20

---

**Context Hub supports complete offline operation by either configuring local directory paths as sources or pre-downloading full content bundles, enabling air-gapped documentation access without remote CDN calls.**

Context Hub is an open-source CLI tool for managing and querying contextual documentation. Whether you are working on air-gapped machines or prefer to keep proprietary documentation local, you can use Context Hub offline by pointing it at local directories or pre-caching remote bundles.

## Two Methods for Offline Operation

### Method 1: Configure Local Content Folders as Sources

You can point Context Hub directly at a local directory containing your documentation. When a source is configured with a `path` field instead of a `url`, the CLI reads [`registry.json`](https://github.com/andrewyng/context-hub/blob/main/registry.json) and content files directly from disk.

The configuration handling is implemented in [`cli/src/lib/config.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/config.js), which loads `~/.chub/config.yaml` and transforms a `path` entry into a local source object [source 1†L21-L45]. The [`cli/src/lib/cache.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/cache.js) module then shortcuts remote fetching when `source.path` is present, reading files directly from the filesystem [source 2†L24-L33].

### Method 2: Pre-Download Full Bundles

For remote sources, you can download a complete offline archive once and use it indefinitely. The `chub update --full` command fetches a pre-packed `bundle.tar.gz` for every configured remote source, extracts it to the local cache, and thereafter all `search` and `get` operations read from the cached files only.

The `--full` flag is parsed in [`cli/src/commands/update.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/commands/update.js) [source 3†L10-L12][source 3†L24-L31], while the bundle download and extraction logic resides in [`cli/src/lib/cache.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/cache.js) [source 2†L68-L81][source 2†L94-L106].

## Architecture Components Supporting Offline Use

Context Hub's offline capability relies on several key components working together:

- **Config (`~/.chub/config.yaml`)**: Lists sources. A source with a `path` field points to a local directory containing a [`registry.json`](https://github.com/andrewyng/context-hub/blob/main/registry.json) and content tree, eliminating network requirements.
- **`fetchDoc` (cache.js)**: Detects `source.path` and reads files straight from the filesystem; remote fetches only occur when the source has a `url`.
- **`ensureRegistry` (cache.js)**: When a local source is present, skips bundled-seed/remote-fetch logic and uses the provided registry directly.
- **Full bundle (`bundle.tar.gz`)**: A static archive containing the registry and all docs/skills. Downloaded once via `chub update --full`, it extracts to `~/.chub/sources/<name>/data/`, making subsequent operations network-free.
- **`build` command**: Located in [`cli/src/commands/build.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/commands/build.js), this converts any folder of DOC/SKILL markdown into a proper registry and content tree (`dist/`), which can then be referenced as a local source.

## Practical Implementation Examples

### Setting Up Local Documentation (Bring Your Own Docs)

To use your own documentation without internet access:

```bash

# Build a local registry from your markdown tree

chub build ./my-content --output ./my-content/.chub-local

# Add the local source to the config (creates ~/.chub/config.yaml if missing)

cat >> ~/.chub/config.yaml <<'EOF'
sources:
  - name: internal
    path: /full/path/to/my-content/.chub-local
EOF

```

Now all commands work offline:

```bash
chub search "payment api"      # searches your local docs only

chub get internal:mycompany/internal-api --lang py   # fetches the DOC.md locally

```

*Relevant files*: [`docs/byod-guide.md`](https://github.com/andrewyng/context-hub/blob/main/docs/byod-guide.md) (explains the workflow) [source 4†L1-L76], [`cli/src/commands/build.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/commands/build.js) (build logic) [source 5†L90-L118], [`cli/src/lib/config.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/config.js) (config parsing) [source 1†L21-L45].

### Downloading Public Registry for Offline Use

To use public documentation without a persistent connection:

```bash

# First time – download the full bundle for every remote source

chub update --full

# Afterwards you can work offline:

chub search "stripe"          # uses the cached search-index.json

chub get stripe/payments --lang js   # reads the cached DOC.md

```

*Relevant files*: [`cli/src/commands/update.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/commands/update.js) (parses `--full`) [source 3†L10-L31], [`cli/src/lib/cache.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/cache.js) (bundle download & extraction) [source 2†L68-L106].

### Verifying Cache Status

To confirm your offline setup is working:

```bash
chub cache status

```

This shows each source, whether a registry is present, bundle status, and file counts. The implementation lives in [`cli/src/lib/cache.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/cache.js) [source 2†L173-L183].

## Key Files and Their Purposes

| File | Purpose |
|------|---------|
| [`docs/byod-guide.md`](https://github.com/andrewyng/context-hub/blob/main/docs/byod-guide.md) | Guide for bringing your own documentation directory and configuring it as a local source. |
| [`docs/design.md`](https://github.com/andrewyng/context-hub/blob/main/docs/design.md) | High-level architecture explaining multiple sources, caching, and offline bundle strategy. |
| [`cli/src/commands/update.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/commands/update.js) | Implements `chub update --full` to download and extract the offline bundle. |
| [`cli/src/commands/build.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/commands/build.js) | Generates a [`registry.json`](https://github.com/andrewyng/context-hub/blob/main/registry.json) and content tree from a local folder (the BYOD build step). |
| [`cli/src/lib/config.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/config.js) | Loads `~/.chub/config.yaml`, creates the source list, and distinguishes local (`path`) vs remote (`url`) sources. |
| [`cli/src/lib/cache.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/cache.js) | Core cache logic: fetching remote registries, reading local sources, downloading full bundles, and serving docs from cache. |

## Summary

- **Local sources** use the `path` field in `~/.chub/config.yaml` to read directly from disk without network calls.
- **Full bundles** downloaded via `chub update --full` enable offline access to remote content by extracting `bundle.tar.gz` to the local cache.
- The **`build`** command converts markdown trees into local registries for proprietary documentation.
- Core offline logic resides in [`cli/src/lib/cache.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/cache.js) and [`cli/src/lib/config.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/config.js), with entry points in [`cli/src/commands/update.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/commands/update.js) and [`cli/src/commands/build.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/commands/build.js).

## Frequently Asked Questions

### Does Context Hub require an internet connection to index local documentation?

No. When you configure a source with a `path` pointing to a local directory containing a [`registry.json`](https://github.com/andrewyng/context-hub/blob/main/registry.json), Context Hub reads directly from the filesystem without any network calls. This is implemented in [`cli/src/lib/cache.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/cache.js), which detects local paths and shortcuts remote fetching entirely.

### Can I use Context Hub offline with documentation from public sources?

Yes. Run `chub update --full` while connected to download the complete `bundle.tar.gz` for each remote source. After extraction to `~/.chub/sources/<name>/data/`, all subsequent `search` and `get` operations read from the cached files locally, requiring no further internet access.

### How do I convert my existing markdown documentation into a Context Hub compatible format?

Use the `chub build` command. Point it at your folder containing DOC or SKILL markdown files, and it will generate a [`registry.json`](https://github.com/andrewyng/context-hub/blob/main/registry.json) and content tree in the output directory. You can then add this directory as a local source in `~/.chub/config.yaml` to query your documentation offline.

### Where does Context Hub store offline content and configuration?

Configuration is stored in `~/.chub/config.yaml`. Cached registries and downloaded bundles reside in `~/.chub/sources/<source-name>/`, with extracted content typically stored under `data/` subdirectories. The cache management logic is handled in [`cli/src/lib/cache.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/lib/cache.js).