{"id":44577002,"url":"https://github.com/dorky-robot/katulong","last_synced_at":"2026-05-02T07:05:49.299Z","repository":{"id":336762621,"uuid":"997516785","full_name":"Dorky-Robot/katulong","owner":"Dorky-Robot","description":"Self-hosted remote workspace in your browser. Terminal (xterm.js + tmux), file browser, port proxy, drag-and-drop uploads, clipboard bridge, and multi-session tabs. Access any server from iPad, phone, or laptop with WebAuthn security.","archived":false,"fork":false,"pushed_at":"2026-04-25T04:29:17.000Z","size":10992,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-25T06:26:34.220Z","etag":null,"topics":["file-browser","homelab","remote-desktop","self-hosted","ssh-alternative","tmux","web-terminal","webauthn","websocket","xterm-js"],"latest_commit_sha":null,"homepage":"https://dorkyrobot.com/katulong/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Dorky-Robot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-06T16:59:52.000Z","updated_at":"2026-04-25T04:29:21.000Z","dependencies_parsed_at":null,"dependency_job_id":"007ae939-a16e-4e3e-9a41-625b6f99b7f4","html_url":"https://github.com/Dorky-Robot/katulong","commit_stats":null,"previous_names":["dorky-robot/katulong"],"tags_count":330,"template":false,"template_full_name":null,"purl":"pkg:github/Dorky-Robot/katulong","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dorky-Robot%2Fkatulong","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dorky-Robot%2Fkatulong/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dorky-Robot%2Fkatulong/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dorky-Robot%2Fkatulong/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Dorky-Robot","download_url":"https://codeload.github.com/Dorky-Robot/katulong/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dorky-Robot%2Fkatulong/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32362782,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-27T20:07:02.737Z","status":"online","status_checked_at":"2026-04-28T02:00:07.250Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["file-browser","homelab","remote-desktop","self-hosted","ssh-alternative","tmux","web-terminal","webauthn","websocket","xterm-js"],"created_at":"2026-02-14T05:30:08.185Z","updated_at":"2026-05-02T07:05:49.293Z","avatar_url":"https://github.com/Dorky-Robot.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# katulong\n\n[![Discord](https://img.shields.io/discord/1483879594619568291?color=5865F2\u0026label=Discord\u0026logo=discord\u0026logoColor=white)](https://dorkyrobot.com/discord)\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"katulong.png\" alt=\"Katulong mascot\" width=\"300\"\u003e\n\n*Katulong* (kah-too-LONG) — Tagalog for *helper*.\n\n\u003c/div\u003e\n\nA remote desktop experience for your server, delivered through the browser. Terminal, file browser, port proxy, drag-and-drop — everything you need to work on a remote machine as if you were sitting in front of it.\n\n**Extensible by design.** Katulong's tile system lets you create custom UI surfaces — dashboards, previews, tools — alongside your terminals. Drop a folder in `~/.katulong/tiles/` and it shows up in the menu.\n\n## What it does\n\nKatulong runs on your server and serves a native-feeling workspace over HTTP + WebSocket. Open a browser on any device — phone, tablet, laptop — and you get:\n\n- **Terminal** — Full xterm.js shell with tmux-backed sessions that survive restarts and reconnects\n- **Tiles** — Pluggable UI containers: terminals, dashboards, web previews, custom HTML, or anything you build\n- **File browser** — Browse, upload, download, and manage files on the remote host\n- **Port proxy** — Access services running on the remote machine (dev servers, dashboards) through the browser\n- **Drag and drop** — Drop files from your device into the terminal or file browser\n- **Multi-session tabs** — Chrome-style tabs with drag reorder, tear-off to new window, and context menus\n- **Clipboard bridge** — Copy/paste images and text between your device and the remote machine\n- **Flippable cards** — Each tile has a front and back face with a 3D flip animation\n\n```bash\nkatulong start\n```\n\nOpen `https://your-machine:3001` from any device. That's it.\n\n## Install\n\n### One-line install (Linux, macOS)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/dorky-robot/katulong/main/install.sh | sh\n```\n\nWorks on Alpine, Debian/Ubuntu, RHEL/Fedora, and macOS. On macOS it detects Homebrew and uses the tap.\n\n### Docker\n\nAdd to your Dockerfile:\n\n```dockerfile\nRUN KATULONG_VERSION=0.14.13 \\\n    curl -fsSL https://raw.githubusercontent.com/dorky-robot/katulong/v0.14.13/install.sh | sh\n\nENV PORT=3001\nCMD [\"katulong\", \"start\", \"--foreground\"]\n```\n\nMount a volume for auth state so passkeys and session tokens survive container restarts:\n\n```bash\ndocker run -d -p 3001:3001 -v katulong-data:/root/.katulong your-image\n```\n\n### Homebrew (macOS)\n\n```bash\n# Add the canonical Dorky-Robot tap (shared across all their projects)\nbrew tap dorky-robot/tap\n\n# Install\nbrew install katulong\n\n# Start\nkatulong start\n\n# Or use brew services for auto-start on login\nbrew services start katulong\n```\n\n### Manual\n\n```bash\ngit clone https://github.com/dorky-robot/katulong.git\ncd katulong \u0026\u0026 npm install \u0026\u0026 npm link\n```\n\n## Quick start\n\n```bash\nkatulong start                          # Start the server\nkatulong browse                         # Open in your default browser\nkatulong status                         # Check if it's running\nkatulong session create myapp --open    # Create session + open in browser\nkatulong logs                           # View logs\nkatulong update                         # Update to the latest version\nkatulong stop                           # Stop everything\n```\n\n### CLI commands\n\n```bash\n# Server\nkatulong start | stop | restart | status | logs | update\n\n# Browser\nkatulong browse                         # Open localhost in browser\n\n# Sessions\nkatulong session create \u003cname\u003e [--open] # Create (--open shows in browser)\nkatulong session list                   # List sessions\nkatulong session kill \u003cname\u003e            # Kill a session\n\n# Messaging (inter-session pub/sub)\nkatulong pub \u003ctopic\u003e \u003cmessage\u003e          # Publish to a topic\nkatulong sub \u003ctopic\u003e [--once] [--json]  # Subscribe (streams to stdout)\nkatulong topics                         # List active topics\nkatulong notify \u003cmessage\u003e               # Send native notification\n\n# Auth\nkatulong token create \u003cname\u003e            # Create setup token (shows QR code)\nkatulong apikey create \u003cname\u003e           # Create API key for external access\nkatulong credential list                # List registered passkeys\n\n# Other\nkatulong info                           # System info\nkatulong service install                # Auto-start on login (macOS)\n```\n\n## Terminals as first-class cards\n\nKatulong's UI is a carousel of terminal cards. Each card is a live tmux\nsession with its own xterm.js front face and a small status dashboard\non the back face — flip between them with a 3D animation.\n\n```js\n// From the browser console:\nconst { carousel } = window.__tiles;\nconst id = carousel.getFocusedCard();\ncarousel.flipCard(id);\n```\n\nFlipping to the back face shows the session's child processes, run\nduration, and quick actions (kill, restart, copy output). When the\nagent running inside the terminal finishes its work, the card\nauto-flips to the dashboard after a short delay.\n\nMultiple terminals in one view (the \"cluster\") is the next step.\n\n## Security\n\nThis application provides direct shell access to the host. Security isn't optional.\n\n- **WebAuthn passkeys** — First device registers via passkey. Additional devices pair via QR code + PIN.\n- **No passwords** — Identity is proven by cryptographic key, not a shared secret.\n- **Localhost bypass** — Local connections auto-authenticate. Remote connections require a session cookie.\n- **30-day sessions** — Server-side tokens, pruned on expiry. No tokens in URLs or localStorage.\n\n## How it works\n\n```\nAny browser  \u003c──WebSocket──\u003e  Katulong server\n                              ├── Terminal sessions (tmux)\n                              ├── Tile system (pluggable UI)\n                              ├── File browser\n                              ├── Port proxy\n                              └── Auth (WebAuthn)\n```\n\nSessions live in tmux on the host. Restart the server, your sessions survive. The browser reconnects and replays the output buffer. Close your laptop, open your phone — same session, same scrollback.\n\n### Touch-first design\n\nBuilt for iPad and mobile from day one:\n\n- Card carousel with swipe navigation between tiles\n- Dedicated text input area (works with dictation/speech-to-text)\n- Swipe arrow keys, pinned Esc/Tab buttons\n- Floating shortcut island, draggable and auto-clamped to viewport\n- PWA-ready — install as a full-screen app\n\n### Environment\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PORT` | `3001` | Server port |\n| `SHELL` | `/bin/zsh` | Shell to spawn in sessions |\n| `KATULONG_DATA_DIR` | `~/.katulong` | Auth state, config, and tiles |\n\n## Development\n\n```bash\nnpm install           # Install dependencies\nnpm run dev           # Run server with auto-reload\nnpm test              # All tests\nnpm run test:unit     # Unit tests only\nnpm run test:e2e      # End-to-end tests (Playwright)\n```\n\n## License\n\nLicensed under either of:\n\n- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))\n- MIT license ([LICENSE-MIT](LICENSE-MIT))\n\nat your option.\n\n### Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally\nsubmitted for inclusion in the work by you, as defined in the Apache-2.0\nlicense, shall be dual licensed as above, without any additional terms or\nconditions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdorky-robot%2Fkatulong","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdorky-robot%2Fkatulong","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdorky-robot%2Fkatulong/lists"}