https://github.com/likescape/ttyd-tmux
tmux 작업 공간을 웹브라우저로 여는 도구 — Tailscale 폐쇄망, 명령 한 줄
https://github.com/likescape/ttyd-tmux
bash remote-access self-hosted ssh tailscale tmux ttyd web-terminal
Last synced: 10 days ago
JSON representation
tmux 작업 공간을 웹브라우저로 여는 도구 — Tailscale 폐쇄망, 명령 한 줄
- Host: GitHub
- URL: https://github.com/likescape/ttyd-tmux
- Owner: likescape
- License: mit
- Created: 2026-07-03T08:05:01.000Z (19 days ago)
- Default Branch: main
- Last Pushed: 2026-07-03T08:27:22.000Z (19 days ago)
- Last Synced: 2026-07-03T10:24:22.314Z (19 days ago)
- Topics: bash, remote-access, self-hosted, ssh, tailscale, tmux, ttyd, web-terminal
- Language: Shell
- Size: 11.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ttyd-tmux
**서버의 작업 공간을 웹브라우저로 열어주는 도구.**
평소엔 서버에 SSH로 접속해 일하다가, 밖에 있을 땐 **폰이나 PC 브라우저로** 같은 화면에 들어가
진행 상황을 보거나 이어서 작업할 수 있게 해줍니다.
---
## 먼저, 세 가지 부품을 쉽게 설명하면
| 부품 | 하는 일 | 비유 |
|---|---|---|
| **tmux** | 서버 안에서 **계속 켜져 있는 작업 공간(화면)**을 만들어 줍니다. 창을 닫아도 안 꺼집니다. | 불을 꺼도 하던 게 그대로인 **방** |
| **ttyd** | 그 작업 공간을 **웹브라우저 화면으로 보여주는** 프로그램입니다. | 방을 밖에서 볼 수 있는 **창문** |
| **Tailscale** | 내 기기와 서버를 잇는 **안전한 사설 네트워크**(앱). 인터넷에 문을 열지 않고도 접속하게 해줍니다. | 나만 드나드는 **비밀 복도** |
**ttyd-tmux** 는 이 셋을 엮어서, "작업 공간을 웹으로 여는 일"을 명령 한 줄로 해줍니다.
### 핵심 한 가지 — 웹은 "창문"일 뿐입니다
작업 공간(방)은 **서버 안에 계속 있습니다.** 웹으로 들어가는 건 **그 방을 창문으로 들여다보는 것**뿐이에요.
- 그래서 **브라우저를 닫아도** 방 안에서 하던 일은 그대로 남습니다.
- **SSH로 들어가든, 웹으로 들어가든 같은 방**이라서 화면이 똑같이 보입니다(동시 접속 가능).
- 웹을 안 열어도 방은 살아 있습니다. 웹은 그저 밖에서 볼 때 쓰는 통로예요.
```
[폰 브라우저] ──(Tailscale: 안전한 복도)──▶ [ttyd: 창문] ──▶ 작업 공간(방)
▲
[내 PC] ─────────────(SSH로)──────────────────────────────┘
```
---
## 무엇이 필요한가요?
- **Ubuntu 서버** (어떤 종류든 OK — 인텔/AMD(amd64), ARM(arm64) 자동으로 맞춰 설치)
- 인터넷 연결, `sudo` 사용 권한
- 본인 **Tailscale 계정** (무료), 그리고 접속할 폰/PC에 **Tailscale 앱** 설치
---
## 설치 (한 번만)
```bash
git clone <이 저장소 주소> ttyd-tmux
cd ttyd-tmux
bash install.sh
```
설치 중 딱 한 번, **Tailscale 로그인**을 합니다. 화면에 뜨는 웹 주소를 폰/PC 브라우저로 열어
'허용'만 누르면 됩니다. (비밀번호나 키는 파일에 저장되지 않아요. 설치는 여러 번 실행해도 안전합니다.)
> `install.sh` 는 tmux · ttyd · Tailscale 만 설치하는 **순수 범용 도구**입니다.
> 작업 공간 안에서 무엇을 돌릴지는 여러분 자유예요(그냥 셸, 원하는 프로그램 등).
---
## 사용법
### 작업 공간을 웹으로 열기
```bash
ttyd-tmux up 일감1 9090
```
- `일감1` = 작업 공간에 붙일 **별명**(원하는 대로). `9090` = 접속에 쓸 **번호(포트)**.
- 이러면 백그라운드에서 켜집니다. **이 명령이 화면을 붙잡지 않고**, 서버를 재시작해도 유지됩니다.
- 작업 공간을 새로 만들 때 안에서 **특정 프로그램을 실행**하고 싶으면 뒤에 붙이세요:
```bash
ttyd-tmux up 모니터 9091 htop # '모니터' 를 열고 htop 실행
```
아무것도 안 적으면 그냥 셸이 뜹니다. 여러 개 열려면 **번호만 다르게** 하면 됩니다.
### 접속하기
폰/PC에서 **Tailscale 앱을 켜고**, 브라우저 주소창에:
```
http://<내 서버의 Tailscale 주소>:9090
```
서버의 Tailscale 주소는 서버에서 `tailscale ip -4` 또는 `ttyd-tmux url 일감1` 로 확인할 수 있어요.
### 확인·관리
```bash
ttyd-tmux ls # 지금 열려 있는 목록 (이름 / 번호 / 웹 켜짐 / 작업공간 있음)
ttyd-tmux url 일감1 # 접속 주소 보여주기
ttyd-tmux stop 일감1 # 웹 창만 잠깐 닫기 (작업 공간은 그대로)
ttyd-tmux down 일감1 # 웹 창 + 작업 공간까지 통째로 정리
```
### 서버에서 (SSH로) 같은 작업 공간에 들어가기
```bash
tmux attach -t 일감1 # 웹에서 보는 것과 똑같은 화면 (나가려면 Ctrl-b 누르고 d)
tmux ls # 작업 공간 목록
```
---
## 안전한가요?
- **인터넷에 노출되지 않습니다.** 웹 창(ttyd)은 오직 Tailscale 네트워크로만 열립니다.
그래서 서버의 방화벽을 건드릴 필요가 없고, 외부에서 주소를 알아도 들어올 수 없어요.
- **내 Tailscale 네트워크에는 내 기기들만** 들어있습니다. 남은 위험은 사실상 **내 폰/PC를 잃어버리는 것** 정도예요.
→ 그래서 (1) 신뢰하는 내 기기만 Tailscale에 등록하고, (2) 폰·PC에 화면 잠금(지문/PIN)을 걸어두면 충분합니다.
- 웹 창에 접속 비밀번호를 걸고 싶으면, 설정 파일 `/etc/ttyd-tmux.d/<이름>.env` 에
`TTYD_TMUX_AUTH=아이디:비번` 을 추가하면 됩니다.
- **비밀 값은 저장소에 없습니다.** Tailscale 로그인은 설치 중 한 번 할 뿐이고,
키·비밀번호가 스크립트나 깃에 남지 않습니다.
---
## 잘 안 될 때
| 이런 증상 | 이렇게 해보세요 |
|---|---|
| `tmux attach` 시 "can't find session" | 그 작업 공간이 아직 없어서 그래요. `ttyd-tmux up <이름> <번호>` 로 먼저 여세요. |
| 웹 주소를 열어도 안 뜸 | `ttyd-tmux ls` 로 '웹=켜짐'인지 확인. 껴져 있으면 `ttyd-tmux up <이름> <번호>` 다시. |
| `run` 을 썼더니 화면을 계속 붙잡음 | `run` 은 테스트용이에요. 평소엔 `ttyd-tmux up`(백그라운드)을 쓰세요. |
| 접속 주소를 모르겠음 | `ttyd-tmux url <이름>` 또는 `tailscale ip -4` |
| Tailscale 이 로그인 안 됨 | `tailscale status` 확인 후 `sudo tailscale up` |
---
## 지우기
```bash
bash uninstall.sh # ttyd-tmux 관련 전체 정리
# 또는 하나만:
ttyd-tmux down <이름>
```
설치했던 프로그램(ttyd·tmux·Tailscale)과 로그인, 다른 작업 공간은 그대로 남겨둡니다.
완전 삭제 방법은 `uninstall.sh` 실행 후 안내를 참고하세요.
---
## 파일 구성
| 파일 | 하는 일 |
|---|---|
| `install.sh` | 설치 (프로그램 설치 · Tailscale 로그인 · `ttyd-tmux` 명령 등록). |
| `bin/ttyd-tmux` | 실제 도구. `up`/`down`/`ls`/`url`/`stop`/`run` 명령을 담고 있음. |
| `uninstall.sh` | 정리(삭제). |
## License
MIT — [LICENSE](LICENSE) 참고.