0xcaff/codex-web

What is codex‑web?

codex‑web 는 Codex Desktop AI 에이전트 플랫폼의 브라우저 기반 UI를 제공하는 가벼운 Node.js 래퍼입니다. 실제 작업은 사용자가 제어하는 기계(노트북, 홈 서버, 클라우드 VM 등)에서 수행되며, 어떤 기기에서도 에이전트를 제어할 수 있습니다.

실제로는 다음과 같은 방식으로 작동합니다:

브라우저 UI를 제공하는 Node.js 서버를 시작합니다.
이 UI를 codex CLI(codex desktop 에이전트 플랫폼의 명령줄 클라이언트)에 연결합니다.
파일 접근, 자격 증명 사용, 명령 실행과 같은 무거운 작업은 브라우저가 아닌 호스트 기계에서 수행합니다.

결과적으로, 데스크톱 전용 경험을 스마트폰, 태블릿, 또는 원격 컴퓨터에서 설치 없이도 접근할 수 있는 가벼운 래퍼가 됩니다.

Why does it exist?

원래의 Codex Desktop 은 터미널 창에서 실행되며, 장시간 실행되는 에이전트나 데스크톱 클라이언트가 설치되지 않은 기기에서 사용하기에는 불편합니다. HTTP를 통해 UI를 노출함으로써 다음이 가능해집니다:

노트북을 닫은 후에도 에이전트를 계속 실행할 수 있습니다.
브라우저를 갖춘 어떤 기기에서든 재연결할 수 있습니다.
백엔드를 신뢰할 수 있는 기계에 두어 로컬 파일, 자격 증명, 로그인된 OpenAI 계정에 대한 접근을 유지할 수 있습니다.

How to get it running

전제 조건 – 호스트 기계에 codex CLI가 설치되어 있고, codex login --device-auth 로 로그인되어 있어야 합니다.

서버 시작 – npx 또는 Nix를 사용해 시작할 수 있습니다:

npx --yes github:0xcaff/codex-web   # 한 줄 명령, 설치 필요 없음
# 또는
nix run github:0xcaff/codex-web

브라우저에서 http://127.0.0.1:8214 (또는 설정한 주소)를 엽니다.

고급: 외부 앱 서버로 프록시

codex‑web 의 크래시가 에이전트 프로세스를 종료하지 않도록 하려면, 앱 서버를 수동으로 시작하고 codex_remote_proxy 스크립트를 사용해 Unix 소켓에 연결할 수 있습니다. README에는 정확한 명령어 시퀀스가 포함되어 있습니다.

Security considerations

웹 UI는 호스트 사용자가 실행할 수 있는 모든 명령을 실행할 수 있으므로, 서버에 접근 가능한 네트워크 피어는 호스트를 완전히 제어할 수 있습니다. 권장 사항:

신뢰할 수 있는 네트워크에서만 서버를 실행하세요.
VPN, WireGuard, Tailscale, 또는 SSH 터널 뒤에 배치하세요.
더 엄격한 접근 제어가 필요하면 외부 리버스 프록시 또는 인증 게이트웨이를 추가하세요.

Current features

macOS, Linux, 그리고 codex CLI + Node가 동작하는 모든 플랫폼에서 작동.
브라우저 기반 UI(가벼운 래퍼, 업데이트가 빠름).
Codex Desktop 기능을 지원:
- 서브에이전트 – 다른 에이전트를 생성할 수 있는 에이전트.
- 인라인 이미지 – UI 내에서 직접 표시되는 시각적 출력.
- 에디터 사이드패널 – 웹 뷰에 내장된 코드 에디터.
- 음성 인식 – 음성에서 텍스트로 변환 통합.

Roadmap (what’s missing)

브라우저 패널 – 추가 웹 콘텐츠를 임베드하기 위해 iframe을 사용할 예정.
Linux 컴퓨터 사용 통합 – 에이전트가 Linux 데스크톱을 제어할 수 있도록.
터미널 지원 – 브라우저를 통해 인터랙티브 셸에 접근.
Git 워커 통합 – Git 작업을 더 밀접하게 통합.
일반적인 커뮤니티 주도 개선.

Who’s it for?

이미 Codex Desktop 을 사용 중이며, 이식 가능하고 브라우저 기반 UI를 원하는 개발자.
중앙의 항상 실행 중인 기계에서 에이전트를 실행하고, 사용자는 어디서든 접근하고자 하는 팀.
네트워크를 통해 강력한 로컬 에이전트를 노출하는 보안적 함의를 이해할 수 있는 사람.

Alternatives mentioned

pocodex – 이전 프로젝트로, 서브에이전트 및 인라인 이미지 지원이 없음.
Codex Remote (내장 기능 플래그) – SSH를 통해 작동하지만, 클라이언트 측에 데스크톱 클라이언트가 필요하므로 모바일 친화적이지 않음.
OpenAI의 곧 출시 예정인 모바일 앱 – 아직 출시되지 않음; codex‑web 이 현재의 공백을 메우고 있음.

How to contribute or get help

버그나 기능 요청은 리포지토리의 이슈를 열어주세요.
흥미로운 사용 사례를 X(Twitter)에 공유하고 @0xcaff 를 태그하세요.
상용 또는 고도로 맞춤화된 배포의 경우, 저자에게 이메일로 직접 연락을 환영합니다.

TL;DR

codex‑web 은 Codex Desktop AI 에이전트 플랫폼을 브라우저에서 접근 가능한 UI로 전환하는 최소한의 Node.js 서버입니다. 모든 실행은 신뢰할 수 있는 호스트에서 이루어지며, 원격, 모바일, 다중 기기 접근에 유용하지만, 서버에 접근 가능한 누구나 호스트를 완전히 제어할 수 있으므로 보안을 철저히 해야 합니다.