DeepBlueDynamics/gnosis-container

상자 안에 담긴 AI 에이전트입니다. 하나의 스크립트로 Docker 컨테이너를 실행하며, 여기서 Codex는 275개 이상의 도구(tools)에 접근할 수 있고, 자체 실행을 예약하거나, 하위 에이전트(sub-agents)를 생성하고, 웹을 크롤링하며, 파일을 감시하고, 셸 명령(shell commands)을 실행할 수 있습니다. 사용자는 에이전트에게 부여할 권한의 양을 제어할 수 있으며, 설정을 통해 도구를 추가하거나 제거할 수 있습니다.

┌─────────────────────────────────────────────────────────────────┐
│ gnosis-container.ps1 │
│ ───────────────────── │
...

실행하는 세 가지 방법:

Windows PowerShell: pwsh 접두사를 생략하고 .\scripts\gnosis-container.ps1 ...를 직접 실행하세요.

모드	명령어	동작 내용
One Shot CLI	`pwsh ./scripts/gnosis-container.ps1 -Exec "do something"`	일회성 프롬프트, 완료 시 종료
API	`pwsh ./scripts/gnosis-container.ps1 -Serve -GatewayPort 4000`	HTTP 서버, 각 POST 요청 시 Codex 실행을 생성
Full power interactive	`pwsh ./scripts/gnosis-container.ps1 -Danger -Privileged`	제한 없는 Codex 샌드박스(sandbox) + Docker 특권 모드(privileged mode)

PowerShell 스크립트를 실행하려면 PowerShell이 필요합니다. Windows에서는 Windows PowerShell을 사용하고 pwsh를 입력하지 마세요 (.\scripts\gnosis-container.ps1 ... 실행). macOS/Linux에서는 PowerShell Core를 설치하세요: brew install --cask powershell (더 많은 정보 | brew 설치). Bash를 선호한다면 scripts/gnosis-container.sh를 사용하세요 (기능 차이가 있을 수 있음).

# 1. Docker 네트워크 생성 (1회)
docker network create codex-network
# 2. 이미지 빌드
...

제공되는 기능:

╭───────────────────────────────────────────────────────╮
│ >_ OpenAI Codex │
│
...

AI에게 더 많은 권한을 주고 싶나요?

pwsh ./scripts/gnosis-container.ps1 -Danger -Privileged

› ping google
93% context left · ? for shortcuts
✔ You approved codex to run ping -c 2 google.com this time
...

끝입니다. 이제 컨테이너는 Docker의 --privileged 플래그와 제한 없는 Codex 샌드박스(sandbox)로 실행되므로, AI가 위험한 작업을 수행할 수 있습니다.

세션 목록 보기:
pwsh ./scripts/gnosis-container.ps1 -ListSessions
세션 재개 (Resume a session):
pwsh ./scripts/gnosis-container.ps1 -SessionId <id>

(전체 UUID 또는 마지막 5자리 문자) - 새로운 실행 시 최근 세션이 자동으로 출력되므로, 재개 명령어를 복사하여 붙여넣을 수 있습니다.

pwsh ./scripts/gnosis-container.ps1 -ListSessions
pwsh ./scripts/gnosis-container.ps1 -SessionId b0b57

녹화 (선택 사항):

녹화 (Record):
pwsh ./scripts/gnosis-container.ps1 -Exec "<prompt>" -Record

(-RecordDir <path> 옵션 선택 사항)

녹화 목록 보기 (List recordings):
pwsh ./scripts/gnosis-container.ps1 -ListRecordings
재생 (Play):
pwsh ./scripts/gnosis-container.ps1 -PlayRecording codex-session-YYYYMMDD-HHMMSS.cast

(Codex 이미지를 사용하며, 호스트 의존성이 없습니다) - 업로드 (Upload):
pwsh ./scripts/gnosis-container.ps1 -UploadRecording codex-session-YYYYMMDD-HHMMSS.cast

(검증을 위해 헤더 환경 변수를 정화(sanitizes)합니다) - 파일은 워크스페이스 루트의 .asciinema/ 디렉토리에 저장됩니다 (git-ignored).

녹화는 세션에 종속되지 않습니다. 재개된 세션이든 새로운 실행이든 모든 실행을 녹화할 수 있습니다.
녹화본은 병합할 수 없습니다. 이전 세션을 재개한 후 다시 녹화하여 새로운 구간을 캡처하십시오.

기능 (Capability)	역할 (What it does)
275개 이상의 MCP 도구	웹 크롤링 (Web crawling), 파일 작업 (file ops), 검색, Gmail/Calendar/Drive, Slack, 날씨, 스케줄링 등
자체 스케줄링 (Self-scheduling)	에이전트가 나중에 실행될 트리거를 생성할 수 있음 (매일, 간격, 일회성)
하위 에이전트 (Sub-agents)	`check_with_agent`, `agent_to_agent` — 에이전트가 다른 Claude 인스턴스와 협의함
파일 감시 (File watching)	파일을 넣으면 자동으로 Codex 실행을 트리거함
HTTP 게이트웨이 (HTTP gateway)	`/completion`으로 POST 요청을 보내 AI 응답을 받음 — 무엇이든 통합 가능 (API 문서 참조)
모델 유연성 (Model flexibility)	OpenAI, Anthropic, 또는 Ollama를 통한 로컬 모델

Docker (Desktop 또는 Engine) — docker network create codex-network를 한 번 실행하십시오.

PowerShell — Windows에는 기본적으로 설치되어 있습니다 (이미 Windows PowerShell을 사용 중이라면 pwsh가 필요하지 않음); macOS/Linux는 PowerShell Core (pwsh)를 설치하십시오.

PowerShell 버전 확인:
powershell -Command "$PSVersionTable.PSVersion" (Windows PowerShell) 또는 pwsh -Command "$PSVersionTable.PSVersion"

Ollama/로컬 모델의 경우: 127.0.0.1:11434에서 데몬 (daemon)이 실행 중인 상태를 유지하세요.

OSS_SERVER_URL을 설정하지 않는 한, 헬퍼 (helper)가 이를 컨테이너 (container) 내부로 브릿지 (bridge) 합니다.

GPU 서비스의 경우: NVIDIA + CUDA 드라이버

macOS (Homebrew):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install --cask powershell

Ubuntu/Debian:

sudo apt-get update && \
sudo apt-get install -y wget apt-transport-https software-properties-common && \
wget -q "https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/packages-microsoft-prod.deb" && \
...

PowerShell (pwsh)이 권장되는 엔트리포인트 (entrypoint)입니다. 걱정하지 마세요 — 기존의 Bash 헬퍼 스크립트인 scripts/gnosis-container.sh가 Unix 계열 시스템에서의 편의를 위해 남아 있지만, 최신 기능 반영이 늦어질 수 있습니다. pwsh를 "의존성 (dependency)"으로 추가하는 것이 망설여진다면, Docker 자체가 이미 필수 사항이며, Unix에서 pwsh를 추가하는 것은 더 일관되고 지원되는 워크플로우 (workflow)를 위한 합리적이고 가벼운 절충안이라는 점을 기억하세요.

아래는 이 리포지토리 (repo)의 핵심인 상호 보완적인 스크립트 세트입니다. 기본 스크립트는 컨테이너 내부에서 Codex를 빌드하고 실행하며 (호스트 환경 변수를 전달함), 동일한 컨테이너 내에서 스케줄링된 러너 (runner) 서비스와 함께 작동합니다. 이에 더해, 일반적인 서비스들을 위한 다양한 편의용 Docker 스타터 (starters)를 제공합니다.

# 샌드박스 (Sandboxed) 환경 (안전함)
pwsh ./scripts/gnosis-container.ps1 -Exec "draft release notes"
# 세션을 대화형으로 재개 (세션 ID의 마지막 5자리 사용)
...

플래그 (Flag)	효과 (Effect)
`-Danger`	Codex 승인 프롬프트를 우회하고, 제한 없는 셸 (shell) 실행을 위한 `danger-full-access` 샌드박스 (sandbox)를 활성화합니다. 또한 DNS/네트워크 호환성(특히 Windows)을 위해 `-Privileged`를 자동으로 활성화합니다.
`-Privileged`	Docker를 `--privileged` 모드로 실행합니다 (파일 와처 (file watchers), 장치 액세스 및 Windows DNS 해상도에 필요함).

네트워크 액세스 (Network access): --network codex-network를 통해 기본적으로 사용 가능합니다. -Danger 플래그는 네트워크 액세스가 아닌 Codex의 *내부 샌드박스 (internal sandbox)*를 제어합니다.

환경 변수 (Environment variables): 특정 호스트 환경 변수를 컨테이너 내부로 전달하려면 .codex-container.toml 파일에서 env_imports를 사용하세요. env_imports에 나열되어 있고 호스트에 존재하는 변수만 전달됩니다 (-Danger 플래그 사용 여부와 상관없이 작동합니다).

추가 마운트 (Extra mounts): 컨테이너 내부에 추가적인 호스트 디렉토리를 노출하려면 .codex-container.toml에 하나 이상의 [[mounts]] 항목을 추가하세요 (각 블록은 자체적인 -v 볼륨 (volume)이 됩니다). 워크스페이스 (workspace)는 항상 한 번 마운트됩니다. 레거시 (legacy) 동작은 /workspace입니다 (리포지토리 (repo) 내용이 그곳에 직접 위치함). 워크스페이스를 /workspace/<repo>에 마운트하려면 workspace_mount_mode = "named"를 설정하거나, 명시적으로 재정의하려면 workspace_container = "/custom/path"를 설정하세요.

# 선택적 추가 마운트
# 참고: 세션 (Sessions)은 이미 메인 codex-home 마운트를 통해 접근 가능합니다.
# 재개 (resume)에 필요한 쓰기 작업을 차단하므로 별도의 ro 마운트를 추가하지 마세요.
...

제한 없는 액세스를 원하는 경우 -Danger와 -Privileged를 모두 조합하여 사용하세요. 프롬프트 (prompt)를 완전히 신뢰할 때만 사용해야 합니다.

pwsh ./scripts/gnosis-container.ps1 -Serve -GatewayPort 4000

이제 http://localhost:4000/completion으로 POST 요청을 보내세요:

curl -X POST http://localhost:4000/completion \
-H "Content-Type: application/json" \
-d '{"messages": [{"role": "user", "content": "What time is it?"}]}'

엔드포인트 (Endpoints):

POST /completion — { "prompt": "...", "model": "...", "workspace": "/workspace" }와 함께 프롬프트 실행

GET /sessions — 모든 세션 목록 표시

GET /sessions/:id — 세션 상세 정보

POST /sessions/:id/prompt — 세션 계속하기

POST /sessions/:id/nudge — 새로운 메타데이터 (metadata)로 다시 재생

GET /status — 동시성 (concurrency), 와처 (watcher), 웹훅 (webhook) 정보

GET /health — 라이브니스 프로브 (liveness probe)

환경 변수: CODEX_GATEWAY_DEFAULT_MODEL, CODEX_GATEWAY_TIMEOUT_MS, CODEX_GATEWAY_EXTRA_ARGS

전체 스키마 (schemas), 와처 이벤트 (watcher events), 웹훅 페이로드 (webhook payloads)는 README_API.md를 참조하세요.

$env:CODEX_GATEWAY_WATCH_PATHS = 'temp;inbox'
$env:CODEX_GATEWAY_WATCH_PROMPT_FILE = './MONITOR.md'
$env:CODEX_GATEWAY_WATCH_PATTERN = '**/*.txt'
...

temp/ 디렉토리에 파일을 넣거나

inbox/ 디렉토리에 파일을 넣으면

→ MONITOR.md를 프롬프트 템플릿 (prompt template)으로 사용하는 Codex 실행이 트리거됩니다.

와처 환경 변수 (Watcher env vars):

CODEX_GATEWAY_WATCH_PATHS

— 쉼표(,) 또는 세미콜론(;)으로 구분된 경로 (절대 경로 또는 워크스페이스 상대 경로)

CODEX_GATEWAY_WATCH_PATTERN

— 글로브 패턴 (glob pattern) (기본값 **/*)

CODEX_GATEWAY_WATCH_PROMPT_FILE

— 프롬프트 템플릿 (prompt template) 경로

CODEX_GATEWAY_WATCH_DEBOUNCE_MS

— 디바운스 타이밍 (debounce timing)

CODEX_GATEWAY_WATCH_USE_WATCHDOG

— watchdog 구현체 사용 여부

와처 상태는 / 및 /status를 통해 노출됩니다.

Windows PowerShell에서는 ./temp 대신 temp와 같은 경로를 사용하세요.

에이전트는 monitor-scheduler.* MCP 도구 (create_trigger, toggle_trigger 등)를 사용하여 트리거를 생성할 수 있습니다:

Daily (매일) — 특정 시간에 실행
Interval (간격) — N분마다 실행
Once (일회성) — 미래의 타임스탬프에 실행

트리거는 .codex-monitor-triggers.json에 유지됩니다. 게이트웨이는 모니터/게이트웨이 실행과 동일한 큐 (queue)를 통해 트리거를 디스패치 (dispatch) 합니다.

워크스페이스 루트 (workspace root)에 PROMPT.md를 넣으세요. 모든 실행 시 자동으로 이를 가져옵니다.

workspace/
├── PROMPT.md ← 모든 실행을 위한 시스템 프롬프트 (system prompt)
├── your-files/
...

CODEX_SYSTEM_PROMPT_FILE=/workspace/custom.md로 재정의 가능 (상대 경로는 워크스페이스를 기준으로 해석됨)
CODEX_DISABLE_DEFAULT_PROMPT=1로 비활성화 가능

HTTP 게이트웨이는 동일한 환경 변수/파일을 읽으므로, 와처 이벤트 (watcher events), 스케줄러 트리거 (scheduler triggers), 그리고 API 호출자 (API callers)는 모두 동일한 시스템 프롬프트 (system prompt)를 상속받습니다.

레벨	플래그	AI가 할 수 있는 작업
Sandboxed (기본값)		워크스페이스 (workspace)에 쓰기 가능, `--network codex-network`를 통해 네트워크 사용 가능. Codex는 셸 명령 (shell commands)에 대해 승인을 요구할 수 있음. 자동화에 안전함.
Danger	`-Danger`	Codex 내부에서 제한 없는 셸 (shell) 사용, 승인 프롬프트 없음. 호환성을 위해 `-Privileged`를 자동으로 활성화함.
Privileged	`-Privileged`	Docker `--privileged` 모드 — 호스트 파일/장치 접근 가능, Windows DNS 해상도(resolution)에 필요함.
Full power	`-Danger -Privileged`	모든 권한. 프롬프트를 완전히 신뢰할 때만 사용하십시오.

추가 안전 레버 (safety levers):

도구별 허용/차단 목록 (Allow/deny lists)
크롤링 깊이/크기/시간 제한; 도메인별 제한
속도 및 동시성 제한 (Rate and concurrency limits)
모든 작업은 세션 파일에 기록됨; last_fired로 트리거 파일 확인
gnosis-files-diff를 통한 백업/차이점(diffs) 확인
.codex-mcp.config를 통한 워크스페이스 범위의 도구 설정

(한 줄당 파일명 하나씩 작성). /workspace/.codex-mcp.config에서 워크스페이스별로 재정의 가능

카테고리	예시
Web/Search	`gnosis-crawl.` (마크다운/HTML, JS 선택 사항, 제한/허용 목록), `serpapi-search.` (낮은 수, 필터)
Term Graph	`oracle_walk_hint`, `sample_urls`, `build_term_graph`, `summarize_signals`, `save_page` / `search_saved_pages`
Files	read/write/stat/exists/delete/copy/move/diff/backup/restore/patch/list/find/search/tree/recent
Scheduling	`monitor-scheduler.*` — 트리거 생성/업데이트/토글/삭제/목록; 시계 유틸리티
Orchestration	`agent_to_agent`, `check_with_agent`, `recommend_tool`
Comms	Gmail, Calendar, Drive, Slack, sticky notes, marketbot
Data	open-meteo 날씨, NOAA 해양, 시간
Audio	elevenlabs-tts, speaker-bridge, transcribe-wav, nuts-news

문서 검색 워크플로우 (자연어를 이용한 저장/검색)는 examples/personal_search/DOC_SEARCH.md에 문서화되어 있습니다.

먼저 이 README의 설정을 완료한 다음, 문서 검색 가이드를 따르십시오.

도구의 이름을 명시하지 않고도 사용할 수 있습니다. 그냥 다음과 같이 요청하십시오:

“이 페이지를 저장해줘.”
“amlodipine 복용 시 서맥(bradycardia)에 대해 저장된 내용 검색해줘.”
“PDF QC503F211839v3.pdf의 10~25페이지를 인덱싱(Index)해줘.”
“‘tini’에 대한 세션 검색해줘.” → 재개(resume) 힌트와 함께 일치하는 세션 ID를 반환합니다.
“내 최근 세션 목록을 보여주고 재개 명령어를 알려줘.”

Codex는 적절한 MCP 도구(크롤러(crawler), 검색 인덱스(search index), PDF 도구(PDF tools), 세션 도구(session tools))를 선택하고 결과를 요약하여 사용자에게 다시 전달합니다.

도구 관리:

에이전트에게 다음과 같이 요청하기만 하면 됩니다: “gnosis-crawl 도구를 추가해줘” 또는 “serpapi를 제거해줘.” 그러면 에이전트가 MCP 헬퍼(mcp_add_tool, mcp_remove_tool, mcp_list_installed 등)를 호출하여 사용자를 대신해 설정을 업데이트합니다.

더 구체적으로 지정할 수도 있습니다:

> mcp_add_tool('my-custom-tool.py')
> mcp_remove_tool('serpapi-search.py')
> mcp_list_installed()

또는 설정 파일을 직접 편집할 수 있습니다:

# 한 줄에 하나의 도구 파일 이름 작성
cat /workspace/.codex-mcp.config
gnosis-crawl.py
...

/workspace/.codex-mcp.config 파일이 존재하지 않으면 컨테이너는 이미지 기본값(image defaults)을 사용합니다. 도구를 처음 추가하거나 제거할 때, 해당 기본값을 바탕으로 워크스페이스 설정(workspace config)이 자동으로 생성되므로 파일을 수동으로 만들 필요가 없습니다.

설정을 수정한 후에는 컨테이너를 재시작하거나 -Install을 다시 실행하여 Codex가 MCP 설정을 다시 로드하도록 하십시오.

DeepBlueDynamics/gnosis-container

요약

핵심 포인트

댓글