{"id":31074162,"url":"https://github.com/norastech/detached-shell","last_synced_at":"2025-10-26T13:07:16.090Z","repository":{"id":314277313,"uuid":"1054845317","full_name":"NorasTech/detached-shell","owner":"NorasTech","description":"Noras Tech's Detached Shell Solution - No complex configurations. It's not like a literal terminal multiplexer. Just a shell detachable with persistent sessions. Use your emulator's tabs and splittings.","archived":false,"fork":false,"pushed_at":"2025-09-11T13:05:43.000Z","size":55,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-11T15:53:08.596Z","etag":null,"topics":["detachable","shell","terminal"],"latest_commit_sha":null,"homepage":"https://nds.noras.dev","language":"Rust","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/NorasTech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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-09-11T12:10:08.000Z","updated_at":"2025-09-11T13:05:47.000Z","dependencies_parsed_at":"2025-09-11T15:53:10.412Z","dependency_job_id":"dbccee1a-217a-4f5f-8d70-6f1cea4e034e","html_url":"https://github.com/NorasTech/detached-shell","commit_stats":null,"previous_names":["norastech/detached-shell"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/NorasTech/detached-shell","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NorasTech%2Fdetached-shell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NorasTech%2Fdetached-shell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NorasTech%2Fdetached-shell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NorasTech%2Fdetached-shell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NorasTech","download_url":"https://codeload.github.com/NorasTech/detached-shell/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NorasTech%2Fdetached-shell/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275706287,"owners_count":25513176,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-18T02:00:09.552Z","response_time":77,"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":["detachable","shell","terminal"],"created_at":"2025-09-16T02:04:10.938Z","updated_at":"2025-10-26T13:07:16.084Z","avatar_url":"https://github.com/NorasTech.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NDS - Noras Detached Shell 🚀\n\n\u003cdiv align=\"center\"\u003e\n\n[![Crates.io](https://img.shields.io/crates/v/detached-shell.svg)](https://crates.io/crates/detached-shell)\n[![Rust](https://img.shields.io/badge/rust-%23000000.svg?style=for-the-badge\u0026logo=rust\u0026logoColor=white)](https://www.rust-lang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)\n\nSimple detachable shell sessions with zero configuration. Not a complex multiplexer like tmux or screen - just clean, persistent sessions you can attach and detach as needed.\n\n[Features](#features) • [Installation](#installation) • [Usage](#usage) • [Documentation](#documentation) • [Contributing](#contributing)\n\n\u003c/div\u003e\n\n## ✨ Features\n\n- 🎯 **Simple Session Management**: Create, detach, and reattach shell sessions with ease\n- 🪶 **Lightweight**: \u003c 1MB single binary with zero configuration required\n- ⚡ **Fast**: Written in Rust for maximum performance\n- 🎨 **User-Friendly**: Intuitive commands with partial ID and name matching\n- 🖥️ **Interactive Mode**: Sleek TUI session picker with real-time status\n- 📝 **Session History**: Track all session events with persistent history\n- 🧹 **Auto-Cleanup**: Automatic cleanup of dead sessions\n- 🔄 **Session Switching**: Simple attach/detach without complex multiplexing\n- 🏷️ **Named Sessions**: Give meaningful names to your sessions\n- 🐧 **Cross-Platform**: Works on Linux and macOS\n\n## 🎯 Philosophy\n\nNDS transforms your normal shell into a detachable, persistent session without changing how you work. No panes, no tabs, no complex layouts - just your shell, but better. When you need splits or tabs, your terminal emulator already handles that perfectly. NDS does one thing exceptionally well: making any shell session detachable and persistent.\n\n## 📦 Installation\n\n\n### Using Cargo\n\n```bash\ncargo install detached-shell\n```\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/NorasTech/detached-shell.git\ncd detached-shell\n\n# Build and install (recommended)\n./scripts/install.sh\n\n# Or manually\ncargo build --release\nsudo cp target/release/nds /usr/local/bin/\n```\n\n\n## 🚀 Quick Start\n\n```bash\n# Create a new session\nnds new\n\n# List sessions\nnds list\n\n# Attach to a session\nnds attach abc123\n\n# Detach from current session\n# Press Enter, then ~d (like SSH's escape sequences)\n```\n\n## 📖 Usage\n\n### Creating Sessions\n\n```bash\n# Create and attach to a new session\nnds new\n\n# Create a named session\nnds new \"project-dev\"\n\n# Create without attaching\nnds new --no-attach\n```\n\n### Managing Sessions\n\n```bash\n# List all active sessions\nnds list\nnds ls\n\n# Interactive session picker with TUI\nnds interactive  # or just 'nds' for short\n\n# Attach to a session (supports partial ID and name matching)\nnds attach abc123\nnds attach project-dev  # attach by name\nnds a abc  # partial ID works\nnds a proj  # partial name works\n\n# Kill sessions (supports ID and name)\nnds kill abc123\nnds kill project-dev  # kill by name\nnds kill abc def ghi  # kill multiple sessions\n\n# Clean up dead sessions\nnds clean\n```\n\n### Session Information\n\n```bash\n# Get detailed info about a session (supports ID and name)\nnds info abc123\nnds info project-dev  # info by name\n\n# Rename a session (supports ID and name)\nnds rename abc123 \"new-name\"\nnds rename project-dev \"production\"  # rename by current name\n\n# View session history\nnds history              # Active sessions only\nnds history --all        # Include archived sessions\nnds history -s abc123    # History for specific session\n```\n\n### Keyboard Shortcuts (Inside Session)\n\n- `Enter, ~d` - Detach from current session (like SSH's `~.` sequence)\n- `Ctrl+D` - Detach from current session (when at empty prompt)\n- `Enter, ~s` - Switch to another session interactively\n\n## 🏗️ Architecture\n\nNDS uses a simple and robust architecture:\n\n- **PTY Management**: Each session runs in its own pseudo-terminal\n- **Unix Sockets**: Communication via Unix domain sockets (0600 permissions)\n- **JSON Metadata**: Session info stored in `~/.nds/sessions/`\n- **Per-Session History**: History stored in `~/.nds/history/`\n- **Zero Dependencies**: Minimal external dependencies for reliability\n- **Async I/O Support**: Optional async runtime with Tokio for high concurrency\n- **Optimized Buffers**: 16KB buffers for 4x throughput improvement\n\n### Directory Structure\n\n```\n~/.nds/\n├── sessions/       # Session metadata (JSON)\n├── sockets/        # Unix domain sockets (0600 permissions)\n└── history/        # Session history\n    ├── active/     # Currently running sessions\n    └── archived/   # Terminated sessions\n```\n\n## 🔐 Security\n\nNDS implements multiple security layers to protect your sessions:\n\n### Session Isolation\n- **Unix Socket Permissions**: All sockets created with `0600` (owner read/write only)\n- **Session Umask**: Sessions run with `umask 0077` for restrictive file creation\n- **Process Isolation**: Each session runs in its own process with separate PTY\n\n### Input Validation\n- **Command Whitelisting**: Only safe NDS control commands allowed (`resize`, `detach`, `attach`, etc.)\n- **Input Sanitization**: Control characters and potentially harmful inputs are filtered\n- **Buffer Limits**: Maximum 8KB command length and 10 arguments to prevent overflow\n- **Numeric Bounds**: Terminal dimensions limited to 1-9999 to prevent resource exhaustion\n\n### Important Note\nNDS is a terminal multiplexer, not a sandbox. Shell commands within sessions are **not** restricted - you have full access to your shell just as you would in a normal terminal. The security measures protect the NDS control plane and session management, not the shell commands you run inside sessions.\n\n## ⚡ Performance\n\nNDS is optimized for speed and efficiency:\n\n### Buffer Optimization\n- **16KB I/O Buffers**: 4x throughput improvement over standard 4KB buffers\n- **2MB Scrollback Buffer**: Increased from 1MB for better history retention\n- **Benchmarked**: 25+ GB/s throughput in buffer operations\n\n### Async I/O (Optional)\nEnable async features for high-concurrency scenarios:\n\n```toml\n# Cargo.toml\n[dependencies]\ndetached-shell = { version = \"0.1\", features = [\"async\"] }\n```\n\nWith async enabled:\n- Non-blocking socket operations\n- Concurrent session management with `Arc\u003cRwLock\u003e`\n- Tokio runtime for scalable I/O\n\n## 🔧 Configuration\n\nNDS works out of the box with zero configuration. However, you can customize:\n\n### Environment Variables\n\n```bash\n# Change default shell (default: $SHELL or /bin/sh)\nexport NDS_SHELL=/bin/zsh\n\n# Session identification (automatically set inside sessions)\nNDS_SESSION_ID      # Current session ID when attached\nNDS_SESSION_NAME    # Current session name (if set)\n\n# Change detach key binding (coming soon)\nexport NDS_DETACH_KEY=\"ctrl-a d\"\n```\n\n## 🤝 Contributing\n\nWe love contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n```bash\n# Clone the repo\ngit clone https://github.com/NorasTech/detached-shell.git\ncd detached-shell\n\n# Run tests\ncargo test\n\n# Run with debug logs\nRUST_LOG=debug cargo run -- list\n\n# Quick rebuild and test\n./scripts/dev.sh quick\n```\n\n### Running Tests\n\n```bash\n# Run all tests (55+ unit and integration tests)\ncargo test\n\n# Run with all features including async\ncargo test --all-features\n\n# Run specific test categories\ncargo test --test security_test     # Security tests\ncargo test --test session_lifecycle  # Integration tests\n\n# Run with coverage\ncargo tarpaulin --out Html\n\n# Run performance benchmarks\ncargo run --release --bin buffer_benchmark\n```\n\n## 🚧 Project Status\n\n**Alpha Release** - NDS is in active development. Core functionality is stable, but expect breaking changes.\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Inspired by GNU Screen and tmux\n- Built with [Rust](https://www.rust-lang.org/) 🦀\n- Terminal handling via [libc](https://github.com/rust-lang/libc)\n\n## 🐛 Troubleshooting\n\n### Session not found after reboot\nSessions don't persist across system reboots by design. Use `nds history --all` to see past sessions.\n\n### Permission denied errors\nEnsure `~/.nds/` directory has proper permissions:\n```bash\nchmod 700 ~/.nds\nchmod 700 ~/.nds/sockets\n```\n\n### Can't detach from session\nMake sure you're using the correct key sequence: press Enter first, then `~d` (similar to SSH's escape sequences).\n\n### Half screen or duplicated lines after attaching\nIf you see only part of a full-screen app (like `htop`) or repeated prompt lines after reattaching, upgrade to the latest NDS build. Earlier versions flipped the client socket to non-blocking mode before replaying buffered output, dropping large frames and queuing failures. Recent releases send the backlog while still blocking, then queue any partial writes so slow terminals catch up cleanly.\n\n## 📮 Support\n\n- 🐛 [Report bugs](https://github.com/NorasTech/detached-shell/issues)\n- 💡 [Request features](https://github.com/NorasTech/detached-shell/issues)\n- 💬 [Discussions](https://github.com/NorasTech/detached-shell/discussions)\n\n---\n\n\u003cdiv align=\"center\"\u003e\nMade with ❤️ and 🦀 by \u003ca href=\"https://noras.tech\"\u003eNoras Technologies\u003c/a\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnorastech%2Fdetached-shell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnorastech%2Fdetached-shell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnorastech%2Fdetached-shell/lists"}