{"id":47726706,"url":"https://github.com/navig-run/core","last_synced_at":"2026-04-12T06:04:20.281Z","repository":{"id":346893391,"uuid":"1192039858","full_name":"navig-run/core","owner":"navig-run","description":"Agentic runtime for operators who want to manage servers, databases, containers, tunnels, and workflows from one place — with AI assistance, not AI dependence.","archived":false,"fork":false,"pushed_at":"2026-04-03T06:26:41.000Z","size":52728,"stargazers_count":5,"open_issues_count":39,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-04-03T06:29:22.766Z","etag":null,"topics":["ai","automation","cli","database","devops","docker","infrastructure","lifeops","matrix","mcp","python","remote-execution","self-hosted","server","ssh","sysadmin","telegram","terminal","vault","workflow"],"latest_commit_sha":null,"homepage":"https://navig.run","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/navig-run.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":"GOVERNANCE.md","roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"miztizm","custom":["https://buymeacoffee.com/miztizm"]}},"created_at":"2026-03-25T20:45:15.000Z","updated_at":"2026-04-03T00:37:15.000Z","dependencies_parsed_at":null,"dependency_job_id":"ba87e513-317f-41d2-adaf-a23d3678a50f","html_url":"https://github.com/navig-run/core","commit_stats":null,"previous_names":["navig-run/core"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/navig-run/core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navig-run%2Fcore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navig-run%2Fcore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navig-run%2Fcore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navig-run%2Fcore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/navig-run","download_url":"https://codeload.github.com/navig-run/core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navig-run%2Fcore/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31423887,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-05T02:22:46.605Z","status":"ssl_error","status_checked_at":"2026-04-05T02:22:33.263Z","response_time":75,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","automation","cli","database","devops","docker","infrastructure","lifeops","matrix","mcp","python","remote-execution","self-hosted","server","ssh","sysadmin","telegram","terminal","vault","workflow"],"created_at":"2026-04-02T20:39:59.533Z","updated_at":"2026-04-12T06:04:20.274Z","avatar_url":"https://github.com/navig-run.png","language":"Python","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo.svg\" alt=\"NAVIG\" width=\"100\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eNAVIG\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eNo Admin Visible In Graveyard\u003c/strong\u003e\u003cbr/\u003e\n  The terminal was never the problem. The chaos around it was.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/navig-run/core/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/navig-run/core/ci.yml?branch=main\u0026style=flat-square\u0026label=CI\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/navig/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/navig?style=flat-square\u0026color=blue\" alt=\"PyPI\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/python-3.10%2B-blue?style=flat-square\" alt=\"Python 3.10+\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache--2.0-green?style=flat-square\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/sponsors/miztizm\"\u003e\u003cimg src=\"https://img.shields.io/badge/GitHub%20Sponsors-support-pink?style=flat-square\" alt=\"Sponsor\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey?style=flat-square\" alt=\"Platform\"\u003e\n\u003c/p\u003e\n\n\u003e [!WARNING]\n\u003e **NAVIG is experimental software under active development.**\n\u003e APIs, CLI commands, and config formats may change between releases. Not yet recommended for production-critical environments without review.\n\n---\n\n## Prerequisites\n\nNAVIG CLI uses [Nerd Font](https://www.nerdfonts.com/) glyphs for Powerline-style status bars and icons. Install once per machine:\n\n```powershell\npwsh scripts/Install-NerdFont.ps1\n```\n\n| Platform | Recommended terminal | Additional step |\n|---|---|---|\n| Windows | Windows Terminal | Script patches automatically |\n| macOS | iTerm2 or Kitty | Set font to **JetBrainsMono Nerd Font Mono** after script runs |\n| Linux | Kitty, Alacritty, GNOME Terminal | Set font manually after script runs |\n\nVS Code is patched automatically on all platforms. Restart VS Code and your terminal after running the script.\n\n\u003e **Offline install**: set `$env:NAVIG_FONT_ZIP` to a local zip path, or pass `-LocalZip \u003cpath\u003e`.\n\n---\n\n## What is NAVIG?\n\nNAVIG 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.\n\nIt 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.\n\nNAVIG is the result of refusing to accept that reality.\n\nIt 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.\n\n**One operator surface. For operators.**\n\n---\n\n## Why NAVIG?\n\nMost operators already have SSH. What they don't have is everything that should live around it:\n\n| You probably have | NAVIG adds |\n|---|---|\n| SSH client | Multi-host management with one active context |\n| Ad-hoc shell scripts | Named workflows with dry-run and preview |\n| Secrets in `.env` files | Encrypted vault with context-aware resolution |\n| `grep` in log files | Structured log tailing across hosts |\n| Copy-paste from Stack Overflow | AI operator layer with your infra as context |\n| One terminal per machine | Mesh networking and command delegation |\n\nNAVIG 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.\n\n---\n\n## Features\n\n| Capability | Description |\n|---|---|\n| **Multi-host management** | Add, switch, test, and operate remote hosts over SSH |\n| **Remote execution** | Run commands, pipe stdin, use base64 encoding for complex scripts |\n| **Database operations** | Query, dump, restore, and maintain MySQL, MariaDB, and PostgreSQL |\n| **File operations** | Upload, download, read, edit, and list remote files safely |\n| **Docker \u0026 containers** | Inspect containers, restart services, tail logs, manage compose stacks |\n| **Web server control** | Manage nginx/apache configs, test changes, reload safely |\n| **Encrypted vault** | Store credentials without leaving secrets in plaintext config files |\n| **Workflows** | Define repeatable multi-step flows with dry-run and preview support |\n| **AI operator layer** | Natural language assistance for infra tasks — CLI, Telegram, or MCP |\n| **Mesh networking** | LAN peer-to-peer node discovery and command delegation |\n| **MCP integration** | Expose tools and resources to AI editors and compatible clients |\n| **Daemon \u0026 gateway** | Background service with Telegram and Matrix channel support |\n\n---\n\n## Install\n\n### Linux / macOS / WSL\n\n```bash\ncurl -fsSL https://navig.run/install.sh | bash\n```\n\n### Windows (PowerShell)\n\n```powershell\niwr -useb https://navig.run/install.ps1 | iex\n```\n\n### pipx\n\n```bash\npipx install navig\n```\n\n### pip\n\n```bash\npip install navig\n```\n\n### Install options\n\n| Option | Example | Description |\n|---|---|---|\n| `--version` | `bash -s -- --version \u003crelease\u003e` | Pin a specific version |\n| `--dev` | `bash -s -- --dev` | Include development extras |\n| `--method git` | `bash -s -- --method git` | Install from source instead of PyPI |\n| `NAVIG_EXTRAS` | `NAVIG_EXTRAS=voice,keyring` | Enable optional extras |\n| `NAVIG_INSTALL_PROFILE` | `NAVIG_INSTALL_PROFILE=operator` | Choose the first-run bootstrap profile |\n\nTelegram bootstrap is available through the installer pipeline after install:\n\n```bash\nNAVIG_TELEGRAM_BOT_TOKEN=\"\u003cyour-bot-token\u003e\" navig init --profile operator\n```\n\n### Development Install\n\n```bash\ngit clone https://github.com/navig-run/core.git navig\ncd navig\npip install -e \".[dev]\"\n```\n\nWith a virtual environment (optional but recommended):\n\n```bash\ngit clone https://github.com/navig-run/core.git navig\ncd navig\npython -m venv .venv\nsource .venv/bin/activate   # Windows: .venv\\Scripts\\activate\npip install -e \".[dev]\"\n```\n\n### Verify\n\n```bash\nnavig --version\nnavig --help\n```\n\n---\n\n## No server? Start here (local mode)\n\nIf you don't have a remote server available yet, NAVIG works on localhost too:\n\n```bash\n# Install\npip install navig\n\n# Discover your local machine as a host\nnavig host discover-local\n\n# Run your first command (on this machine)\nnavig run \"echo hello from NAVIG \u0026\u0026 uname -a\"\n\n# Explore files\nnavig file list ~ --tree --depth 2\n\n# Ask the AI operator layer something\nnavig ai ask \"what process is using the most CPU right now?\"\n```\n\nThat's a complete first run — no remote server required.\n\n---\n\n## Quick start\n\n```bash\n# 1. Initialize — creates ~/.navig/, runs setup wizard\nnavig init\n\n# 2. Add a remote host\nnavig host add\n\n# 3. Test the connection\nnavig host test\n\n# 4. Set it as active\nnavig host use \u003cname\u003e\n\n# 5. Run your first remote command\nnavig run \"uname -a\"\n\n# 6. Ask the AI operator layer something about it\nnavig ai ask \"what is consuming the most memory on this host?\"\n```\n\nThat's it. Everything else builds from here.\n\n**Where to go next** — after that first `navig run`:\n\n| Command | What it does |\n|---|---|\n| `navig host add` | Add more hosts |\n| `navig vault set KEY=value` | Store secrets encrypted |\n| `navig db query \"SELECT 1\"` | Connect to a remote database |\n| `navig tunnel 5432` | Open an SSH tunnel to a port |\n| `navig workflow run deploy.yaml` | Run a multi-step workflow |\n| `navig ai ask \"...\"` | Ask the AI operator layer anything |\n\n---\n\n## Command reference\n\nThe pattern is consistent across all resources:\n\n```bash\nnavig \u003cresource\u003e \u003caction\u003e [options]\n```\n\n### Infrastructure\n\n| Command | What it does |\n|---|---|\n| `navig host` | Add, switch, test, and inspect remote hosts |\n| `navig run` | Execute commands on remote or local hosts |\n| `navig file` | Upload, download, read, and edit remote files |\n| `navig db` | Query, dump, restore, and maintain databases |\n| `navig docker` | Container and compose operations |\n| `navig web` | Web server config, test, and reload |\n| `navig tunnel` | SSH tunnel management |\n| `navig backup` | Config and data backup / restore |\n\n### AI \u0026 Automation\n\n| Command | What it does |\n|---|---|\n| `navig ai ask` | AI-assisted troubleshooting and command guidance |\n| `navig flow` | Multi-step automation workflows |\n| `navig mcp` | MCP server for AI editor and tool integration |\n| `navig gateway` | Start and manage chat gateway (Telegram, Matrix) |\n\n### Organisation\n\n| Command | What it does |\n|---|---|\n| `navig config` | View, validate, and manage configuration |\n| `navig vault` | Encrypted credential storage |\n| `navig workspace` | Multi-context operator workspace |\n| `navig mesh` | LAN peer discovery and command delegation |\n\nRun `navig help` or `navig help \u003ctopic\u003e` for detailed usage. Every command also supports `--help`.\n\n---\n\n## AI and chat interfaces\n\nNAVIG can expose its operator layer through:\n\n- CLI (`navig ai ask`)\n- Telegram (via `navig gateway`)\n- Matrix\n- Any MCP-compatible editor (Cursor, Claude Desktop, VS Code)\n\n```bash\nnavig ai ask \"Why does this container keep restarting?\"\n```\n\nThe 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.\n\n---\n\n## Configuration\n\nGlobal config lives in `~/.navig/`. Override with `NAVIG_CONFIG_DIR`.\n\n```text\n~/.navig/\n├── config.yaml       ← main config\n├── vault/            ← encrypted credentials\n├── sessions/\n├── workspace/\n│   ├── SOUL.md       ← persistent operator identity\n│   └── HEARTBEAT.md\n└── logs/\n```\n\nProject-specific overrides: place a `.navig/` directory at your repository root. Project config takes precedence over global config.\n\nSee [`docs/user/CONFIG_SCHEMA.md`](docs/user/CONFIG_SCHEMA.md) and [`docs/user/USAGE_GUIDE.md`](docs/user/USAGE_GUIDE.md).\n\n---\n\n## Documentation\n\n| Guide | |\n|---|---|\n| Installation | [`docs/user/INSTALLATION.md`](docs/user/INSTALLATION.md) |\n| Quick reference | [`docs/user/QUICK_REFERENCE.md`](docs/user/QUICK_REFERENCE.md) |\n| CLI commands | [`docs/user/CLI_COMMANDS.md`](docs/user/CLI_COMMANDS.md) |\n| Handbook | [`docs/user/HANDBOOK.md`](docs/user/HANDBOOK.md) |\n| Troubleshooting | [`docs/user/troubleshooting.md`](docs/user/troubleshooting.md) |\n| Telegram setup | [`docs/features/TELEGRAM.md`](docs/features/TELEGRAM.md) |\n| Production deployment | [`docs/dev/PRODUCTION_DEPLOYMENT.md`](docs/dev/PRODUCTION_DEPLOYMENT.md) |\n| Migration guide | [`docs/dev/MIGRATION_GUIDE.md`](docs/dev/MIGRATION_GUIDE.md) |\n| Plugin / pack development | [navig-community](https://github.com/navig-run/community) |\n\n---\n\n## Development\n\n```bash\n# Lint\nruff check navig tests\nruff format --check navig tests\n\n# Test\npytest\n\n# Build\npython -m build\n```\n\n**Quick checks before a PR:**\n\n```bash\npython -c \"import navig\"             # no import errors\nnavig --help                         # CLI loads in \u003c 1s\npytest tests/ -q                     # all green\n```\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md) for the full contribution workflow, branch model, and commit conventions.\n\n---\n\n## Community \u0026 support\n\n| Channel | |\n|---|---|\n| Bug reports \u0026 feature requests | [GitHub Issues](https://github.com/navig-run/core/issues) |\n| Ideas \u0026 discussion | [GitHub Discussions](https://github.com/navig-run/core/discussions) |\n| Announcements | [t.me/navigrun](https://t.me/navigrun) |\n| Community group | [t.me/+OyFMwN66c3M0NTk0](https://t.me/+OyFMwN66c3M0NTk0) |\n| Security reports | [SECURITY.md](SECURITY.md) |\n\n---\n\n## Project structure\n\n```text\nnavig/\n├── navig/               # Main Python package\n│   ├── cli/             # CLI app, commands registry, help system\n│   ├── commands/        # CLI command modules (one file per resource)\n│   ├── agents/          # Specialist agents (inbox router, etc.)\n│   ├── memory/          # Conversation store, knowledge base, RAG, embeddings\n│   ├── providers/       # AI provider clients, fallback manager, OAuth\n│   ├── gateway/         # Chat gateway (Telegram, Matrix) integrations\n│   ├── onboarding/      # First-run setup engine and wizard steps\n│   ├── daemon/          # Background service entry point\n│   ├── core/            # Config loader, migrations, crash handler\n│   └── resources/       # Default prompts, personas, assets\n├── sdk/                 # Python SDK package\n├── scripts/             # Install and deployment scripts\n├── deploy/              # Docker, systemd, hardening configs\n├── docs/                # Documentation\n├── packages/            # Optional add-on packages\n└── tests/               # pytest test suite\n```\n\n---\n\n## Sponsor\n\nNAVIG is built by one person and released as open-source. If it saves you time, prevents mistakes, or earns a place in your workflow:\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/sponsors/miztizm\"\u003e\u003cimg src=\"https://img.shields.io/badge/❤️_GitHub_Sponsors-EA4AAA?style=for-the-badge\u0026logo=githubsponsors\u0026logoColor=white\" alt=\"GitHub Sponsors\" height=\"40\"\u003e\u003c/a\u003e\n  \u0026nbsp;\u0026nbsp;\n  \u003ca href=\"https://buymeacoffee.com/navig-run\"\u003e\u003cimg src=\"https://img.shields.io/badge/☕_Buy_Me_a_Coffee-FFDD00?style=for-the-badge\u0026logo=buymeacoffee\u0026logoColor=black\" alt=\"Buy Me a Coffee\" height=\"40\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n| Tier | | |\n|---|---|---|\n| 📡 **Watcher** | $5/mo | Simple backing. Badge + optional name in supporters. |\n| ⚡ **Node Operator** | $10/mo | You run this in real workflows. Early betas + dev updates. |\n| 🏗️ **System Architect** | $25/mo | Long-term support. Roadmap input + private changelogs. |\n| ⚡ **Signal Boost** | $10 one-time | Small direct contribution. |\n| 🚀 **Feature Sprint** | $50 one-time | Funds a focused development push. |\n| 🌐 **Founding Node** | $100 one-time | Permanent credit in `FOUNDERS.md`. Limited. |\n\nSee [FUNDING.md](FUNDING.md) for full details.\n\n---\n\n## Security\n\nReport vulnerabilities privately. See [`SECURITY.md`](SECURITY.md).\n\n---\n\n## License\n\nApache-2.0 — see [`LICENSE`](LICENSE).\n\nBrand usage and official build identity: [`TRADEMARK.md`](TRADEMARK.md) · [`GOVERNANCE.md`](GOVERNANCE.md)\n\n---\n\n\u003cp align=\"center\"\u003e\n  Forge-coded by \u003ca href=\"https://github.com/miztizm\"\u003e@miztizm\u003c/a\u003e\n\u003c/p\u003e\n","funding_links":["https://github.com/sponsors/miztizm","https://buymeacoffee.com/miztizm","https://buymeacoffee.com/navig-run"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnavig-run%2Fcore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnavig-run%2Fcore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnavig-run%2Fcore/lists"}