Navig

[NAVIG]

NAVIG

No Admin Visible In Graveyard
The terminal was never the problem. The chaos around it was.

[CI] [PyPI] [Python 3.10+] [License] [Sponsor] [Platform]

[navig host list, a real navig run over SSH, and navig apply safe-deployment --dry-run]

[!NOTE] NAVIG 3.x is a stable release. The CLI contract (navig <resource> <action>) is stable and changes follow semantic versioning. Review the CHANGELOG before upgrading across major versions. As with any tool that operates live infrastructure, use read-only inspection and dry runs first in production-critical environments.

See it in action

Real sessions, recorded from the tapes in tools/showcase/ against lab hosts — nothing typed into the output, nothing edited out. All eleven scenes, the videos and how they were made: docs/showcase · videos (and a 90-second trailer) on the NAVIG 3.25.0 release.

Prerequisites

NAVIG CLI uses Nerd Font glyphs for Powerline-style status bars and icons. Install once per machine:

pwsh navig/builtin/scripts/Install-NerdFont.ps1

VS Code is patched automatically on all platforms. Restart VS Code and your terminal after running the script.

Offline install: set $env:NAVIG_FONT_ZIP to a local zip path, or pass -LocalZip <path>.

What is NAVIG?

NAVIG is a terminal-first infrastructure CLI and runtime for people who are tired of juggling SSH sessions, scattered scripts, disconnected dashboards, and ad-hoc credentials just to keep their systems running.

It was built by one person — a solo founder managing a growing swarm of remote machines, projects, and operational overhead with no platform team to fall back on. The problem wasn't the terminal. The problem was everything fragmented around it: SSH in one place, SFTP in another, databases behind dashboards, secrets pasted into notes, logs spread across providers, and no single coherent surface to operate from.

NAVIG is the result of refusing to accept that reality.

It gives operators direct control over remote hosts, databases, containers, files, tunnels, and workflows — from one place, with structure, memory, and optional AI assistance that stays out of the way until it's actually useful.

One operator surface. For operators.

NAVIG Core (free) vs NAVIG Deck (paid)

NAVIG ships in two layers with a deliberate split:

• NAVIG Core (this repo) — Apache-2.0 open source. The daemon, CLI, agent runtime, vault, scheduler, mesh, MCP server, Telegram text bot, gateway. Free forever, no host limits via the CLI, no telemetry.
• NAVIG Deck — the polished UI cockpit (proprietary; signed PyPI wheel installed via pip install navig[deck]). Hosts inventory, mesh topology, vault UI, mission queue, workflow runner, Telegram Mini App. Free on one host; Harbor Pass / Max add host scale and the full operator module suite — see navig.run/deck.

The split is honest: the daemon is open and audit-able, the Deck is free on one host, and Harbor subscriptions add host scale, every operator module and all of Harbor Bay. See navig.run/buy for the plans.

What's free, forever, no matter what:

• The entire CLI — unlimited navig ssh, unlimited hosts you connect to
• Telegram text bot (/start, /run, /status, all commands)
• Agent runtime (navig ask, conversation memory, missions)
• VS Code MCP integration
• Vault, scheduler, mesh peer discovery
• All updates, including major versions

What a Harbor subscription pays for is scale and the operator suite; the daemon never will be paid.

Why NAVIG?

Most operators already have SSH. What they don't have is everything that should live around it:

NAVIG is not a configuration management tool (not Ansible). It is not a deployment platform (not Kubernetes). It is a control plane for humans — the thing you reach for when you need to do something to a real machine, right now, without writing a playbook.

Features

Install

Linux / macOS / WSL

curl -fsSL https://navig.run/install.sh | bash

Windows (PowerShell)

iwr -useb https://navig.run/install.ps1 | iex

pipx

pipx install navig

pip

pip install navig

Install options

Telegram bootstrap is available through the installer pipeline after install:

NAVIG_TELEGRAM_BOT_TOKEN="<your-bot-token>" navig init --profile operator

Development Install

git clone https://github.com/navig-run/core.git navigcd navigpip install -e ".[dev]"

With a virtual environment (optional but recommended):

git clone https://github.com/navig-run/core.git navigcd navigpython -m venv .venvsource .venv/bin/activate   # Windows: .venv\Scripts\activatepip install -e ".[dev]"

Verify

navig --versionnavig --help

No server? Start here (local mode)

If you don't have a remote server available yet, NAVIG works on localhost too:

# Installpip install navig
# Discover your local machine as a hostnavig host discover-local
# Run your first command (on this machine)navig run "echo hello from NAVIG && uname -a"
# Explore filesnavig file list ~ --tree --depth 2
# Ask the AI operator layer somethingnavig ask "what process is using the most CPU right now?"

That's a complete first run — no remote server required.

Quick start

# 1. Initialize — creates ~/.navig/, runs setup wizardnavig init
# 2. Add a remote hostnavig host add
# 3. Test the connectionnavig host test
# 4. Set it as activenavig host use <name>
# 5. Run your first remote commandnavig run "uname -a"
# 6. Ask the AI operator layer something about itnavig ask "what is consuming the most memory on this host?"

That's it. Everything else builds from here.

No server yet? examples/quickdemo.sh walks the same path on your own machine in 60 seconds.

Where to go next — after that first navig run:

Command reference

The pattern is consistent across all resources:

navig <resource> <action> [options]

Infrastructure

AI & Automation

Organisation

Run navig help or navig help <topic> for detailed usage. Every command also supports --help.

Plugins

First-party plugins extend navig with new commands — and several run on their own, with no navig install at all. Source and per-plugin docs: navig-run/plugins.

Agent runtime

NAVIG ships an autonomous agent layer that runs as a persistent background process.

# One-time setup: write ~/.navig/agent/config.yaml and create runtime directoriesnavig agent install
# Optional: register as an OS service (starts on boot)navig service installnavig service start
# Check statenavig agent status

Operating modes: supervised (default, confirms actions), autonomous (executes without prompts), observe-only (reads and reports, no writes). Personality profiles: friendly, professional, witty, paranoid, minimal.

See docs/agent/install.md for the full reference.

AI and chat interfaces

NAVIG can expose its operator layer through:

• CLI (navig ask)
• Telegram (via navig gateway)
• Matrix
• Any MCP-compatible editor (Cursor, Claude Desktop, VS Code)

navig ask "Why does this container keep restarting?"

The AI layer assists with reasoning, context, and workflow execution. It does not replace direct operator control — the operator stays responsible, the operator stays in command.

Cloud routing (relay.navig.run)

NAVIG's hosted Deck lives at relay.navig.run. It's a static React app + a tiny broker (Cloudflare Pages Functions + D1) that maps your daemon's API key (and your Telegram user_id) to its current public URL. Your daemon registers itself with the broker on every boot; the Deck and the Telegram Mini App resolve "where is my daemon" via the broker. Daemon data never leaves your machine — the broker only stores routing metadata (a SHA-256 of your api_key, your current public URL, and the Telegram bindings).

Modes — pick one

The subscription-vs-perpetual split: the hosted cloud relay is the one feature that costs us money per month. So it's a subscription feature. Perpetual-pack buyers get the full local app forever and self-host the Mini App with a single Tailscale command — free, stable, costs us nothing. See docs/CLOUD.md for the full topology.

Always-on in 3 commands (your own edge + your own Deck)

NAVIG self-hosts entirely on your Cloudflare account — two tiny deployments, each with its own stable URL, plus your brain dialing out:

navig lighthouse login     # 1. EDGE: API uplink (Worker + Durable Object). Opens                           #    Cloudflare → click Authorize → deploys + sets the                           #    Telegram webhook. (Or: navig lighthouse deploy --token <t>)navig miniapp deploy       # 2. DECK: builds the UI (static export) → your own                           #    Cloudflare Pages, bakes the edge URL in (auto-targets                           #    your brain) → sets the bot's Mini App button.navig gateway start        # 3. BRAIN: your daemon dials OUT to the edge. Nothing inbound.

Open your bot → tap the menu button → your Deck, talking to your brain through your edge — reachable from anywhere, no tunnel, no port-forwarding, no domain. navig lighthouse url prints every inbound hook (Telegram is set automatically; paste the SMS hook into Twilio only if you use SMS; social publishers are outbound — token only, no webhook).

One Cloudflare credential for both deploys, no wrangler: both lighthouse deploy/login and miniapp deploy upload via the Cloudflare REST API and reuse the same credential (an API token with the "Edit Cloudflare Workers" template, or the OAuth token from lighthouse login). Node 18+ is only needed to build the Deck (miniapp deploy); the upload — like the edge — needs neither Node nor wrangler. (miniapp deploy --wrangler is a Cloudflare-Pages fallback if you prefer it.)

Ports & firewall (cheat sheet)

The daemon itself never binds to a public interface — your reverse proxy is what listens on 0.0.0.0:443 in direct mode. Defense in depth: even if you misconfigure the proxy, the daemon socket stays on loopback.

Quick commands

navig lighthouse login        # recommended: your own Cloudflare edge (browser auth)navig lighthouse url          # show every inbound hook + the one stable edge URLnavig miniapp deploy          # deploy your own Deck UI → bot's Mini App buttonnavig cloud connect           # turn cloudflared mode on (default)navig cloud direct https://navig.example.com   # switch to VPS direct modenavig cloud direct --clear    # revert direct mode back to cloudflarednavig cloud status            # show mode, public URL, last heartbeatnavig cloud disconnect        # full off (no broker, no tunnel)navig cloud key --reveal      # print the api_key (sensitive)

For the full operator guide — including ready-made nginx/Caddy configs, a systemd unit template with Environment=NAVIG_PUBLIC_URL=..., the security model, and troubleshooting — see docs/CLOUD.md.

Configuration

Global config lives in ~/.navig/. Override with NAVIG_CONFIG_DIR.

~/.navig/├── config.yaml       ← main config├── vault/            ← encrypted credentials├── sessions/├── workspace/│   ├── SOUL.md       ← persistent operator identity│   └── HEARTBEAT.md└── logs/

Project-specific overrides: place a .navig/ directory at your repository root. Project config takes precedence over global config.

See docs/user/CONFIG_SCHEMA.md and docs/user/HANDBOOK.md.

Documentation

Development

# Lintruff check navig testsruff format --check navig tests
# Testpytest
# Buildpython -m build

Quick checks before a PR:

python -c "import navig"             # no import errorsnavig --help                         # CLI loads in < 1spytest tests/ -q                     # all green

See CONTRIBUTING.md for the full contribution workflow, branch model, and commit conventions.

Community & support

Project structure

navig/├── navig/               # Main Python package│   ├── cli/             # CLI app, commands registry, help system│   ├── commands/        # CLI command modules (one file per resource)│   ├── agents/          # Specialist agents (inbox router, etc.)│   ├── memory/          # Conversation store, knowledge base, RAG, embeddings│   ├── providers/       # AI provider clients, fallback manager, OAuth│   ├── gateway/         # Chat gateway (Telegram, Matrix) integrations│   ├── onboarding/      # First-run setup engine and wizard steps│   ├── daemon/          # Background service entry point│   ├── core/            # Config loader, migrations, crash handler│   └── resources/       # Default prompts, personas, assets├── sdk/                 # Pointer to the SDK in navig-run/registry├── scripts/             # Install and deployment scripts├── deploy/              # Docker, systemd, hardening configs├── docs/                # Documentation├── packages/            # Optional add-on packages└── tests/               # pytest test suite

Sponsor

NAVIG is built by one person and released as open-source. If it saves you time, prevents mistakes, or earns a place in your workflow:

[GitHub Sponsors]    [Buy Me a Coffee]

See FUNDING.md for full details.

Security

Report vulnerabilities privately. See SECURITY.md.

License

Apache-2.0 — see LICENSE.

Brand usage and official build identity: TRADEMARK.md · GOVERNANCE.md

Forge-coded by @miztizm