# Omnish > Omnish runs shell commands from WhatsApp and Telegram on hardware you control. Free MIT gateway. npm install -g omnish. Run shell commands from WhatsApp or Telegram on your machine. Allowlisted senders only. One `config.json` for CLI, chat, and `omnish ui`. ## About - Developer tool for shell and terminal control from chat - Runs on hardware you control - MIT license ## What's free - `npm install -g omnish` - Core commands on your hardware (`!`, `/apps`, `/bg`, `/cowork`, `/board`, files, watch, webhooks) - No subscription for core routing ## Install ```bash npm install -g omnish omnish link omnish allow +15551234567 omnish start ``` Send `!ls` in private chat to verify. Browser setup: `omnish ui`. ## Key capabilities - Sync shell with `!command` - PTY sessions with `/apps` and `>session` - Background jobs with `/bg`, `/jobs`, `/tail` - Scheduled tasks with `/cowork` - Job queue with `/board` - Online catalog for recipes, apps, and shortcuts - Cluster routing with `/c use` and `/c here` - Files with `/send`, `/sendto`, `/receive` - Media with `/dl` and paste-a-link download - Platform attached mode (link once, run locally on each device) - Watch rules and CI webhooks - Doc search with `/s q` and `omnish search` - Cursor hooks from https://omnish.dev/downloads/omnish-cursor/install.sh ## Security - Allowlisted identities are credentials - Wildcard allowlists are rejected - Run `omnish security` before production ## Contact - Website: https://omnish.dev - Documentation: https://omnish.dev/docs - Platform: https://platform.omnish.dev/ - GitHub: https://github.com/eligapris/omnish - Install: `npm install -g omnish` ## Start here - [Vision and Direction](https://omnish.dev/docs/vision): Chat-to-shell gateway with allowlist trust and one shared config file. - [Quick Start](https://omnish.dev/docs/quick-start): Install omnish, link chat, allowlist your identity, and run !pwd from your phone. - [User Guide](https://omnish.dev/docs/user-guide): Run shell, apps, jobs, shortcuts, and /run recipes from chat day to day. ## Core guides - [Browser Setup UI (`omnish ui`)](https://omnish.dev/docs/browser-ui): Start omnish ui to configure gateway settings, pair WhatsApp, and control start/stop in a browser. - [Interactive Terminal (`omnish i`)](https://omnish.dev/docs/interactive-cli): Run the same chat command surface locally with omnish i. - [Background Gateway and Start on Boot](https://omnish.dev/docs/background-and-boot): Keep the gateway running in the background and auto-start it on boot. - [Security Model](https://omnish.dev/docs/security-model): Set allowlists, respect host boundaries, and run omnish security checks. - [Interactive Sessions (`/apps`)](https://omnish.dev/docs/interactive-sessions): Start, attach, send to, and stop PTY sessions with /apps. - [Background Jobs](https://omnish.dev/docs/background-jobs): Start long shell tasks with /bg and tail or kill them from chat. - [Platform Attached Mode](https://omnish.dev/docs/platform-attached-mode): Link messengers on the platform once, then run omnish start on each machine. - [Cursor Integration](https://omnish.dev/docs/cursor-integration): Install Cursor hooks, a setup skill, and mobile Done notifications. - [Files Send and Receive](https://omnish.dev/docs/files-send-receive): Send files to peers and save inbound media to a receive root. - [Cowork Tasks](https://omnish.dev/docs/cowork): Schedule and run saved shell tasks with /cowork from chat. - [Job Board](https://omnish.dev/docs/job-board): Queue and coordinate autonomous jobs with /board across your gateway. - [Online Catalog](https://omnish.dev/docs/online-catalog): Browse, install, and publish recipes, apps, cowork tasks, and shortcuts from chat. - [Watch (OS Event Eye)](https://omnish.dev/docs/watch): Watch filesystem, packages, and services and get debounced chat alerts. - [Webhook Receiver](https://omnish.dev/docs/webhook-receiver): POST CI/CD webhooks to the gateway and get formatted chat alerts. - [Media Commands](https://omnish.dev/docs/media-commands): Download URLs, transcribe audio, and edit media with /dl, /tr, and /edit. - [Cluster and Chat Config](https://omnish.dev/docs/cluster-and-chat-config): Bind senders to hosts in a cluster and change config from chat. - [Troubleshooting](https://omnish.dev/docs/troubleshooting): Diagnose install, auth, routing, and runtime problems with status and verbose logs. - [Docs Search from Chat](https://omnish.dev/docs/docs-search): Find docs from chat with /s q or omnish search on the host. - [Chat Agent Daemon](https://omnish.dev/docs/chat-agent-daemon): Run a long-lived per-peer agent process with curated mobile notifications. ## Optional - [System Agents and `/run`](https://omnish.dev/docs/system-agents-and-run): Launch local agents with /run recipes, queues, and multi-session /apps. - [Configuration Guide](https://omnish.dev/docs/configuration): Tune gateway, shell, sessions, files, and cluster keys in ~/.omnish/config.json. - [Architecture Overview](https://omnish.dev/docs/architecture-overview): Follow messages from transport through routing to shell and PTY execution. - [Message Routing](https://omnish.dev/docs/message-routing): See which command wins when a message matches multiple routes. - [Run Queue (`/run -q` / `--queue`)](https://omnish.dev/docs/run-queue): Queue /run recipe launches FIFO so one session runs at a time per chat. - [Service Commands from Chat](https://omnish.dev/docs/service-from-chat): Check gateway service status and logs from chat; install only when enabled. - [Device Update Delivery](https://omnish.dev/docs/device-update-delivery): Check npm versions and read update advisories from chat. - [Telegram Integration Notes](https://omnish.dev/docs/telegram-integration-notes): Link a Telegram bot, allowlist chat IDs, and run the gateway. - [Media Pull Toolchain](https://omnish.dev/docs/media-pull): Install yt-dlp, ffmpeg, and Whisper with omnish pull for media commands. - [Platform Reference](https://omnish.dev/docs/platform-reference): Platform API, dashboard, CLI commands, and allowlist reference. - [Tunneling](https://omnish.dev/docs/tunneling): Expose local HTTP or TCP ports with omnish tunnel and the relay. ## Markdown mirrors - https://omnish.dev/docs/vision.md - https://omnish.dev/docs/quick-start.md - https://omnish.dev/docs/browser-ui.md - https://omnish.dev/docs/interactive-cli.md - https://omnish.dev/docs/background-and-boot.md - https://omnish.dev/docs/user-guide.md - https://omnish.dev/docs/security-model.md - https://omnish.dev/docs/interactive-sessions.md - https://omnish.dev/docs/background-jobs.md - https://omnish.dev/docs/platform-attached-mode.md - https://omnish.dev/docs/cursor-integration.md - https://omnish.dev/docs/files-send-receive.md - https://omnish.dev/docs/cowork.md - https://omnish.dev/docs/watch.md - https://omnish.dev/docs/webhook-receiver.md - https://omnish.dev/docs/media-commands.md - https://omnish.dev/docs/cluster-and-chat-config.md - https://omnish.dev/docs/troubleshooting.md - https://omnish.dev/docs/docs-search.md - https://omnish.dev/docs/job-board.md - https://omnish.dev/docs/online-catalog.md - https://omnish.dev/docs/chat-agent-daemon.md Generated: 2026-06-18. ## Frequently Asked Questions Q: What is Omnish? A: A gateway that connects WhatsApp or Telegram to shell and PTY sessions on your machine. Allowlisted senders only. Q: How much does Omnish cost? A: Core routing is free under MIT. npm install -g omnish, set allowlists, and run commands on your hardware. Q: How do I install Omnish? A: npm install -g omnish, omnish link (or omnish link --tg TOKEN), omnish allow , omnish start. Send !ls in private chat to verify. Q: Does Omnish require an AI API? A: No. Commands go to your local shell, PTY sessions, and background jobs. Q: WhatsApp or Telegram? A: Both work. Use omnish link for WhatsApp or a bot token for Telegram. Platform mode links once on the relay; each device runs omnish start locally. Q: What is platform attached mode? A: Link messengers once on the Omnish relay. Run omnish start on each computer. Shell stays on that device. Q: How does Omnish handle security? A: Allowlisted chat identities are treated like passwords. Wildcards are rejected. Run omnish security before production. Q: Can I run long commands without blocking chat? A: Yes. Use /bg for background jobs, /jobs and /tail for logs, and /apps for interactive sessions. Q: How do file transfers work? A: Use /send, /sendto, and /receive. Platform attached mode has no default 8 MiB relay cap. Messenger limits still apply. Q: What is the default tunnel relay? A: tunnel.omnish.dev. Run omnish tunnel login and omnish tunnel http , or use /tunnel from chat. Q: How do I search Omnish docs from chat? A: Use /s q in chat or omnish search q on the host. Works offline with numbered excerpts. Q: What is the job board (/board)? A: /board add creates jobs. A coordinator dispatches specialists and a supervisor reviews work. /jobs is an alias. Q: What is the online catalog? A: Browse and install recipes, apps, cowork tasks, and shortcuts with /run online, /apps online, and related commands. Publish after omnish platform login. Q: What is the chat agent daemon? A: Optional chatAgentEnabled mode queues plain chat to a long-lived local process. Use /agent status and /sendto for updates. Q: How do I get Cursor agent notifications? A: curl -fsSL https://omnish.dev/downloads/omnish-cursor/install.sh | bash. Requires omnish start and an allowlisted peer. Q: What platforms does Omnish support? A: Linux, macOS, and Windows. Node.js 22+ on the host.