Gray: 최소한의, 항상 작동하는 AI 에이전트 하네스

<div align="center"> <img alt="Gray" src="assets/logo-dark.svg" width="160" height="160" /> <h1>gray</h1> <p><strong>최소한의, 항상 작동하는 AI 에이전트 하네스입니다.</strong><br/>단일 바이너리로 어떤 모델이든 구동 가능하며, 사용자가 잠자는 동안에도 작동합니다.</p> <p> <a href="https://gray.alignment.id">웹사이트</a> · <a href="CHANGELOG.md">변경 기록</a> · <a href="https://github.com/vstaln/gray/releases">릴리스</a> </p> <p> <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-1c1c20?style=flat-square&labelColor=0a0a0b" /></a> <a href="https://www.rust-lang.org"><img alt="Built with Rust" src="https://img.shields.io/badge/built%20with-rust-1c1c20?style=flat-square&labelColor=0a0a0b&logo=rust&logoColor=d4a373" /></a> <a href="#platform-support"><img alt="Platform: linux, macOS, windows" src="https://img.shields.io/badge/platform-linux%20%C2%B7%20macos%20%C2%B7%20windows-1c1c20?style=flat-square&labelColor=0a0a0b" /></a> <a href="https://github.com/vstaln/gray/releases"><img alt="Latest release" src="https://img.shields.io/github/v/release/vstaln/gray?style=flat-square&labelColor=0a0a0b&color=131316" /></a> </p> </div> <br/>

Gray는 단일 Rust 바이너리 형태의 코딩 및 자동화 에이전트입니다. Claude, GPT, Gemini와 같은 어떤 모델이든 (오픈 모델 또는 로컬 모델 포함) 가져와 쉘을 제공하고 작동시킬 수 있습니다. cron으로 스케줄링하면 게이트웨이 데몬(gateway daemon)이 터미널 창을 열지 않고도 계속 실행 상태를 유지합니다.

curl -fsSL https://gray.alignment.id/install.sh | sh && gray

왜 gray를 사용해야 하는가


어떤 모델이든, 당신의 열쇠	Claude를 위한 네이티브 Anthropic Messages API (프롬프트 캐싱, 확장된 사고). OpenAI와 호환되는 모든 제공업체 — OpenAI, Google, OpenRouter, DeepSeek, Groq, Mistral, xAI, Fireworks, Together 및 번들된 models.dev 카탈로그의 나머지 172개 모델 — 그리고 Ollama를 통한 로컬 모델까지 지원합니다.
...

설치

curl -fsSL https://gray.alignment.id/install.sh | sh              # stable
curl -fsSL https://gray.alignment.id/install.sh | sh -s -- beta   # rebuilt on every main push
cargo build --release -p gray                                     # from source

네이티브 Windows 11 x64 (WSL 미사용; Git for Windows가 셸 제공). PowerShell에서는:

irm https://gray.alignment.id/install.ps1 | iex

설치 프로그램은 릴리스 SHA256SUMS를 확인합니다. 오프라인 설치를 하려면 dist/install.ps1과 zip 파일을 함께 보관하고 .\dist\install.ps1 -ArchivePath .\gray-stable-x86_64-windows.zip -Sha256 <digest>를 실행하세요. 현재 네이티브 Windows에서는 게이트웨이(Gateway)/cron 실행 및 셀프 업데이트가 지원되지 않습니다 — 베타, 오프라인 및 WSL 설치에 대한 내용은 Windows 가이드를 참조하세요.

빠른 시작

gray                 # 프롬프트로 이동합니다


`/connect`	제공업체를 선택하고 키를 붙여넣으세요 — 환경에 이미 있는 키는 감지됩니다
...
gray.alignment.id의 계정은 필수가 아닙니다 — 이는 gray-account 플러그인(`gray account login` / `whoami` / `logout`)에 존재하며, gray에서 이 계정에 의존하는 기능은 없습니다.

항상 켜기: cron + gateway

gray cron add

모델은 스스로 `gray cron add`를 실행할 수 있으므로, “매일 아침 확인”과 같은 작업이 그냥 작동합니다. 작업은 스토어에 틱(tick)을 주는 모든 것에서 발생합니다: 게이트웨이 데몬, `gray cron serve`, `gray cron tick` 호스트 (systemd 타이머 / crontab), 또는 열린 REPL입니다. 게이트웨이는 `$GRAY_HOME/gateway.sock`에 있는 60초 간격의 티커와 제어 소켓을 가지고 있으며, 종료 시 진행 중인 작업을 비웁니다.

## 명령어 (Commands)

슬래시 명령어는 자동 완성됩니다 — Enter를 누르면 완료되고 실행되며, Tab을 누르면 삽입됩니다.

| | |
|---|---|
| `/new` · `/sessions [id|--last|--all]` | 새로운 대화 시작 또는 기존 대화 재개 |
| ... | 
CLI: `gray resume`, `gray cron`, `gray gateway`, `gray plugin`, `gray memory`, `gray sessions prune`, `gray update`. 플래그: `-p`, `-c`, `--session <ID>`, `--context-window`, `--json`, `--bare`. `--json`은 성공 시 `0`, 턴 실패 시 `1`, 프로바이더/네트워크 실패 시 `3` (재시도 가능)을 반환합니다. 오류 기록에는 `code`와 `hint`가 포함됩니다.

## 확장 (Extend)

**스킬 (Skills)** — `~/.gray/skills` 및 `.gray/skills`, 그리고 Claude Code / opencode / agents / pi 위치의 `SKILL.md` 파일은 전역적 및 프로젝트별로 사용 가능합니다. 모델은 매 턴마다 이 목록을 보고 필요한 것을 읽습니다.

**플러그인 (Plugins)** — stdio를 통해 NDJSON으로 통신하는 사이드카 프로세스(wire v1, frozen)이며, 타임아웃과 충돌 격리 기능을 제공합니다. `gray.yml` 프로파일이 순서를 지정하며, [`crates/gray-plugin/testdata/echo.sh`](crates/gray-plugin/testdata/echo.sh)는 복사하여 붙여넣을 수 있는 시작점입니다. 더 자세한 내용은 [docs/plugins.md](docs/plugins.md)를 참조하세요.

**다른 곳에서 실행할 명령어 (Run commands elsewhere)** — 이 설정 하나로 모든 셸 명령어를 사용자의 컴퓨터 외부로 이동시킬 수 있습니다:

```json
// ~/.gray/config.json
{ "exec_prefix": "docker exec -i dev sh -s" }    // 또는 "ssh box sh -s"

명령어는 텍스트 형태로 전달되므로, 따옴표(quoting), 글로브(globs), 히어독(heredocs)이 원본 그대로 먼 쪽 셸에 도달합니다. 경로는 넘어가지 않습니다: 원격 명령어는 해당 계정의 홈 디렉터리에서 시작됩니다.

백그라운드 작업 (Background jobs) — bash는 command와 timeout만 받습니다 (기본값 120초, 최대 3600초). 타임아웃 시점까지 실행 중인 명령어는 종료되지 않습니다. 계속 백그라운드 작업으로 실행되며, 호출은 로그, pgid(프로세스 그룹 ID), 현재 출력 내용 및 중지 명령(kill -- -<pgid>)을 반환합니다. 모델은 턴을 끝내면서 기다립니다: 완료된 작업이 종료 상태와 로그 경로로 세션을 깨웁니다. /jobs는 작업을 나열하고 중지시킵니다. 베어 모드 (GRAY_NO_JOBS)는 일반적인 mini-swe-agent입니다: 타임아웃 시킬 경우 종료됩니다.

안전성 (Safety)

Gray는 모델의 셸 명령을 사용자의 권한으로, 승인 프롬프트 없이, 샌드박스 없이 실행합니다. 신뢰할 수 없는 작업의 경우 컨테이너/VM에서 실행하거나 exec_prefix를 격리된 박스로 설정하십시오. ~/.gray/sessions에 있는 세션 기록은 도구 호출을 통해 교환된 모든 것(비밀 정보 포함)을 보관하며, -p 모드는 이를 삭제합니다. 보고서: SECURITY.md.

참고 자료 (Reference)

컨텍스트 창 (Context window) — --context-window / GRAY_CONTEXT_WINDOW → 제공업체 값 → LiteLLM 테이블 → 폴백(fallback). window − 16k에서 자동 압축되며, 오버플로우 발생 시 한 번 압축하고 재시도합니다.

환경 (Environment)

var	의미
`GRAY_HOME`	설정 루트 (기본값 `~/.gray`)
...

플랫폼 지원 (Platform support)

OS / arch	바이너리	참고 사항
Linux x86_64 / aarch64	musl-static	전체 지원, 사용자 서비스 게이트웨이로 사용
...
레이아웃 (Layout) — `gray` (CLI, TUI, 세션, cron, gateway) · `gray-core` (에이전트 루프) · `gray-provider` (OpenAI 호환 + 네이티브 Anthropic 스트리밍) · `gray-tools` · `gray-plugin` · `gray-pkg` · `gray-markdown`.

안정성 (Stability) — CLI 플래그, 세션 JSONL, 플러그인 와이어 v1 및 ~/.gray 레이아웃은 1.0 버전에서 계약(contract)이 되며, 0.x 버전에서는 최선의 노력(best-effort)입니다. 변경 사항: CHANGELOG.md.

THIRD_PARTY_NOTICES.md의 프로젝트들로부터 정보를 얻었습니다 — 그들에게 감사합니다. cargo install gray는 다른 크레이트입니다. 설치 프로그램을 사용하거나 소스에서 빌드하십시오.

Gray: 최소한의, 항상 작동하는 AI 에이전트 하네스

요약

핵심 포인트