Installation, onboarding, and authentication

Installation, onboarding, and authentication (설치, 온보딩, 인증)

이 가이드는 CoCo Desktop 인터페이스를 안내하고, Snowflake 계정에 어떻게 연결하는지 보여줘요. 그래서 평범한 영어로 질문하고, 데이터를 탐색하고, 워크플로를 만들 수 있게 돼요.

출처: Installation, onboarding, and authentication

본문

CoCo Desktop 받기

최신 버전을 다운로드해요. macOS와 Windows에서 사용할 수 있어요.

Windows 설치 프로그램 선택: 다운로드 페이지는 두 가지 Windows 설치 프로그램 유형을 제공해요.

User installer(권장): 현재 사용자에게만 CoCo Desktop을 설치해요. 관리자 권한이 필요 없고, 높은 권한 없이도 자동 업데이트를 지원해요.
System installer: 시스템의 모든 사용자에게 설치해요. 관리자 권한이 필요하며, IT 관리 배포로 관리 워크스테이션에 설치하거나 머신 전체 설치를 원할 때 적합해요.

로그인하기 전에 내 Snowflake 역할에 필요한 데이터베이스 역할이 있는지 확인해요.

접근 요구사항

CoCo Desktop을 사용하려면 내 Snowflake 역할에 SNOWFLAKE.CORTEX_USER 또는 SNOWFLAKE.CORTEX_AGENT_USER가 있어야 해요. 기본적으로 SNOWFLAKE.CORTEX_USER는 PUBLIC 역할을 통해 모든 사용자에게 제공돼요. 관리자는 이 역할을 PUBLIC에서 회수하거나 사용자별 일일 크레딧 한도를 설정해 접근을 제한할 수 있어요. Access control requirements와 CoCo의 Daily credit usage limits를 참고해요.

온보딩과 로그인

처음 실행하면 CoCo Desktop이 네 단계 설정 흐름을 안내해요: 환영 → 연결 → 모드 → 테마. 창 위쪽의 진행 표시기가 현재 단계를 보여주고, Back으로 이전 단계로 돌아갈 수 있어요. 이미 ~/.snowflake/connections.toml 파일이 있다면(예: CoCo CLI에서) 기존 연결이 자동으로 감지돼요.

단계별 진행

Welcome. CoCo Desktop을 실행해요. Welcome 화면이 CoCo를 소개해요. Next를 클릭해 설정을 시작해요.
Connect to Snowflake. 기존 연결이 감지되면(connections.toml에서) 상태 점과 함께 목록에 나타나요. 하나를 선택하고, 편집(연필) 아이콘으로 수정하거나, chevron을 클릭해 연결 세부 정보를 펼쳐요. Add connection을 클릭해 새 연결을 만들고, Next로 계속하거나 Skip으로 나중에 설정할 수 있어요. 연결을 추가할 때 양식을 채워요. 패널에는 Snowsight(app.snowflake.com → 내 아바타 → Connect a tool to Snowflake)에서 계정 식별자와 로그인 이름을 찾는 인라인 지침이 있어요.
- Account identifier(계정 식별자): 예: myorg-myaccount([계정 식별자 찾기](https://docs.snowflake.com/en/user-guide/admin-account-identifier 참고)).
- Connection name(연결 이름): 계정 식별자에서 자동 생성된 친숙한 라벨.
- Username(사용자 이름): 내 Snowflake 로그인 이름.
- Authentication method(인증 방법): Local OAuth(권장), External browser(SSO), 또는 Password. Sign in을 클릭해 연결을 저장하고 인증해요. OAuth나 SSO는 브라우저에서 안내가 뜨면 로그인을 완료해요.
Choose a view. CoCo가 어떻게 시작할지 골라요.
- Agent: 여러 워크스페이스에서 병렬 에이전트 세션에 최적화.
- Editor: 에이전트 세션을 옆에 두고 파일 작업에 최적화. Agent view와 Editor view는 언제든 전환할 수 있어요. Next를 클릭해요.
Choose your theme. Light 또는 Dark를 선택해요(나중에 Settings에서 바꿀 수 있어요). 그다음 Get Started를 클릭해 메인 앱을 실행해요.

팁

OAuth/SSO에서 브라우저가 자동으로 열리지 않으면, 앱의 "Browser didn't open?" 링크를 사용해 로그인 URL을 복사하고 직접 열어요.

계정 식별자 찾기

app.snowflake.com에 로그인해요.
왼쪽 아래 모서리의 내 아바타를 클릭하고 Connect a tool to Snowflake를 선택해요.
계정 식별자(orgname-accountname)와 로그인 이름을 복사해요. URL에서도 계정 식별자를 읽을 수 있어요: https://app.snowflake.com/orgname/accountname/.

설정 후 연결 관리

앱 안에서 언제든 연결을 추가, 편집, 전환할 수 있어요.

연결 메뉴 열기: 상단 내비게이션 바의 연결 이름을 클릭하면 연결 관리 옵션이 있는 드롭다운이 나타나요.

Manage Snowflake Connections: 연결 관리자 대화상자를 열어 연결 전환, 새 연결 추가, 기존 연결 편집·삭제를 할 수 있어요.
View Snowflake Connections: 참고용으로 connections.toml 파일을 보여줘요.
Refresh Snowflake Connections: 디스크에서 연결을 다시 로드해요(구성 파일을 수동 편집한 뒤 유용해요).
Change Role: 연결을 끊지 않고 활성 Snowflake 역할을 전환해요.
Default Warehouse: 새 세션이 사용할 웨어하우스를 선택해요. CoCo는 이 선택을 ALTER USER SET DEFAULT_WAREHOUSE로 내 Snowflake 사용자에게 저장하고, 로컬의 connections.toml도 갱신해서 이후 연결은 매 세션 설정하지 않아도 선택한 웨어하우스를 사용해요.
Private Mode: 민감한 작업을 위해 비공개 모드를 켜요.

Manage Connections 대화상자: Manage Snowflake Connections를 선택하면 이 대화상자가 열려요. 라디오 버튼으로 연결을 전환하고, 편집(연필) 아이콘으로 수정하거나 휴지통 아이콘으로 삭제해요. Add Connection을 클릭해 새 연결을 만들 수 있어요.

연결 편집·추가: 편집 아이콘이나 Add Connection을 클릭하면 Edit Connection 대화상자가 열려요. 이 양식은 온보딩 양식과 동일하게 동작해요. Account Identifier, Connection Name, Username, Authentication Method를 채우고 Save를 클릭해요.

팁

채팅 입력에 /connections를 입력해 연결 관리자를 빠르게 열 수도 있고, 활성 연결이 없으면 "Sign in to Snowflake" 시작 카드를 사용할 수 있어요.

기본 웨어하우스

CoCo Desktop은 활성 연결의 기본 웨어하우스를 언제든 설정할 수 있게 해줘요. 웨어하우스는 Snowflake 계정에 서버 측으로 저장되므로 모든 세션과 디바이스에 적용돼요.

기본 웨어하우스 설정·변경

상단 내비게이션 바의 연결 이름을 클릭해 연결 드롭다운을 열어요.
Set Default Warehouse를 선택해요.
목록에서 웨어하우스를 선택하고 확인해요.

선택한 웨어하우스는 즉시 활성화되고, 이후 이 세션과 미래 세션의 모든 쿼리에 사용돼요.

참고

여기서 설정한 기본 웨어하우스는 Snowflake 계정에 서버 측으로 저장돼요.

UI 둘러보기

CoCo Desktop 인터페이스에는 네 영역이 핵심이에요.

Top Navigation Bar: 활성 Snowflake 연결, 전역 Search, 오른쪽의 Agent/Editor 뷰 토글(어시스턴트 동작 방식을 전환)을 표시해요.
Left Sidebar: New Session을 만들고, Automations를 열고, 내 Projects를 탐색해요. 각 프로젝트는 컴퓨터의 작업 디렉터리에 해당해요.
Main Chat Area: 어시스턴트와의 대화가 일어나는 중앙 영역이에요. 메시지, 도구 실행, 코드, SQL 결과, 차트, 파일 diff가 모두 여기 나타나요. 입력 바는 아래쪽에 있어요. 메시지를 입력하고, /로 스킬을 호출하고 @로 맥락을 더하고, 모드(Agent 또는 Editor), 모델, 승인 선호를 고를 수 있어요. 새 세션에서는 시작 프롬프트 칩도 표시돼요.
Right Toolbar: 앱 내 브라우저, SQL, Snowflake 객체, 파일 탐색기, 소스 제어 등을 위한 세로 빠른 접근 아이콘 띠예요.

업데이트

CoCo Desktop은 자동으로 최신 상태를 유지해요.

앱은 백그라운드에서 새 버전을 확인하고, 다운로드한 뒤 설치를 안내해요. 설치하면 업데이트가 적용되고 앱이 다시 시작돼요.
크게 오래된 설치본은 계속하기 전에 업데이트가 필요하므로, 항상 최신 수정이 포함된 지원 버전을 유지하게 돼요.

업데이트는 앱 자체가 관리해요. 일상적인 버전 상승에는 새 설치 프로그램을 다운로드할 필요가 없어요. 최신 상태 유지의 보안 근거는 Auto-update를 참고해요.

인증 방법

CoCo Desktop은 Snowflake에 로그인하는 여러 방법을 지원해요. 내 계정에 맞는 것을 골라요.

Local OAuth(권장)

브라우저를 열어 안전하게 로그인해요. 토큰은 운영체제의 키체인에 캐시되므로 매번 로그인할 필요가 없어요. 기본이자 권장 옵션이에요.

[my-connection]
account = "myorg-myaccount"
user = "myuser"
authenticator = "oauth_authorization_code"
client_store_temporary_credential = true

External Browser(SSO)

내 조직의 Identity Provider(Okta, Azure AD 등)를 통해 로그인해요. 내 Snowflake 계정에 SSO가 구성되어 있어야 해요.

[my-sso-connection]
account = "myorg-myaccount"
user = "myuser"
authenticator = "externalbrowser"
client_store_temporary_credential = true

Password

전통적인 사용자 이름과 비밀번호예요. 계정에 MFA가 설정되어 있으면 로그인 시 내 인증 앱에서 안내가 떠요.

참고

비밀번호를 평문으로 저장하는 것은 권장하지 않아요. 가능하면 OAuth나 SSO를 선호해요.

Key Pair(JWT)

RSA 키 쌍으로 인증해요. 서비스 계정과 자동화 워크플로에 흔해요. connections.toml을 직접 편집해 이 옵션을 구성해요.

[my-keypair-connection]
account = "myorg-myaccount"
user = "myuser"
authenticator = "snowflake_jwt"
private_key_path = "~/.ssh/snowflake_rsa_key.p8"

개인 키가 암호화되어 있으면 private_key_passphrase로 암호를 설정해요. CoCo Desktop은 private_key_file_pwd(Snowflake 커넥터의 파라미터 이름)도 폴백으로 읽어요.

연결 파일 참조

CoCo Desktop은 ~/.snowflake/connections.toml에서 연결 설정을 읽어요. 이 파일을 직접 편집해 warehouse나 role 같은 기본값을 설정하고, 여러 이름 있는 연결을 정의할 수 있어요.

# ~/.snowflake/connections.toml
default_connection_name = "dev"

[dev]
account = "myorg-myaccount"
user = "myuser"
authenticator = "oauth_authorization_code"
client_store_temporary_credential = true
warehouse = "COMPUTE_WH"
role = "MY_ROLE"
database = "MY_DB"
schema = "PUBLIC"

[prod]
account = "myorg-prodaccount"
user = "myuser"
authenticator = "externalbrowser"
client_store_temporary_credential = true

공통 필드

필드	설명
`account`	계정 식별자(`orgname-accountname`). 필수.
`host`	Snowflake 호스트 URL 오버라이드. PrivateLink 연결이나 계정 식별자만으로 엔드포인트를 확인할 수 없는 정부 리전(예: `myorg-myaccount.privatelink.snowflakecomputing.com`)에 사용해요.
`user`	내 Snowflake 사용자 이름. 필수.
`authenticator`	로그인 방법(예: `oauth_authorization_code`, `externalbrowser`, `snowflake`).
`warehouse`	쿼리용 기본 웨어하우스.
`role`	기본 역할.
`database`	기본 데이터베이스.
`schema`	기본 스키마.
`client_store_temporary_credential`	OAuth/SSO 토큰을 캐시해 매번 로그인하지 않게 해요.

자격 증명 보안

CoCo Desktop은 운영체제의 내장 암호화로 인증 토큰을 저장해요.

macOS: Keychain
Windows: Data Protection API(DPAPI)
Linux: System secret service(libsecret / GNOME Keyring)

이 덕분에 앱은 다음 실행 때 다시 로그인하라고 요구하지 않고 자동으로 재연결돼요.

문제 해결

연결 테스트 실패

오류	의미	해결 방법
Account not found	계정 식별자가 올바르지 않아요.	app.snowflake.com에서 확인해요.
Authentication failed	잘못된 비밀번호, 만료된 토큰, 또는 SSO 불일치.	자격 증명을 다시 입력하거나 브라우저로 다시 로그인해요.
Connection failed	네트워크 또는 방화벽 문제.	네트워크 연결과 방화벽 설정을 확인해요.
File not found	참조된 파일(개인 키, 토큰 파일)이 없어요.	connections.toml에서 경로를 확인해요.

OAuth/SSO에서 브라우저가 열리지 않음

기본 브라우저가 구성되어 있는지 확인해요.
앱에 표시된 폴백 링크를 사용해 수동으로 로그인해요.

온보딩 다시 실행

명령 팔레트를 열고 Reset Onboarding을 실행하면 다음 실행 때 설정 흐름이 다시 보여요.

모범 사례

가장 안전한 로그인 환경을 위해 OAuth나 SSO를 사용해요. 디스크에 저장되는 비밀번호가 없어요.
자격 증명 캐싱(client_store_temporary_credential = true)을 켜서 매번 로그인하지 않게 해요.
쿼리 실행 시 오류를 피하려면 기본 웨어하우스를 설정해요(설정 중, 연결 메뉴에서, 또는 connections.toml에서).
연결 이름을 설명적으로 지어요(예: prod-analytics, dev-sandbox) 드롭다운에서 고르기 쉽게요.

더 알아보기

Access control requirements — 역할 요구사항
Daily credit usage limits — 크레딧 한도
Auto-update — 업데이트 보안 근거