워크스페이스 관리 도구
이 도구들은 워크스페이스 전체에 적용되는 설정을 조회하고 수정합니다. 한 사용자의 개인 설정이 아니라 워크스페이스에 속한 모두에게 적용되는 설정입니다. sudo와 터널 접근을 통제하는 권한 상승·세션 수명 정책, 로그인 시 요구되는 인증·MFA 조건, 알림 채널, 타임존·결제 이메일·초대 허용 도메인 같은 워크스페이스 환경설정을 다룹니다. “워크스페이스 전체의 sudo 정책이 뭐야”, “여기 로그인할 때 MFA가 필수야”, “서버가 끊기면 이메일로 알림을 받게 해줘” 같은 요청이 이 도구들로 이어집니다.
모든 도구는 workspace(필수)와 region(선택, 기본값은 설정된 리전)을 받습니다. 이 공통 파라미터는 아래 표에서 생략합니다.
요약
| 도구 | 설명 | 접근 수준 |
|---|---|---|
get_workspace_access_control | sudo/root 접근 정책, 터널·편집기 기본값, 작업 세션 TTL 조회 | 읽기 전용 |
get_workspace_security | 워크스페이스의 인증·MFA 요구 사항 조회 | 읽기 전용 |
list_workspace_mfa_methods | 워크스페이스에서 허용하는 MFA 방식 목록 조회 | 읽기 전용 |
get_workspace_notifications | 알림 채널 설정 조회 | 읽기 전용 |
update_workspace_notifications | 알림 채널 설정 수정 | 멱등적 쓰기 |
get_workspace_preferences | 타임존, 로케일, 결제 정보 등 워크스페이스 환경설정 조회 | 읽기 전용 |
update_workspace_preferences | 워크스페이스 환경설정 수정 | 멱등적 쓰기 |
접근 제어
get_workspace_access_control
워크스페이스 접근 제어 설정을 조회합니다: sudo/root 접근 정책(allow_sudo_with_mfa, allow_direct_root, block_local_sudo, sudo_timeout), 터널·편집기 기본값, home_directory_permission, 작업 세션 TTL(work_session_max_ttl, work_session_pending_ttl), 명령 환경 변수 감사 노출 여부, shared_account_names를 반환합니다. 상위 권한을 요청하기 전에 워크스페이스 전체에 적용되는 권한 상승·세션 수명 규칙을 확인할 때 사용합니다.
셀프호스팅 배포에서는 MFA 관련 필드(allow_sudo_with_mfa, block_local_sudo, sudo_timeout)가 응답에서 빠집니다.
접근 수준: 읽기 전용
예시
“우리 워크스페이스의 sudo·root 접근 정책이 뭐야?”
에이전트는 get_workspace_access_control을 호출해 sudo, root, 터널 정책 필드를 정리해서 알려줍니다.
보안과 MFA
get_workspace_security와 list_workspace_mfa_methods는 OAuth/SSO 로그인이 필요합니다. 정적 API 토큰으로는 요청 자체가 거부됩니다. 또한 Alpacon Cloud에서만 제공되며, 셀프호스팅 배포에서는 일반적인 오류 대신 해당 배포에서는 사용할 수 없다는 메시지를 반환합니다.
get_workspace_security
워크스페이스의 인증·보안 설정을 조회합니다: mfa_required, allowed_mfa_methods, mfa_timeout, 그리고 MFA가 필요한 작업 목록을 반환합니다.
접근 수준: 읽기 전용
예시
“이 워크스페이스에 로그인할 때 MFA가 필수야?”
에이전트는 get_workspace_security를 호출해 mfa_required와 allowed_mfa_methods를 알려줍니다.
list_workspace_mfa_methods
워크스페이스에서 허용하는 MFA 방식을 조회합니다: allowed_mfa_methods와 패스키로 MFA를 대체할 수 있는지(passkey_as_mfa)를 반환합니다. 도구 호출이 MFA 재인증을 요구하며 실패했을 때, 사용자에게 어떤 방식으로 브라우저 재인증을 완료할 수 있는지 알려줄 때 유용합니다.
접근 수준: 읽기 전용
예시
“방금 도구 호출이 MFA 재인증을 요구하던데, 어떤 방식을 쓸 수 있어?”
에이전트는 list_workspace_mfa_methods를 호출해 재인증에 사용할 수 있는 방식을 알려줍니다.
알림
get_workspace_notifications
워크스페이스 알림 설정을 조회합니다: disconnection_notification과 워크스페이스 수준 알림을 전달하는 notification_channels를 반환합니다.
접근 수준: 읽기 전용
예시
“서버 연결이 끊기면 알림을 받고 있어?”
에이전트는 get_workspace_notifications를 호출해 disconnection_notification과 설정된 채널을 알려줍니다.
update_workspace_notifications
워크스페이스 알림 설정을 수정합니다. 전달한 필드만 반영됩니다(부분 수정).
notification_channels는 목록 전체를 교체하며 추가되지 않습니다. 채널을 추가하려면 먼저 get_workspace_notifications로 현재 목록을 조회한 뒤 새 채널을 합쳐 전체 목록을 다시 전송하세요. 그렇지 않으면 빠진 채널은 삭제됩니다.
접근 수준: 멱등적 쓰기
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
disconnection_notification | boolean | 아니오 | 서버 연결이 끊기면 알림 발송 여부 |
notification_channels | array | 아니오 | 알림을 전달할 채널 유형(예: email, webhook, push). 목록 전체를 교체합니다 |
예시
“서버가 끊기면 이메일로도 알려주고, 기존 웹훅 채널은 그대로 유지해줘”
에이전트는 먼저 get_workspace_notifications로 현재 채널을 조회한 뒤, disconnection_notification=true와 기존 webhook 항목을 포함해 합친 목록을 notification_channels에 담아 update_workspace_notifications를 호출합니다.
환경설정
get_workspace_preferences
워크스페이스 환경설정을 조회합니다: timezone, 로케일(country/language), front_url, invite_ttl, enabled_extensions, websh_session_timeout, auto_agent_upgrade, package_proxy, billing_email, allowed_domains를 반환합니다. 개인 설정이 아니라 워크스페이스 전역 설정입니다.
접근 수준: 읽기 전용
예시
“이 워크스페이스는 타임존과 초대 설정이 어떻게 돼 있어?”
에이전트는 get_workspace_preferences를 호출해 timezone과 invite_ttl을 알려줍니다.
update_workspace_preferences
워크스페이스 환경설정을 수정합니다. 전달한 필드만 반영됩니다(부분 수정).
timezone은 워크스페이스의 결제 기준 시각이기도 합니다. 값을 바꾸면 일별 사용량 집계 기준 시점도 함께 바뀝니다. enabled_extensions와 allowed_domains는 목록을 추가하지 않고 전체를 교체합니다. 기존 항목을 지우지 않으려면 get_workspace_preferences로 현재 값을 조회한 뒤 합쳐서 전체 목록을 다시 전송하세요. enabled_extensions를 줄이는 경우 엔터프라이즈 이하 플랜에서는 HTTP 402 오류가 발생합니다. billing_email과 allowed_domains는 Alpacon Cloud에서만 적용됩니다.
접근 수준: 멱등적 쓰기
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
front_url | string | 아니오 | 워크스페이스 프런트엔드 URL |
country | string | 아니오 | 워크스페이스 국가 코드 |
language | string | 아니오 | 워크스페이스 로케일·언어 코드 |
timezone | string | 아니오 | 워크스페이스 타임존. 결제 기준 시각으로도 사용됩니다 |
invite_ttl | integer | 아니오 | 초대 링크 유효 기간(초) |
enabled_extensions | array | 아니오 | 활성화된 확장 기능 이름 목록. 전체를 교체하며, 목록을 줄이면 엔터프라이즈 이하 플랜에서 HTTP 402 오류가 발생합니다 |
websh_session_timeout | integer | 아니오 | Websh 유휴 세션 타임아웃(초) |
auto_agent_upgrade | boolean | 아니오 | 에이전트 자동 업그레이드 여부 |
package_proxy | string | 아니오 | 패키지 설치용 프록시 서버 URL(예: http://proxy.example.com:8080) |
billing_email | string | 아니오 | 결제 담당자 이메일. Alpacon Cloud에서만 적용됩니다 |
allowed_domains | array | 아니오 | 초대를 허용할 이메일 도메인. Alpacon Cloud에서만 적용되며 전체 목록을 교체합니다 |
예시
“결제 이메일을 ops@example.com으로 설정하고, 워크스페이스 타임존을 America/New_York으로 바꿔줘”
에이전트는 billing_email="ops@example.com"과 timezone="America/New_York"을 담아 update_workspace_preferences를 호출하고, 나머지 필드는 그대로 둡니다.
관련 문서
- 접근 제어·승인 도구: 이 도구들이 조회하는 워크스페이스 전체 정책과 별개로, 토큰별 ACL과 sudo 정책을 다룹니다
- 작업 세션:
get_workspace_access_control이 반환하는 TTL 값이 적용되는 세션입니다 - 이벤트·웹훅 도구: 워크스페이스 수준 알림 채널과 별개로 개별 웹훅 엔드포인트를 구성합니다