⚡ OxideTerm

원격 서버를 위한 AI 기반 네이티브 운영 워크스페이스 — 순수 Rust 네이티브 앱
SSH, Telnet, 시리얼, RDP/VNC, SFTP, 포트 포워딩, 경량 편집을 하나의 네이티브 워크스페이스에.
GPU 직접 렌더링. 무료, 계정 불필요.
Electron 미사용. WebView 번들 없음. 텔레메트리 없음. 구독 없음. BYOK 우선. OpenSSL/libssh2 없는 순수 Rust SSH.

_{오픈 소스, 로컬 우선, GPUI 기반 GPU 렌더링.}

OxideTerm 기능 개요

--- ## OxideTerm란 OxideTerm는 SSH와 원격 운영을 위한 오픈 소스 작업 공간입니다. 터미널, 파일, 포트 포워딩, 호스트 도구, 원격 데스크톱을 한곳에서 다룹니다. **할 수 있는 작업:** - SSH, Telnet, 시리얼, RDP/VNC, SFTP, 포트 포워딩, 로컬 셸, 가벼운 편집을 하나의 작업 공간에서 관리 - Grace Period 재연결로 짧은 네트워크 중단 중에도 원격 작업 유지 - 자체 AI 공급자를 통해 OxideSens에 활성 세션 점검과 승인된 작업 공간 작업 실행 요청 연결 정보와 운영 데이터는 사용자가 관리합니다. OxideSens는 사용자의 AI 공급자를 사용하며 계정이 필요하지 않습니다. --- ## 왜 OxideTerm인가? - SSH, Telnet, 시리얼, RDP/VNC, SFTP, 포트 포워딩, 로컬 셸을 하나의 데스크톱 앱에 통합 - 짧은 네트워크 중단을 견디는 Grace Period 재연결 - 자체 AI 자격 증명과 승인된 작업을 사용하는 OxideSens - Electron과 번들 브라우저 런타임이 없는 GPUI 인터페이스 --- ## 스크린샷 아래 스크린샷은 OxideTerm의 터미널, 파일, 편집, 포워딩 흐름을 보여 줍니다.

SSH 터미널 + OxideSens AI	SFTP 파일 관리자
내장 IDE	스마트 포트 포워딩

--- ## 원격 운영을 위한 설계 OxideTerm는 연결, 파일, 포워딩, 호스트 도구, 자동화, AI 컨텍스트를 하나의 Rust 작업 공간에 둡니다. 도구는 같은 서버 ID와 세션 수명 주기를 공유합니다. | 항목 | 번들 브라우저 방식 | OxideTerm | |---|---|---| | **렌더링** | 브라우저 엔진과 웹 레이아웃 | GPU 표면의 GPUI | | **터미널 데이터 흐름** | WebSocket → JS 이벤트 루프 → xterm.js | Rust 입력 → `TerminalState` 변경 → GPUI 렌더링 | | **연결 수명 주기** | 프런트엔드와 백엔드 계층에 분산 | 프로세스 내부의 단일 연결 및 재연결 파이프라인 | | **AI 컨텍스트** | 애플리케이션 브리지를 통해 복사 | 사용자 승인 아래 활성 작업 공간에서 구성 | | **플러그인 런타임** | 브라우저 스크립트 환경 | manifest-only, 기능 제한 WASM, 명시적 신뢰가 필요한 프로세스 경로 | | **CLI** | 데스크톱 앱 실행이 필요 | Crate에 직접 연결한 독립 바이너리 | | **런타임 경계** | 데스크톱 래퍼와 브라우저 런타임 | 번들 브라우저 런타임 없는 네이티브 프로세스 | --- ## 기능 | 범주 | 기능 | |---|---| | **터미널 및 연결** | 로컬 셸, SSH, Telnet, 시리얼, 분할 창, 자유 입력 모드, 여러 대상에 대한 고급 명령 전송, 멀티홉, 안정적인 재연결 | | **파일 및 원격 편집** | SFTP, 전송 대기열, 즐겨찾기, 안전한 쓰기, 프로젝트 트리, 탭 편집 | | **포워딩 및 네트워크** | 로컬·원격·동적 SOCKS5 포워딩, 저장된 규칙, 소켓 디버깅 | | **호스트 운영 및 원격 데스크톱** | 모니터링, 프로세스, 서비스, 로그, 포트, 작업, 디스크, 패키지, 컨테이너, tmux, RDP, VNC | | **OxideSens 및 자동화** | 자체 AI 공급자, MCP, 로컬 RAG, Agent Skills, 공급자별 추론 제어, 승인된 작업, 암호화 동기화, CLI | | **확장 및 개인화** | manifest-only, WASM, 프로세스 플러그인, 사용자 탭, 빠른 명령, 테마, 배경, 단축키, 11개 언어 | ---

*OxideSens가 사용자 요청을 따라 OxideTerm 안에서 터미널을 여는 모습입니다.*

--- ## 아키텍처 OxideTerm는 터미널, SSH, Telnet, RDP, VNC, SFTP, 포워딩, IDE, AI, 플러그인, CLI를 하나의 Rust 아키텍처에 통합합니다. 기술 세부 사항은 아래에 설명합니다.

아키텍처, SSH 내부, GPUI 셸, 재연결, AI, 플러그인 등

### 아키텍처 — 프로세스 내부 코어, WebView 브리지 없음 ```text GPUI 렌더링 루프 WorkspaceApp / 탭 화면 / GPUI 뷰 │ in-process Arc<> / async 도메인 Crate NodeRouter → SshConnectionRegistry TerminalState ← SSH PTY channel SftpSession / ForwardingRuntime / IdeWorkspace Ai/ACP Entities / CloudSync / Plugin Runtimes ``` UI와 SSH/터미널 백엔드 사이에는 직렬화 경계가 없습니다. 터미널 바이트는 `TerminalState`를 직접 변경하고 GPUI는 상태를 읽어 GPU 그리기 명령을 발행합니다. ### 순수 Rust SSH — russh (ring) - **SSH 스택에 OpenSSL/libssh2 없음** — SSH 암호화는 `ring`으로 제공 - 전체 SSH2: 키 교환, 채널, SFTP 서브시스템, 포트 포워딩 - ChaCha20-Poly1305 / AES-GCM, Ed25519/RSA/ECDSA 키 - SSH Agent: Unix (`SSH_AUTH_SOCK`)와 Windows (`\\.\pipe\openssh-ssh-agent`) - 각 홉에서 독립적으로 인증하는 다중 홉 ProxyJump ### Grace Period 기반 스마트 재연결 1. JavaScript timer throttling 없이 SSH keepalive timeout 감지 2. 터미널 패널, SFTP 전송, 포워딩, IDE 파일 스냅샷 3. Grace Period 동안 기존 연결을 30초 probe하여 네트워크 전환 시 TUI apps가 살아남을 수 있게 함 4. 복구 실패 시 재연결, 포워딩 복원, 전송 재개, IDE 파일 재오픈 Pipeline: `queued → snapshot → grace-period → ssh-connect → await-terminal → restore-포워딩 → resume-transfers → restore-ide → verify → done` ### SSH 연결 풀 및 노드 라우팅 - 기본 모드에서는 하나의 물리 SSH connection이 터미널 패널, SFTP, 포트 포워딩, IDE work를 공유하며, 터미널은 필요할 때 전용 connection을 사용할 수 있음 - 각 연결은 `connecting → active → idle → link_down → reconnecting` 상태를 이동 - UI는 `nodeId`로 command를 보내고 `NodeRouter`가 active `connectionId`를 atomic하게 resolve - `NodeRuntimeStore`는 노드 런타임 상태와 topology 스냅샷을 보유하며, workspace helper가 이를 `session_tree.json`에 기록하고 시작 시 실제 handle을 다시 구성 - 점프 호스트 장애는 하위 노드에 `link_down` 상태를 연쇄 전파 ### OxideSens AI OxideSens는 BYOK 우선을 유지하며 컨텍스트 구성은 프로세스 안에서 수행됩니다. - 제공자: OpenAI, Anthropic, Gemini, Ollama 또는 OpenAI 호환 엔드포인트 - MCP: stdio/SSE 전송, 도구 검색과 호출 - RAG: BM25 전문 검색, HNSW 벡터 인덱스, Reciprocal Rank Fusion, CJK 바이그램 토크나이저 - 제공자에게 보낼 메시지는 자격 증명 패턴을 마스킹하며, 작업 공간 컨텍스트와 작업은 사용자가 제어합니다 - API 키는 OS 키체인에 저장하며 구조화된 로그와 데스크톱 코어 메시지 대상에서 명시적으로 제외합니다 ### GPUI 데스크톱 셸 UI는 GPUI로 직접 그려지며 DOM/CSS/JavaScript rendering pipeline이 없습니다. - 작업 공간 탭 유형: local terminal, SSH, Telnet, Serial, RDP, VNC, SFTP, IDE, Forwards, Settings, Plugin, Topology 등 - draggable dividers를 가진 binary pane tree, terminal tab당 최대 4 panes - Command palette, global key bindings, sidebars는 GPUI primitives - 즉시 모드 렌더링은 직렬화 왕복 없이 Rust 상태 변화에 반응 ### 터미널 상태와 렌더링 터미널 렌더링은 먼저 Rust 상태로 모델링되고 GPUI가 그립니다. - PTY 출력은 `TerminalState`로 들어가며 scrollback, cursor, selection, marks, search state는 Rust 안에 유지됩니다 - 렌더링 policy는 Boost, Normal, Idle 사이를 전환할 수 있고 브라우저 이벤트 루프 협조를 기다리지 않습니다 - Sixel과 Kitty graphics는 DOM nodes나 canvas overlays가 아니라 terminal-owned assets로 추적됩니다 - 분할 패널은 같은 작업 공간 상태 모델을 공유하므로 탭 복원과 재연결이 터미널 토폴로지를 함께 스냅샷할 수 있습니다 ### SFTP 및 IDE 작업 공간 원격 파일은 분리된 부가 기능이 아니라 같은 노드 작업 공간의 일부입니다. - SFTP sessions는 `NodeRouter`와 connection generation으로 resolve됩니다. 재연결 시 유효한 session을 다시 얻을 수 있지만, 이전 generation의 작업을 새 connection으로 조용히 교체하지 않습니다 - 전송 대기열은 보이는 파일 창과 독립적으로 방향, 진행률, 재시도 상태, 속도 제한을 추적합니다 - IDE 탭은 수정된 버퍼, 원격 경로, 충돌 상태, 복원 메타데이터를 함께 보관합니다 - Backend가 지원하면 remote writes는 staged/atomic behavior를 사용해 일반 edit flow에서 partial writes를 줄입니다 ### 플러그인, CLI, 진단 확장 기능과 지원 기능은 Rust가 소유하는 명확한 경계 안에서 동작합니다. - 플러그인은 manifest-only, WASM, 일반 프로세스 경로를 지원합니다. WASM은 내장된 Wasmtime/WASI 런타임을 사용하며, 프로세스 플러그인은 운영 체제 샌드박스가 없는 로컬 프로세스입니다. - CLI는 도메인 crate에 직접 링크되어 doctor, settings, connections, 포워딩, 휴대용 번들, 백업, 보고서를 다룹니다 - 진단은 비밀이 포함된 원시 페이로드보다 개수, 경로, 기능 플래그, 마스킹된 힌트를 우선합니다 - 상태를 변경하는 CLI 흐름은 dry-run 계획, `--yes` 보호, 롤백 백업을 사용합니다 ### 포트 포워딩 — 잠금 없는 I/O - Local `-L`, Remote `-R`, Dynamic SOCKS5 `-D` - 하나의 `ssh_io` task가 각 SSH Channel을 소유하여 `Arc>` 회피 - 재연결 auto-restore, 종료 보고, 유휴 시간 초과 ### trzsz — 대역 내 파일 전송 trzsz는 계속 terminal stream을 사용하며 extra port나 remote agent가 필요 없습니다. - 기존 terminal stream을 통한 upload/download - ProxyJump chains를 통과해 동작 - Native file pickers로 browser memory limits 회피 - bidirectional transfer, directory support, configurable limits ### `.oxide` 암호화 내보내기 - **ChaCha20-Poly1305 AEAD** authenticated encryption - **Argon2id KDF**: 256 MB memory cost, 4 iterations로 GPU brute-force cost 증가 - connections, 포워딩, settings, quick commands, 플러그인 설정, 휴대용 비밀 포함

--- ## 소스에서 실행 **요구 사항:** Rust 툴체인(Edition 2024) 및 GPUI를 실행할 수 있는 데스크톱 환경. ```sh cargo run OXIDETERM_RENDER_PROFILE=compatibility cargo run ./scripts/build/build-cli.sh ./scripts/build/build-agent.sh ``` ## CLI 헤드리스 `oxideterm` CLI는 앱을 실행하지 않고도 사용할 수 있으며 자동화, CI, 진단에 유용합니다. ```sh cargo run -p oxideterm-cli -- doctor --strict cargo run -p oxideterm-cli -- settings validate --strict --json cargo run -p oxideterm-cli -- connections search prod cargo run -p oxideterm-cli -- forwards list --format json cargo run -p oxideterm-cli -- cloud-sync push --dry-run --json cargo run -p oxideterm-cli -- oxide export ./profile.oxide --connection prod --password-stdin cargo run -p oxideterm-cli -- report --bundle ./oxideterm-report.zip cargo run -p oxideterm-cli -- completion install zsh --force ``` ## 기술 스택 | 계층 | 기술 | 설명 | |---|---|---| | UI | GPUI (Zed) | GPU 기반 즉시 모드, 순수 Rust | | 런타임 | Tokio + DashMap | 비동기 실행과 동시성 맵 | | SSH | russh (`ring`) | SSH 스택에 OpenSSL/libssh2 없음, SSH Agent 지원 | | 터미널 | portable-pty + alacritty_terminal | 로컬 PTY, 터미널 에뮬레이션, Sixel/Kitty 그래픽 | | 플러그인 | Wasmtime/WASI 및 프로세스 | manifest-only, 제어된 WASM 호스트 호출, 명시적 신뢰가 필요한 로컬 프로세스 | | AI 및 검색 | SSE + BM25 + HNSW | 제공자 스트리밍, CJK 바이그램, RRF 결합 | | 편집기 | tree-sitter(구문), 사용자 버퍼 | 다국어, SFTP 기반 | | 암호화 | ChaCha20-Poly1305 + Argon2id | AEAD + 메모리 하드 KDF(256 MB) | | i18n | oxideterm-i18n | 내장 로더, 11개 제공 언어 | ## 보안 | Concern | Implementation | |---|---| | 저장된 자격 증명 | macOS Keychain / Windows Credential Manager / libsecret | | 메모리의 비밀 정보 | 비밀 정보를 소유한 타입과 임시 버퍼는 지원되는 소유권 경계에서 `zeroize` / `Zeroizing` 사용 | | 진단 | 지원 출력은 비밀 정보를 담은 원문보다 구조화된 메타데이터와 마스킹된 힌트를 우선 | | AI 컨텍스트 | 제공자에게 보낼 메시지는 자격 증명 패턴을 마스킹하며, 워크스페이스 컨텍스트와 작업은 사용자가 제어 | | `.oxide` | ChaCha20-Poly1305 + Argon2id | | CLI writes | dry-run 계획, `--yes` 보호, 롤백 백업 | | 호스트 키 | `~/.ssh/known_hosts`를 사용하는 TOFU, 예기치 않은 변경 거부 | | Plugins | Wasmtime/WASI 및 프로세스 | 제어된 WASM 호스트 호출과 OS 샌드박스가 없는 신뢰 기반 로컬 프로세스 | ## 적법한 사용 안내 OxideTerm은 추가 라이선스 제한 없이 GPL-3.0-only로 배포됩니다. 사용할 때에는 본인이 소유하거나 명시적인 접근 권한을 받은 시스템, 네트워크 및 장치에만 접근하고 관련 법률을 준수하십시오. 무단 접근, 서비스 방해 또는 접근 통제 우회에 OxideTerm을 사용하지 마십시오. ## 기여 코드, 문서, 번역, 플러그인, 테스트, 버그 재현 기여를 환영합니다. 큰 변경이나 범위가 명확한 수정은 Issue에서 먼저 논의해 주세요. ```sh cargo run -p oxideterm-cli -- report --bundle ./oxideterm-report.zip ``` --- ## 지원 및 유지관리 재현 단계와 마스킹된 진단이 포함된 버그 보고 및 회귀를 우선합니다. 기능 요청은 범위, 안전성, OxideTerm의 원격 서버 작업 공간 방향성과의 일치 여부를 기준으로 검토합니다.

OxideTerm이 작업 흐름에 도움이 된다면 GitHub 스타, 문제 재현 보고, 번역 수정, 플러그인이 프로젝트 지속에 도움이 됩니다. --- ## 라이선스 **GPL-3.0-only**. 자세한 제3자 고지는 [`THIRD_PARTY_NOTICES.md`](../../THIRD_PARTY_NOTICES.md)에, 추가 고지는 [`NOTICE`](../../NOTICE)에 기록되어 있습니다. ## 감사의 말 `russh`, `GPUI`, `alacritty_terminal`, `portable-pty`, `wasmtime`, `tree-sitter` 프로젝트에 감사드립니다.