https://github.com/uskhokhar/linux-display-extend
Use your Android device as a real extended display for Linux X11 sessions.
https://github.com/uskhokhar/linux-display-extend
bash good-first-issue linux shell vnc-server x11 x11vnc xrandr
Last synced: 17 days ago
JSON representation
Use your Android device as a real extended display for Linux X11 sessions.
- Host: GitHub
- URL: https://github.com/uskhokhar/linux-display-extend
- Owner: USKhokhar
- License: mit
- Created: 2025-08-01T06:57:27.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2026-04-03T14:00:08.000Z (3 months ago)
- Last Synced: 2026-04-20T19:41:03.829Z (2 months ago)
- Topics: bash, good-first-issue, linux, shell, vnc-server, x11, x11vnc, xrandr
- Language: Shell
- Homepage:
- Size: 62.5 KB
- Stars: 47
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: docs/SECURITY.md
- Support: docs/SUPPORT.md
Awesome Lists containing this project
README
# Linux Display Extend
Use your Android device as a real extended display for Linux X11 sessions.
[](LICENSE)
[](https://github.com/USKhokhar/linux-display-extend/stargazers)
[](https://github.com/USKhokhar/linux-display-extend/issues)
## What It Does
`linux-display-extend` combines:
- `xrandr` to attach and position an extra display output
- `x11vnc` to stream only that extended desktop region
- an Android VNC client to render and interact with the new display
It is designed for X11 sessions today. Wayland support is not implemented yet.
## Quick Start
Install with the canonical repo-root installer:
```bash
bash <(curl -fsSL https://raw.githubusercontent.com/USKhokhar/linux-display-extend/main/universal_installer.sh)
```
Then validate your machine and launch:
```bash
display-extend doctor
display-extend install-deps
display-extend start
```
On Android:
1. Install a VNC client such as RealVNC Viewer or MultiVNC.
2. Connect to the host and port printed by `display-extend start`.
3. If prompted, use the password stored in `~/.config/linux-display-extend/connection.secret`.
## Why This Release Is Better
- the runtime now respects configured resolution and position
- the tool tracks its own PID, output, and clip geometry instead of killing unrelated `x11vnc` processes
- config is parsed safely instead of being executed as shell
- VNC defaults now use password authentication instead of open `-nopw`
- the installer and package builder now have one canonical source of truth
- the CLI is branded and includes diagnostics, logs, and password management commands
## Commands
```bash
display-extend [options]
```
Core commands:
- `display-extend start`
- `display-extend stop`
- `display-extend restart`
- `display-extend status`
- `display-extend config`
Support commands:
- `display-extend doctor`
- `display-extend install-deps`
- `display-extend logs`
- `display-extend set-password`
- `display-extend install-vnc`
- `display-extend update`
- `display-extend --help`
- `display-extend --version`
Useful start options:
- `--resolution WxH`
- `--position right|left|above|below`
- `--monitor `
- `--port `
- `--bind `
- `--quality low-bandwidth|balanced|high-quality`
- `--insecure-lan`
- `--debug`
## Support Matrix
Currently supported and expected:
- Linux only
- X11 desktop sessions
- `xrandr`, `x11vnc`, and `cvt` available on the host
- at least one connected monitor plus one usable disconnected output target
See [DISTROS.md](DISTROS.md) for the current Linux distribution support matrix.
Currently not supported:
- Wayland sessions
- multi-device streaming
- encrypted transport without a separate tunnel or network layer
## Repository Layout
- `scripts/display-extend.sh`: canonical runtime source
- `universal_installer.sh`: canonical installer
- `display_extend_package.sh`: canonical Debian package tree builder
- `DISTROS.md`: Linux distribution support matrix
- `installer/`: compatibility wrappers around the root scripts
- `docs/`: architecture, testing, and security documentation
## Development
Common commands:
```bash
make test
make package
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for contributor workflow, architecture guidance, and pre-PR testing instructions across Linux, macOS, and Windows setups.
Project health files:
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
- [SECURITY.md](SECURITY.md)
- [SUPPORT.md](SUPPORT.md)
- [docs/RELEASE.md](docs/RELEASE.md)
## Troubleshooting
If the session will not start:
1. Run `display-extend doctor`.
2. If dependencies are missing, run `display-extend install-deps`.
3. Confirm you are on X11, not Wayland.
4. Check that `xrandr` shows a connected main monitor and at least one disconnected output.
5. Read the runtime logs with `display-extend logs`.
## License
[MIT](LICENSE)