Project N.O.M.A.D. is a self-contained, offline-first knowledge and education server packed with critical tools, knowledge, and AI to keep you informed and empowered—anytime, anywhere.
Project N.O.M.A.D. can be installed on any Debian-based operating system (we recommend Ubuntu). Installation is completely terminal-based, and all tools and resources are designed to be accessed through the browser, so there's no need for a desktop environment if you'd rather setup N.O.M.A.D. as a "server" and access it through other clients.
Note: sudo/root privileges are required to run the install script
sudo apt-get update && sudo apt-get install -y curl && curl -fsSL https://raw.githubusercontent.com/Crosstalk-Solutions/project-nomad/refs/heads/main/install/install_nomad.sh -o install_nomad.sh && sudo bash install_nomad.shProject N.O.M.A.D. is now installed on your device! Open a browser and navigate to http://localhost:8080 (or http://DEVICE_IP:8080) to start exploring!
For a complete step-by-step walkthrough (including Ubuntu installation), see the Installation Guide.
For more control over the installation process, copy and paste the Docker Compose template into a docker-compose.yml file and customize it to your liking (be sure to replace any placeholders with your actual values). Then, run docker compose up -d to start the Command Center and its dependencies. Note: this method is recommended for advanced users only, as it requires familiarity with Docker and manual configuration before starting.
If you are using Infisical with the local docker-compose.yml, the three core secrets you need are APP_KEY, DB_PASSWORD, and MYSQL_ROOT_PASSWORD.
You can generate them locally with openssl:
openssl rand -hex 32
openssl rand -base64 32 | tr -d '\n'
openssl rand -base64 32 | tr -d '\n'Recommended mapping:
- First command:
APP_KEY - Second command:
DB_PASSWORD - Third command:
MYSQL_ROOT_PASSWORD
If you want all three in one shot:
printf 'APP_KEY=%s\nDB_PASSWORD=%s\nMYSQL_ROOT_PASSWORD=%s\n' \
"$(openssl rand -hex 32)" \
"$(openssl rand -base64 32 | tr -d '\n')" \
"$(openssl rand -base64 32 | tr -d '\n')"Store the generated values in Infisical or a local untracked .env file. Do not commit them. Also keep APP_KEY stable for an existing install, since changing it later will invalidate encrypted app data such as cookies and signed values.
The repo-level docker-compose.yml is set up to pull the three core secrets from environment variables injected by Infisical:
APP_KEYDB_PASSWORDMYSQL_ROOT_PASSWORD
On a new machine, the basic flow is:
- Install Docker and the Infisical CLI.
- Clone this repository and
cdinto it. - If you are working from a fork, add the original repository as
upstreamso you can pull future changes cleanly:
git remote add upstream https://github.com/Crosstalk-Solutions/project-nomad.gitIf you are not used to working with forks, the short version is:
# Update your local main branch from the original repo
git checkout main
git fetch upstream
git rebase upstream/main
# Optionally update your fork's main branch on GitHub too
git push origin mainWhen you are already on a feature branch and want the latest changes from the original repo:
git fetch upstream
git rebase upstream/mainIf you have already pushed that feature branch to your fork before rebasing, update it with:
git push --force-with-lease origin YOUR_BRANCH_NAMEFor a fuller fork/upstream workflow, see CONTRIBUTING.md.
- Make sure the needed secrets already exist in your Infisical project for the environment you plan to use.
- Log in to Infisical:
infisical login- If this repo does not already contain
.infisical.json, initialize the project connection from the repo root:
infisical init- Set any non-secret machine-specific values you want to override.
NOMAD_DATA_ROOTis the most common one.
export NOMAD_DATA_ROOT="$HOME/project-nomad-data"
export NOMAD_LOCAL_STATE_ROOT="./.docker"
export URL="http://localhost:8080"By default, the repo-level Compose file keeps large app content on NOMAD_DATA_ROOT but stores MySQL and Redis under ./.docker on the local machine. This avoids a common Docker Desktop/macOS problem where database containers fail on external exFAT/NTFS volumes.
If you want to override them explicitly, use:
export NOMAD_MYSQL_ROOT="$HOME/.local/share/project-nomad/mysql"
export NOMAD_REDIS_ROOT="$HOME/.local/share/project-nomad/redis"- Validate that Infisical can inject secrets and that Compose resolves cleanly:
infisical run --env=dev -- docker compose config- Start the stack:
infisical run --env=dev -- docker compose up -d- Verify that the services are healthy:
docker compose ps
docker compose logs -f adminThe default stack now includes dedicated worker and download_worker containers for BullMQ background jobs. This separates long-running downloads from the rest of the background queue workload and lets Docker restart worker containers independently from the web app.
If your Infisical environment is not named dev, replace dev in the commands above with the correct environment name such as prod or staging.
Useful lifecycle commands:
# Stop the stack
infisical run --env=dev -- docker compose down
# On Linux hosts that support mount propagation, also start the optional disk collector
infisical run --env=dev -- docker compose --profile host-disk up -d
# Pull the latest images and recreate containers
infisical run --env=dev -- docker compose pull
infisical run --env=dev -- docker compose up -d
# Restart just the web app and workers
docker restart nomad_admin nomad_worker nomad_download_worker
# View the resolved Compose config for troubleshooting
infisical run --env=dev -- docker compose configNotes:
NODE_ENVis the app runtime mode. It is not the same thing as Infisical's--envflag.APP_ENVandJWT_SECRETare not used by this project.- If
infisical runfails with a login error, runinfisical loginagain or use a service token. - On macOS, keep MySQL and Redis on a local/native filesystem. Using an external drive for
NOMAD_DATA_ROOTis fine for large downloaded content, but database state is safer underNOMAD_LOCAL_STATE_ROOT,NOMAD_MYSQL_ROOT, orNOMAD_REDIS_ROOT. - On Docker Desktop for macOS, the storage bars in Easy Setup and System Information may show the Docker VM or host-sharing mount capacity instead of the real free space on your external drive. Project N.O.M.A.D. still writes app content to
NOMAD_DATA_ROOT/storage, but the displayed free-space number can be misleading. - On macOS, verify the real available capacity for downloaded content from the host, not from inside the container:
df -h "$NOMAD_DATA_ROOT/storage"- If
NOMAD_DATA_ROOTis not exported in your current shell, the default path is:
df -h /Volumes/Research/project-nomad/storage- The optional
disk-collectorservice uses/:/host:ro,rslave, which is intended for Linux hosts with mount propagation support. Leave it disabled on Docker Desktop for macOS. - Download-related queue behavior can be tuned with
DOWNLOAD_QUEUE_CONCURRENCY,DOWNLOAD_QUEUE_LOCK_DURATION_MS,DOWNLOAD_QUEUE_STALLED_INTERVAL_MS, andDOWNLOAD_QUEUE_MAX_STALLED_COUNT. - Avoid running
docker compose configin a shared terminal session if you do not want resolved secret values visible in output.
N.O.M.A.D. is a management UI ("Command Center") and API that orchestrates a collection of containerized tools and resources via Docker. It handles installation, configuration, and updates for everything — so you don't have to.
Built-in capabilities include:
- AI Chat with Knowledge Base — local AI chat powered by Ollama, with document upload and semantic search (RAG via Qdrant)
- Information Library — offline Wikipedia, medical references, ebooks, and more via Kiwix
- Education Platform — Khan Academy courses with progress tracking via Kolibri
- Offline Maps — downloadable regional maps via ProtoMaps
- Data Tools — encryption, encoding, and analysis via CyberChef
- Notes — local note-taking via FlatNotes
- System Benchmark — hardware scoring with a community leaderboard
- Easy Setup Wizard — guided first-time configuration with curated content collections
N.O.M.A.D. also includes built-in tools like a Wikipedia content selector, ZIM library manager, and content explorer.
| Capability | Powered By | What You Get |
|---|---|---|
| Information Library | Kiwix | Offline Wikipedia, medical references, survival guides, ebooks |
| AI Assistant | Ollama + Qdrant | Built-in chat with document upload and semantic search |
| Education Platform | Kolibri | Khan Academy courses, progress tracking, multi-user support |
| Offline Maps | ProtoMaps | Downloadable regional maps with search and navigation |
| Data Tools | CyberChef | Encryption, encoding, hashing, and data analysis |
| Notes | FlatNotes | Local note-taking with markdown support |
| System Benchmark | Built-in | Hardware scoring, Builder Tags, and community leaderboard |
While many similar offline survival computers are designed to be run on bare-minimum, lightweight hardware, Project N.O.M.A.D. is quite the opposite. To install and run the available AI tools, we highly encourage the use of a beefy, GPU-backed device to make the most of your install.
At it's core, however, N.O.M.A.D. is still very lightweight. For a barebones installation of the management application itself, the following minimal specs are required:
Note: Project N.O.M.A.D. is not sponsored by any hardware manufacturer and is designed to be as hardware-agnostic as possible. The harware listed below is for example/comparison use only
- Processor: 2 GHz dual-core processor or better
- RAM: 4GB system memory
- Storage: At least 5 GB free disk space
- OS: Debian-based (Ubuntu recommended)
- Stable internet connection (required during install only)
To run LLM's and other included AI tools:
- Processor: AMD Ryzen 7 or Intel Core i7 or better
- RAM: 32 GB system memory
- Graphics: NVIDIA RTX 3060 or AMD equivalent or better (more VRAM = run larger models)
- Storage: At least 250 GB free disk space (preferably on SSD)
- OS: Debian-based (Ubuntu recommended)
- Stable internet connection (required during install only)
For detailed build recommendations at three price points ($150–$1,000+), see the Hardware Guide.
Again, Project N.O.M.A.D. itself is quite lightweight - it's the tools and resources you choose to install with N.O.M.A.D. that will determine the specs required for your unique deployment
For answers to common questions about Project N.O.M.A.D., please see our FAQ page.
Project N.O.M.A.D. is designed for offline usage. An internet connection is only required during the initial installation (to download dependencies) and if you (the user) decide to download additional tools and resources at a later time. Otherwise, N.O.M.A.D. does not require an internet connection and has ZERO built-in telemetry.
To test internet connectivity, N.O.M.A.D. attempts to make a request to Cloudflare's utility endpoint, https://1.1.1.1/cdn-cgi/trace and checks for a successful response.
By design, Project N.O.M.A.D. is intended to be open and available without hurdles - it includes no authentication. If you decide to connect your device to a local network after install (e.g. for allowing other devices to access it's resources), you can block/open ports to control which services are exposed.
Will authentication be added in the future? Maybe. It's not currently a priority, but if there's enough demand for it, we may consider building in an optional authentication layer in a future release to support uses cases where multiple users need access to the same instance but with different permission levels (e.g. family use with parental controls, classroom use with teacher/admin accounts, etc.). We have a suggestion for this on our public roadmap, so if this is something you'd like to see, please upvote it here: https://roadmap.projectnomad.us/posts/1/user-authentication-please-build-in-user-auth-with-admin-user-roles
For now, we recommend using network-level controls to manage access if you're planning to expose your N.O.M.A.D. instance to other devices on a local network. N.O.M.A.D. is not designed to be exposed directly to the internet, and we strongly advise against doing so unless you really know what you're doing, have taken appropriate security measures, and understand the risks involved.
Contributions are welcome and appreciated! Please see CONTRIBUTING.md for guidelines on how to contribute to the project.
- Website: www.projectnomad.us - Learn more about the project
- Discord: Join the Community - Get help, share your builds, and connect with other NOMAD users
- Benchmark Leaderboard: benchmark.projectnomad.us - See how your hardware stacks up against other NOMAD builds
- Troubleshooting Guide: TROUBLESHOOTING.md - Find solutions to common issues
- FAQ: FAQ.md - Find answers to frequently asked questions
Project N.O.M.A.D. is licensed under the Apache License 2.0.
Once installed, Project N.O.M.A.D. has a few helper scripts should you ever need to troubleshoot issues or perform maintenance that can't be done through the Command Center. All of these scripts are found in Project N.O.M.A.D.'s install directory, /opt/project-nomad
sudo bash /opt/project-nomad/start_nomad.shsudo bash /opt/project-nomad/stop_nomad.shUpdate Script - Attempts to pull the latest images for the Command Center and its dependencies (i.e. mysql) and recreate the containers. Note: this only updates the Command Center containers. It does not update the installable application containers - that should be done through the Command Center UI
sudo bash /opt/project-nomad/update_nomad.shUninstall Script - Need to start fresh? Use the uninstall script to make your life easy. Note: this cannot be undone!
curl -fsSL https://raw.githubusercontent.com/Crosstalk-Solutions/project-nomad/refs/heads/main/install/uninstall_nomad.sh -o uninstall_nomad.sh && sudo bash uninstall_nomad.sh