core

<p align="center">
  <img src="https://raw.githubusercontent.com/navig-run/core/main/logo.svg" alt="NAVIG" width="100" />
</p>

<h1 align="center">NAVIG</h1>

<p align="center">
  <strong>No Admin Visible In Graveyard</strong><br/>
  The terminal was never the problem. The chaos around it was.
</p>

<p align="center">
  <a href="https://github.com/navig-run/core/actions"><img src="https://img.shields.io/github/actions/workflow/status/navig-run/core/ci.yml?branch=main&style=flat-square&label=CI" alt="CI"></a>
  <a href="https://pypi.org/project/navig/"><img src="https://img.shields.io/pypi/v/navig?style=flat-square&color=blue" alt="PyPI"></a>
  <img src="https://img.shields.io/badge/python-3.10%2B-blue?style=flat-square" alt="Python 3.10+">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-green?style=flat-square" alt="License"></a>
  <a href="https://github.com/sponsors/navig-run"><img src="https://img.shields.io/badge/GitHub%20Sponsors-support-pink?style=flat-square" alt="Sponsor"></a>
  <img src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey?style=flat-square" alt="Platform">
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/navig-run/core/main/docs/showcase/hero.gif" alt="navig host list, a real navig run over SSH, and navig apply safe-deployment --dry-run" width="900" />
</p>

> [!NOTE]
> **NAVIG 3.x is a stable release.** The CLI contract (`navig <resource> <action>`) is stable
> and changes follow [semantic versioning](https://semver.org). Review the [CHANGELOG](CHANGELOG.md)
> 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/`](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](docs/showcase/README.md)** · videos (and a 90-second trailer) on the [NAVIG 3.25.0 release](https://github.com/navig-run/core/releases/tag/v3.25.0).

<table>
<tr>
<td width="50%"><b>Live dashboard</b> — <code>navig dashboard</code><br/><img src="https://raw.githubusercontent.com/navig-run/core/main/docs/showcase/dashboard.gif" alt="navig dashboard" /></td>
<td width="50%"><b>Hosts &amp; safety</b> — <code>host test</code>, a second session refused, a destructive command declined<br/><img src="https://raw.githubusercontent.com/navig-run/core/main/docs/showcase/hosts-and-safety.gif" alt="navig host test, session lock, destructive confirmation" /></td>
</tr>
<tr>
<td><b>Spaces</b> — <code>space init --dry-run</code> → <code>space init</code> → <code>space doctor</code><br/><img src="https://raw.githubusercontent.com/navig-run/core/main/docs/showcase/spaces.gif" alt="navig space init and space doctor" /></td>
<td><b>Blocks</b> — <code>block show</code> → <code>apply --dry-run</code> with per-step risk<br/><img src="https://raw.githubusercontent.com/navig-run/core/main/docs/showcase/blocks.gif" alt="navig block show and apply --dry-run" /></td>
</tr>
<tr>
<td><b>Ledger &amp; undo</b> — <code>ledger show</code> → <code>ledger verify</code> → <code>undo --list</code><br/><img src="https://raw.githubusercontent.com/navig-run/core/main/docs/showcase/ledger-and-undo.gif" alt="navig ledger show, verify and undo --list" /></td>
<td><b>Your node</b> — <code>navig whoami</code><br/><img src="https://raw.githubusercontent.com/navig-run/core/main/docs/showcase/whoami.gif" alt="navig whoami sigil card" /></td>
</tr>
</table>

---

## Prerequisites

NAVIG CLI uses [Nerd Font](https://www.nerdfonts.com/) glyphs for Powerline-style status bars and icons. Install once per machine:

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

| Platform | Recommended terminal | Additional step |
|---|---|---|
| Windows | Windows Terminal | Script patches automatically |
| macOS | iTerm2 or Kitty | Set font to **JetBrainsMono Nerd Font Mono** after script runs |
| Linux | Kitty, Alacritty, GNOME Terminal | Set font manually after script runs |

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 Solo tier (1 host); paid tiers and modules at
  [navig.run/deck](https://navig.run/deck).

The split is honest: the daemon is open and audit-able; the polished
GUI is the paid product. Pack owners get the local app forever,
self-hosted; subscribers add host scale and the hosted cloud relay we
run on `relay.navig.run`. See [navig.run/pricing](https://navig.run/pricing)
for the full pricing model.

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

The Deck UI is what you pay for if you want it; **the daemon never
will be**.

---

## Why NAVIG?

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

| You probably have | NAVIG adds |
|---|---|
| SSH client | Multi-host management with one active context |
| Ad-hoc shell scripts | Named workflows with dry-run and preview |
| Secrets in `.env` files | Encrypted vault with context-aware resolution |
| `grep` in log files | Structured log tailing across hosts |
| Copy-paste from Stack Overflow | AI operator layer with your infra as context |
| One terminal per machine | Mesh networking and command delegation |

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

| Capability | Description |
|---|---|
| **Multi-host management** | Add, switch, test, and operate remote hosts over SSH |
| **Remote execution** | Run commands, pipe stdin, use base64 encoding for complex scripts |
| **Database operations** | Query, dump, restore, and maintain MySQL, MariaDB, and PostgreSQL |
| **File operations** | Upload, download, read, edit, and list remote files safely |
| **Docker & containers** | Inspect containers, restart services, tail logs, manage compose stacks |
| **Web server control** | Manage nginx/apache configs, test changes, reload safely |
| **Encrypted vault** | Store credentials without leaving secrets in plaintext config files |
| **Workflows** | Define repeatable multi-step flows with dry-run and preview support |
| **AI operator layer** | Natural language assistance for infra tasks — CLI, Telegram, or MCP |
| **Mesh networking** | LAN peer-to-peer node discovery and command delegation |
| **MCP integration** | Expose tools and resources to AI editors and compatible clients |
| **Daemon & gateway** | Background service with Telegram and Matrix channel support |
| **Telegram Manager** | Full-account Telegram organizer (MTProto): search/move/forward/dedupe + a business-conversation AI catcher, emoji-AI, deletion alerts, and rich-message replies — owner-only ([docs](docs/TELEGRAM_MANAGER.md) · [cheatsheet](docs/TELEGRAM_CHEATSHEET.md)) |
| **GitHub mirroring** | `navig github` — search, backup, and clone GitHub repos (flat or nested), token from the vault |
| **TikTok** | `navig tiktok` — download videos, extract metadata + top comments, and AI-brief any link (via yt-dlp) |

---

## Install

### Linux / macOS / WSL

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

### Windows (PowerShell)

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

### pipx

```bash
pipx install navig
```

### pip

```bash
pip install navig
```

### Install options

| Option | Example | Description |
|---|---|---|
| `--version` | `bash -s -- --version <release>` | Pin a specific version |
| `--dev` | `bash -s -- --dev` | Include development extras |
| `--method git` | `bash -s -- --method git` | Install from source instead of PyPI |
| `NAVIG_EXTRAS` | `NAVIG_EXTRAS=voice,keyring` | Enable optional extras |
| `NAVIG_INSTALL_PROFILE` | `NAVIG_INSTALL_PROFILE=operator` | Choose the first-run bootstrap profile |

Tel