<div align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="frontend/stravia-webui/static/stravia-logo-reversed.svg">
<source media="(prefers-color-scheme: light)" srcset="frontend/stravia-webui/static/stravia-logo.svg">
<img alt="Stravia" src="https://raw.githubusercontent.com/Stravia-AI/StraviaPlatform/HEAD/frontend/stravia-webui/static/stravia-logo.svg" width="96">
</picture>
<h1>Stravia</h1>
로컬 에이전트 인프라 — 모든 AI 클라이언트를 위한 단일 엔드포인트.<br>
통합 모델 접근성, 사용자를 위해 실행되는 도구들, 공유된 접근 제어,<br>기록 및 사용량 관리 — 데스크톱 앱 또는 단일 바이너리 형태로 제공됩니다.
Release
License: AGPL-3.0-only
CI
Rust
Releases · Changelog · 中文文档
</div>
Request Records — every client request, traced live
상태: Stravia는 1.0 미만 버전이며 활발하게 개발 중입니다. 안정화된 출시 전에 구성 및 데이터베이스 호환성이 변경될 수 있습니다.
Stravia란 무엇인가
Stravia는 AI 코딩 클라이언트를 사용하거나 에이전트 기반 앱을 구축하는 개발자를 위한 로컬이며 자체 호스팅 가능한 에이전트 인프라입니다. 사용자의 클라이언트는 이미 사용하는 프로토콜(OpenAI, Anthropic 또는 Gemini)을 유지하고 단순히 Stravia를 가리키기만 하면 됩니다. Stravia는 어떤 상위 서비스가 응답해야 할지 결정하며 필요할 때 프로토콜 간의 번역을 수행합니다.
모델 접근성 외에도, 이 플랫폼은 자체적으로 도구를 실행합니다: 내장 웹 검색 및 미디어 이해 기능은 Stravia 내부에서 실행되어 결과를 모델에 전달하며 — 일반적인 모델 요청이나 MCP를 통해, 클라이언트 플러그인이 필요하지 않습니다. 접근 제어, 요청 기록, 사용량 및 진단 도구는 모두 한 곳에서 관리됩니다.
Claude Code · Codex CLI · Gemini CLI · OpenCode · SDKs
│
▼
...```
에이전트의 동작은 플랫폼에 의해 정의되고 버전 관리됩니다. Stravia는 사용자가 정의한 에이전트나 시각적 워크플로우 빌더가 아닙니다.
## Stravia를 사용해야 하는 이유
- **AI 코딩 클라이언트를 위한 드롭인 엔드포인트** — Claude Code, Codex CLI, Gemini CLI 또는 OpenCode를 `127.0.0.1:23471`에 연결하고 계속 작업할 수 있습니다. 각 클라이언트가 자체 프로토콜을 유지하며, Stravia가 번역(translation), 라우팅(routing), 장애 조치(failover)를 처리합니다.
- **사용자를 대신하여 실행되는 도구** — 내장 웹 검색(로컬 검색은 설치된 Chrome/Chromium 브라우저를 사용하며, 컨테이너에는 Chromium이 포함됨)과 이미지 이해 기능이 Stravia 내부에서 실행되어 결과를 모델에 다시 전달합니다. 이들을 MCP를 통해 노출하거나 호환 가능한 요청에 자동으로 추가할 수 있습니다.
- **키, 지출 및 요청 기록을 한 곳에서** — 각 앱에 모델 접근 권한과 RPM(분당 요청 수) 제한이 설정된 자체 키를 부여하고, 사용 제공업체가 실제로 보고하는 내용을 확인하며, 모든 요청을 실시간으로 모니터링하고, 문제가 발생했을 때 전체 디버그 번들(debug bundle)을 다운로드할 수 있습니다.
- **로컬 우선(Local-first), 단일 Rust 코어** — 데스크톱 앱 또는 헤드리스 서버 바이너리입니다. 기본값은 SQLite이며, 팀의 경우 PostgreSQL을 사용합니다. 로컬 또는 S3 파일 스토리지를 지원합니다. 클라우드 의존성이 없습니다.
## 빠른 시작하기
**데스크톱** — [GitHub Releases](https://github.com/Stravia-AI/StraviaPlatform/releases)에서 Windows (NSIS), Linux (AppImage), 또는 macOS (DMG, Intel / Apple Silicon) 설치 파일을 다운로드하십시오. 전체 플랫폼은 통합 관리 UI와 함께 로컬에서 실행됩니다. macOS 빌드는 Apple notarization 없이 Ad-hoc signing을 사용하므로 Gatekeeper가 첫 실행을 차단할 수 있습니다. [릴리스 및 서명 세부 정보](docs/releasing.md#macos-构建与独立验证)를 참조하십시오.
시작에 실패하면 데스크톱 앱이 진단 및 복구 옵션을 제공하며, 데이터베이스를 자동으로 초기화하지는 않습니다.
**서버** — 단일 컨테이너:
```bash
docker run --rm \
--publish 127.0.0.1:23471:23471 \
--mount source=stravia-data,target=/data \
...
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
또는 릴리스에서 플랫폼 아카이브를 다운로드하십시오(SHA256SUMS와 비교하여 확인).
Nix / NixOS (Linux 서버 전용): nix build .#stravia-server를 사용하여 이 체크아웃을 빌드하거나, nixosModules.default를 가져와 services.stravia를 활성화하십시오. Nix 배포를 참조하십시오.
기존 인스턴스 업그레이드: 먼저 전체 데이터 디렉터리와 외부 데이터베이스를 중지하고 백업하십시오. Route 출력 목적 마이그레이션(output-purpose migration)은 SQLite와 PostgreSQL 모두에서 개별적으로 재구성하기 전까지 모든 기록된 Route를 비실행 상태로 만듭니다. 업그레이드 및 복구를 참조하십시오. 롤백(rollback)을 하려면 백업을 복원해야 합니다. history-storage 업그레이드는 시작 시 기존 대화 기록과 요청 기록을 다시 작성합니다. 기록이 클수록 시간이 더 오래 걸리고 임시 공간이 더 많이 필요하며, 이전 바이너리는 업그레이드된 데이터베이스를 읽을 수 없습니다.
최초 실행 (둘 다):
- http://127.0.0.1:23471/setup을 열고 콘솔에 출력되는 일회성 설정 토큰(one-time setup token)을 붙여넣으십시오. SQLite 또는 PostgreSQL 중 하나를 선택하고 관리자 계정을 생성하십시오. PostgreSQL은 설정을 시작하기 전에 Redis가 구성되어야 합니다. 캐시 및 서버 구성를 참조하십시오.
- 프로바이더 추가(Add a provider) — API 키 또는 OAuth 채널(Codex, Claude 구독, Grok 디바이스 플로우, Devin)을 추가합니다. Stravia는 사용 가능한 모델 인벤토리(model inventory)를 동기화합니다.
- 모델 추가(Add a model) — 텍스트 또는 이미지 출력을 선택한 다음 일치하는 상위 모델(upstream models)을 선택하십시오. Model ID가 Route 클라이언트가 호출하는 식별자입니다.
- API 키 생성 후, **클라이언트 연결(Connect clients)**을 열십시오. Stravia는 Claude Code, Codex CLI, Gemini CLI 또는 OpenCode용으로 적용 준비가 된 프로바이더 패치(provider patch)를 생성합니다. 데스크톱 앱이 설정을 대신 작성해 줄 수 있습니다.
그런 다음 지원되는 모든 프로토콜을 통해 호출하십시오:
curl http://127.0.0.1:23471/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_PROXY_KEY" \
...
기능 (Features)
통합 모델 접근 (Unified model access)
| 클라이언트 대상 프로토콜 | 엔드포인트 |
|---|
| OpenAI Chat Completions | POST /v1/chat/completions |
| ... | |
| 크로스-프로토콜 도구 호출(tool calls), 추론(reasoning), 사용량 보고는 보존되며, 변경이 필요 없는 요청은 그대로 통과됩니다. | |
제공업체 및 모델 라우팅 (Providers and model routing)
OpenAI (incl. Codex OAuth) · Anthropic (API key; Claude Pro/Max subscription OAuth via the Claude Code plugin — Claude Code 외부에서 구독을 사용하는 것은 Anthropic의 약관을 위반할 수 있음) · Google Gemini + Vertex AI · Devin (OAuth) · DeepSeek · Moonshot AI · Zhipu AI · Z.AI · MiniMax · xAI (API key 및 Grok OAuth) · NVIDIA · OpenRouter · Ollama · 사용자 정의 OpenAI 호환 엔드포인트.
클라이언트는 사용자가 정의한 **모델 ID(Model ID)**를 호출합니다. 이 모델 ID는 우선순위 레이어에 있는 하나 이상의 업스트림(upstreams)에 매핑됩니다: 요청은 가장 상위 레이어로 먼저 전송되며, 트래픽 균형을 맞추거나 가장 빠른 대상을 선호하며, 대화 내용은 이전 작동 방식에 고정됩니다. 내장 카탈로그가 제공업체의 모델 목록을 최신 상태로 유지합니다.
업스트림 서비스가 일시적으로 사용 불가능할 경우, Stravia는 라우트 구성에 따라 재시도하거나 서비스를 전환합니다. 관리 UI에서는 각 대상의 가용성을 보여줍니다.
Editing a model — upstream targets in priority layers
StraviaRead — 하나의 도구, 하나의 경로(path): 파일, 웹페이지, search:// 질문 및 이미지 읽기; 오피스 문서(DOCX/XLSX/PPTX/DOC/XLS/PPT)는 추출된 마크다운(Markdown)으로 읽기; 긴 결과 페이지를 자동으로 탐색.- 웹 검색 (Web Search) — 브라우저 기반의 로컬 소스(Local source), Exa 또는 Zhipu와 함께 로컬 에이전트 루프(Local agent loop)를 사용하거나, 완전하게 인용된 보고서를 반환하는 외부 경로(External Route)의 벤더 플러그인(Vendor plugin)을 연결합니다.
- 미디어 이해 (Media Understanding) — 이미지 설명 및 텍스트 추출(JPEG/PNG/WebP) 또는 선택한 비전 모델(vision model)로 오피스 문서에 대한 질문 답변이 가능합니다.
- 미디어 생성 (Media Generation) — 적격 이미지 생성 대상과 연결된 저장된 경로를 통해 이미지를 생성하거나 편집하고, 이후 도구에서 아티팩트 참조(Artifact Reference)를 재사용할 수 있습니다.
- 모든 것을
POST /mcp를 통해 노출하거나 호환되는 요청에 자동으로 추가합니다. 루프는 하드 타임(time), 턴(turn), 토큰(token), 도구(tool) 예산 내에서 실행됩니다.
이미지 생성 (Image generation)
**고급 기능(Advanced Features) → 미디어 생성(Media Generation)**에서 적격 이미지 생성 대상과 연결된 저장된 경로를 연결한 다음, 해당 기능을 활성화합니다. 번들로 제공되는 Codex OAuth 및 이미지 전용 플러그인은 동일한 경로 메커니즘을 사용하며, 실제 가용성은 상위 계정 및 모델 지원에 따라 달라집니다.
가용성은 상위 계정 및 모델 지원에 달려 있습니다. 크기 선호도가 정확한 치수를 보장하지 않으며, 재시도는 추가 할당량을 소모할 수 있습니다. 구성, 예제 및 제한 사항은 미디어 생성 문서(Media Generation documentation)를 참조하십시오.
벤더 플러그인 (Vendor plugins)
모든 모델 벤더(Vendors)는 자체 포함형 Wasm 컴포넌트(Wasm Components)로 실행됩니다. Stravia가 기본 벤더(base Vendor)를 내장하고 있으며, Codex, Claude Code, Grok, Command Code, Devin은 별도의 릴리스 첨부 파일로 배포되는 전용 플러그인입니다. 연결을 추가하기 전에 **벤더 플러그인(Vendor Plugins)**에서 해당 로컬 .wasm 파일을 가져오십시오. 전용 플러그인은 자체 전체 공급업체 식별자(supplier identity)를 소유하며 기본 패키지로 되돌아가지 않습니다.
**벤더 플러그인(Vendor Plugins)**은 마켓플레이스 없이도 로컬 플러그인 업데이트를 지원합니다. 플러그인은 선택된 연결의 상위(upstream) 자격 증명 및 승인된 네트워크 목적지에 대한 신뢰를 받으므로, 사용 전에 소스 및 요청된 출처를 검토해야 합니다. 설정, 지원되는 기능, 격리(isolation), 업데이트 및 라이프사이클 세부 정보는 플러그인 디자인을 참조하십시오.
키, 사용량 및 요청 기록
- 내장 콘솔 채팅(Built-in console chat): 관리 UI에서 API 키와 모델을 선택하고, 다중 턴 응답을 스트리밍하며, 로컬 대화 기록을 다시 확인할 수 있습니다. 저장 공간 및 도구 주입 제한은 콘솔 채팅을 참조하십시오.
- 사용자 지정 비밀(custom secrets), 모델 바인딩, 만료일 및 동시성, MCP 접근, 자동 도구 주입을 위한 키별 제한이 있는 API 키.
- 요청 기록(Request Records): 확대 가능한 캔버스에서 모든 상호 작용(모델 호출, 재시도, 도구 호출)을 실시간으로 확인하며, 별도의 실패한 요청 목록과 대화별 보기 기능을 제공합니다.
- 서비스가 실제로 보고하는 토큰 사용량 및 공급자 할당량(provider quotas)을 확인할 수 있습니다.
- 디버그(Debug)를 켜서 HTTP/SSE/WebSocket 트래픽을 캡처하고 디버그 번들로 다운로드할 수 있습니다. 이 경우 HTTP
Authorization 값만 마스킹되며, 다른 자격 증명, 콘텐츠 및 미디어는 유지될 수 있습니다. 해당 번들은 민감하게 취급해야 하며, 요청 기록 디자인을 참조하십시오.
- 일반 요청 관찰(Ordinary request observations)은 디버그가 꺼져 있어도 동일한 필터링을 사용합니다: 실제 HTTP
Authorization 헤더 값만 마스킹되며 (대소문자 구분 없는 헤더 이름), 유사하게 이름 붙여진 본문 또는 도구 필드는 마스킹되지 않습니다. 실시간 보기, 저장된 기록 및 내보낸 이벤트는 다운로드 권한(download grants) 및 기타 원시 자격 증명을 유지할 수 있습니다. 이는 일반적인 캡처를 전체 와이어 레코딩으로 확장하거나, 오래된 기록을 다시 작성하거나, 보존 기간, 권한, 프로세스 로그/클라이언트 오류 필터링 또는 모델 측 자격 증명 보호 기능을 변경하지 않습니다. 다운로드 권한은 자동으로 새로 고침되거나 갱신되지 않습니다.
자격 증명 보호
기본적으로 비활성화되어 있습니다. 한 번 켜면 클라이언트에서 변경할 필요 없이 모든 Stravia API 키를 처리합니다.
- 비밀 정보는 장치에 유지됩니다 — Stravia는 모델로 전송되는 메시지, 기록(history), 도구 입력 및 출력에서 API 키, 토큰 및 기타 자격 증명(credentials)을 인식하고, 요청이 나가기 전에 이를 플레이스홀더(placeholders)로 교체합니다. 461개의 모든 탐지 규칙(detection rules)은 번들링되어 로컬에서 실행되며, 확인을 위해 어딘가로 전송되는 것은 없습니다.
- 답변은 여전히 종단 간(end to end)으로 작동합니다 — 제공업체(provider)가 플레이스홀더를 반사할 때, Stravia는 답변과 도구 호출에서 실제 값을 복원하여 도구가 자격 증명을 계속 사용할 수 있도록 합니다. 동일한 비밀 정보는 대화와 재시작 전반에 걸쳐 동일한 플레이스홀더를 유지합니다.
- 안전하게 실패하며, 절대 조용하지 않습니다 — 탐지 또는 저장 기능이 작동하지 않으면, 평문(plaintext)을 전송하는 대신 요청 자체가 실패합니다. 이를 끄면 새로운 교체가 중단되지만, 이미 발급된 플레이스홀더는 만료될 때까지 계속 복원됩니다.
- 가시적이며 테스트 가능합니다 — 전체 규칙 목록을 탐색하고, 각 요청이 어떤 자격 증명을 포착했는지 확인하며, 자신의 텍스트를 디텍터(detector)에 대입하여 테스트할 수 있습니다. 테스트 입력은 이 인스턴스에 남아 저장되지 않습니다.
