> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# shell 실행 및 구성

Tauri 개발 shell을 실행해 Web 앱에 연결합니다.

## 초보자 연습

전제 조건: 아래 두 개의 초보자 가이드를 읽고 Rust 및 운영 체제 전제 조건을 포함한 데스크톱 로컬 설정을 완료하세요. 코드 블록은 모노레포에서 웹앱과 Tauri를 모두 시작합니다. 데스크톱 전용 결제에서는 별도로 연결할 수 있는 웹 백엔드를 시작한 후에만 필터링된 명령을 사용하세요. Tauri는 해당 백엔드를 로드합니다.

빠른 용어: 작업 영역은 한 팀의 별도 사용자, 데이터 및 설정입니다. 서버는 신뢰할 수 있는 백엔드입니다. 제공업체 키를 브라우저 및 전화 코드에 보관하세요. 마이그레이션은 테이블을 생성하거나 업데이트하는 버전이 지정된 데이터베이스 변경입니다. AI 모델은 응답하는 엔진입니다. 모델 카탈로그는 서버의 사용 가능한 모델 ID 및 가격 목록입니다. 공급자는 AI, 이메일, 청구 서비스와 같은 외부 서비스입니다. 자격은 작업 영역에서 기능을 사용할 수 있도록 하는 부여입니다. 웹훅은 한 서비스가 다른 서비스의 URL에 보내는 메시지입니다.

1. `apps/desktop/src-tauri/src/lib.rs`를 엽니다. 에이전트에게 명명된 창/트레이/단축키 동작만 변경하고 웹 앱의 제품 UI를 유지하도록 요청하세요.

2. 셸을 실행하고 트레이 가까이에서 Quit 및 `CmdOrCtrl+Shift+Space`를 테스트합니다. `supastack:///settings/appearance?preview=1#main`를 테스트하세요.

3. 기존 창에 초점을 맞추고 경로/쿼리/조각을 보존해야 합니다. 잘못된 페이지가 열리면 구성된 출발지와 정확한 경로를 비교하세요.

사용자 정의 코드의 경우 제공된 `prompts/README.md`로 시작하고 가장 가까운 프롬프트(앱 화면의 경우 `prompts/new-app-screen.md`, 공개 페이지의 경우 `prompts/new-landing-page.md`)를 복사합니다. 서버, 데이터베이스 또는 공급자 작업의 경우 코딩 에이전트에게 이 가이드의 작업을 제공하고 `AGENTS.md`, `.ai/PROJECT_CONTEXT.md` 및 일치하는 `.ai/` 미러를 읽도록 요청하세요. 여기에 이름이 지정된 정확한 소스 파일을 검사하십시오. 편집하기 전에 파일을 나열하고 확인합니다. 작업 공간 소유권과 서버 전용 비밀을 보존합니다. 차이점을 보여주세요. 원하는 동작, 입력 및 출력 필드, 허용된 역할, 예상되는 성공 및 오류, 테스트 계정, 공급자 또는 장치를 알려주십시오. 샘플 값을 사용하십시오. 절대 진짜 비밀을 붙여넣지 마세요.

[시작하기 전에](https://supastack.dev/ko/docs/web/before-you-start.md)

[단말기 기본사항](https://supastack.dev/ko/docs/web/terminal-basics.md)

[데스크탑 로컬 설정](https://supastack.dev/ko/docs/desktop/ship-in-5-minutes.md)

[에이전트 프롬프트 및 프로젝트 메모리](https://supastack.dev/ko/docs/web/agents.md)

```
# Monorepo: start the web app and desktop shell together
corepack pnpm dev:desktop

# Desktop-only checkout: start Tauri after a web backend is already reachable
corepack pnpm --filter @supastack/desktop dev
```


## Rust에서 쉘 동작 유지

`src-tauri/src/lib.rs`는 기본 1200×800 웹뷰 창을 생성합니다. 닫으면 트레이에 숨겨집니다. 종료를 종료합니다. 기본 메뉴는 홈/뒤로/앞으로/새로 고침, 확대/축소/전체 화면 및 창 작업을 제공합니다. 창 상태 복원은 크기/위치를 유지합니다.


## 링크 처리 및 소환

셸은 `supastack://` 경로를 수락하고 정확하게 구성된 HTTP(S) 앱 원본에 대해 이를 확인합니다. 예를 들어, `supastack:///settings/appearance?preview=1#main`는 `/workspace/settings?tab=billing#plans`가 됩니다. `supastack:///auth/callback?code=...`는 `/auth/callback?code=...`에 매핑됩니다. 쿼리 문자열과 조각은 보존됩니다.

시작 링크는 첫 번째 창이 표시되기 전에 적용됩니다. macOS 런타임 링크는 Tauri의 `on_open_url`를 사용합니다. Windows 및 Linux 두 번째 인스턴스 인수는 `deep-link` 기능이 활성화된 단일 인스턴스 콜백을 사용합니다. 유효한 링크는 기존 창에 초점을 맞추고 탐색합니다.

정확하게 구성된 체계, 호스트 및 유효 포트가 있는 자격 증명이 없는 HTTP(S) 링크만 셸에 유지됩니다. 자격 증명이 필요 없는 HTTP(S), `mailto:` 및 `tel:` 링크는 외부에서 열릴 수 있습니다. 잘못된 링크, 자격 증명, 지원되지 않는 구성표, 사용자 정의 링크의 포트 및 순회 시도가 거부됩니다. 구성된 백엔드 URL는 자격 증명을 거부하고 다음 유효한/기본 원본으로 대체합니다.

```
SUPASTACK_APP_URL=https://your-app.example
SUPASTACK_DESKTOP_HOTKEY=CmdOrCtrl+Shift+Space

supastack:///settings/appearance?preview=1#main
# Opens https://your-app.example/workspace/settings?tab=billing#plans
```


## 플랫폼별 동작 확인

삽입된 오프라인 오버레이는 재시도를 제공하고 온라인에서 숨기고 웹 앱을 다시 로드합니다. 모든 대상 OS에서 포커스, 바로 가기, 메뉴 확대/축소, 트레이 및 딥 링크 호출을 테스트합니다. 유닛 URL 검사만으로는 이러한 기본 상호 작용을 증명할 수 없습니다.

[데스크톱 수용](https://supastack.dev/ko/docs/desktop/release.md)


## 설치 및 설정

작업 공간 종속성과 Rust 도구 체인 및 Tauri의 OS별 필수 구성 요소를 설치합니다(WebView2는 Windows와 함께 제공되며 macOS 및 Linux에는 문서화된 패키지가 필요함). corepack pnpm --filter @supastack/desktop dev는 tauri dev를 실행합니다. 이는 Rust 코어를 빌드하고 자리 표시자 UI를 표시하며 확인된 앱 URL를 로드합니다.

런타임 SUPASTACK_APP_URL을 먼저 사용하고 빌드 시 값을 다음으로 사용합니다. 자격 증명 없는 HTTP(S)만 허용하며 잘못된 값이면 다음 후보를 확인합니다. SUPASTACK_DESKTOP_HOTKEY는 기본 CmdOrCtrl+Shift+Space를 대체하며 잘못된 값은 기본값으로 돌아가 시작을 막지 않습니다.

```
corepack pnpm --filter @supastack/desktop dev
corepack pnpm --filter @supastack/desktop typecheck

SUPASTACK_APP_URL=https://app.example.com \
SUPASTACK_DESKTOP_HOTKEY=CmdOrCtrl+Shift+Space \
corepack pnpm --filter @supastack/desktop dev
```


## 구현 워크플로

주 창은 scheme과 port까지 포함한 정확한 설정 origin 안에서만 이동합니다. 자격 증명 없는 HTTP(S), mailto, tel은 시스템 브라우저에서 열 수 있고 다른 scheme은 취소됩니다.

등록된 supastack:// 링크는 path, query, fragment를 설정된 앱 origin으로 매핑합니다. 시작 시, 플랫폼 open-url 이벤트, second-instance callback이 같은 검증을 거쳐 다른 host로의 이동을 막습니다.

tray와 전역 단축키는 단일 주 창을 표시하고 포커스합니다. 단축키가 등록되지 않으면 다른 앱이 사용 중일 수 있으니 SUPASTACK_DESKTOP_HOTKEY를 바꾸세요.


## 검증 및 문제 해결

src-tauri를 수정한 뒤 package script로 cargo check와 cargo test를 실행하세요. 정확한 origin 탐색, 허용된 외부 URL, 설정 origin에 남는 supastack:// 경로, tray와 단축키, 재시작 후 로그인 유지도 확인합니다.


설정을 계속하려면 [데스크톱 릴리스 계정 만들기](https://supastack.dev/ko/docs/desktop/external-accounts.md) 가이드를 읽어보세요.


## 다음

[데스크톱 릴리스 계정 만들기](https://supastack.dev/ko/docs/desktop/external-accounts.md)