워크스페이스 관리 도구
이 도구들은 워크스페이스 전체에 적용되는 설정을 조회하고 수정합니다. 한 사용자의 개인 설정이 아니라 워크스페이스에 속한 모두에게 적용되는 설정입니다. sudo와 터널 접근을 통제하는 권한 상승·세션 수명 정책, 로그인 시 요구되는 인증·MFA 조건, 타임존·결제 이메일·초대 허용 도메인 같은 워크스페이스 환경설정을 다룹니다. “워크스페이스 전체의 sudo 정책이 뭐야”, “여기 로그인할 때 MFA가 필수야” 같은 요청이 이 도구들로 이어집니다.
모든 도구는 workspace(필수)와 region(선택, 기본값은 설정된 리전)을 받습니다. 이 공통 파라미터는 아래 표에서 생략합니다.
요약
| 도구 | 설명 | 접근 수준 |
|---|---|---|
get_workspace_access_control | sudo/root 접근 정책, 터널·편집기 기본값, 작업 세션 TTL 조회 | 읽기 전용 |
get_workspace_security | 워크스페이스의 인증·MFA 요구 사항 조회 | 읽기 전용 |
list_workspace_mfa_methods | 워크스페이스에서 허용하는 MFA 방식 목록 조회 | 읽기 전용 |
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를 반환합니다. 상위 권한을 요청하기 전에 워크스페이스 전체에 적용되는 권한 상승·세션 수명 규칙을 확인할 때 사용합니다.
Auth0가 없는 배포(셀프호스팅)에서는 allow_sudo_with_mfa와 sudo_timeout이 응답에서 빠집니다. block_local_sudo는 저장된 값 true가 적용 중일 때만 반환되므로 찾아서 끌 수 있지만, 이 배포에서 켤 수는 없습니다.
접근 수준: 읽기 전용
예시
“우리 워크스페이스의 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 재인증을 요구하며 실패했을 때, 사용자에게 어떤 방식으로 브라우저 재인증을 완료할 수 있는지 알려줄 때 유용합니다.
이 목록이 패스키 로그인을 MFA로 인정할지도 결정합니다. 목록이 비어 있거나 webauthn-platform(생체 인증) 또는 webauthn-roaming(하드웨어 보안 키)이 들어 있으면 MFA로 인정됩니다. 자세한 내용은 패스키와 허용된 MFA 수단을 참고하세요. 응답에 passkey_as_mfa가 함께 올 수 있지만, 더 이상 쓰지 않는 설정이라 결과에 영향을 주지 않습니다.
접근 수준: 읽기 전용
예시
“방금 도구 호출이 MFA 재인증을 요구하던데, 어떤 방식을 쓸 수 있어?”
에이전트는 list_workspace_mfa_methods를 호출해 재인증에 사용할 수 있는 방식을 알려줍니다.
환경설정
get_workspace_preferences
워크스페이스 환경설정을 조회합니다: timezone, 로케일(country/language), front_url, invite_ttl, enabled_extensions, websh_session_timeout, agent_rollout_policy, package_proxy, billing_email, allowed_domains를 반환합니다. 개인 설정이 아니라 워크스페이스 전역 설정입니다.
응답에는 한 릴리스 동안만 유지되는 지원 중단 예정 불리언 auto_agent_upgrade도 들어 있습니다. 롤아웃 mode가 manual이 아니면 true입니다. 이 값 대신 agent_rollout_policy를 읽으세요.
접근 수준: 읽기 전용
예시
“이 워크스페이스는 타임존과 초대 설정이 어떻게 돼 있어?”
에이전트는 get_workspace_preferences를 호출해 timezone과 invite_ttl을 알려줍니다.
update_workspace_preferences
워크스페이스 환경설정을 수정합니다. 전달한 필드만 반영됩니다(부분 수정).
timezone은 워크스페이스의 결제 기준 시각이기도 합니다. 값을 바꾸면 일별 사용량 집계 기준 시점도 함께 바뀝니다. enabled_extensions와 allowed_domains는 목록을 추가하지 않고 전체를 교체합니다. 기존 항목을 지우지 않으려면 get_workspace_preferences로 현재 값을 조회한 뒤 합쳐서 전체 목록을 다시 전송하세요. enabled_extensions에 워크스페이스 플랜이 지원하지 않는 확장 기능이 포함되면 HTTP 402 오류가 발생합니다. 확장 기능마다 필요한 플랜이 다른데, Metrics는 Essentials부터, 나머지는 Enterprise부터 사용할 수 있습니다(자세한 내용은 확장 기능 참고). IP 없이 DNS나 Proxy를 새로 켜거나, DNS나 Proxy를 그대로 둔 채 IP를 빼면 HTTP 400 workspace_extension_requires_extension 오류가 발생합니다. billing_email과 allowed_domains는 Alpacon Cloud에서만 적용됩니다.
접근 수준: 멱등적 쓰기
파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
front_url | string | 아니오 | 워크스페이스 프런트엔드 URL |
country | string | 아니오 | 워크스페이스 국가 코드 |
language | string | 아니오 | 워크스페이스 로케일·언어 코드 |
timezone | string | 아니오 | 워크스페이스 타임존. 결제 기준 시각으로도 사용됩니다 |
invite_ttl | integer | 아니오 | 초대 링크 유효 기간(초) |
enabled_extensions | array | 아니오 | 활성화된 확장 기능 이름 목록. 전체를 교체하며, 워크스페이스 플랜이 지원하지 않는 확장 기능이 포함되면 HTTP 402 오류가 발생합니다(Metrics는 Essentials부터, 나머지는 Enterprise부터). IP 없이 DNS나 Proxy를 새로 켜거나 DNS나 Proxy를 둔 채 IP를 빼면 HTTP 400 오류가 발생합니다 |
websh_session_timeout | integer | 아니오 | Websh 유휴 세션 타임아웃(초) |
agent_rollout_policy | object | 아니오 | 에이전트 롤아웃 정책: {"mode": "latest" | "n_minus_1" | "manual", "window": {"days": [0-6, Monday is 0], "start_hour": 0-23, "length_hours": 1-24, "timezone": "<IANA>"}}. 객체의 일부만 지정할 수 있으며, 지정하지 않은 값은 그대로 유지됩니다 |
auto_agent_upgrade | boolean | 아니오 | 지원 중단 예정이며 한 릴리스 동안만 유지됩니다. agent_rollout_policy를 사용하세요. 지원 중단 예정인 auto_agent_upgrade 참고 |
package_proxy | string | 아니오 | 패키지 설치용 프록시 서버 URL(예: http://proxy.example.com:8080) |
billing_email | string | 아니오 | 결제 담당자 이메일. Alpacon Cloud에서만 적용됩니다 |
allowed_domains | array | 아니오 | 초대를 허용할 이메일 도메인. Alpacon Cloud에서만 적용되며 전체 목록을 교체합니다 |
에이전트 롤아웃 정책
manual은 자동 업그레이드를 하지 않고, latest는 유지보수 시간대 안에서 에이전트를 새 릴리스로 업그레이드하며, n_minus_1은 최신 릴리스보다 한 단계 뒤에 머뭅니다. 검증된 업그레이드가 켜지기 전에는 n_minus_1을 지정하면 preferences_agent_rollout_mode_unavailable로 거부되므로 latest나 manual을 사용하세요. 형식이 잘못된 agent_rollout_policy는 요청을 보내기 전에 어느 필드가 문제인지 알려 주는 메시지와 함께 거부됩니다. 형식은 맞지만 서버가 거부한 값은 오류 코드(preferences_agent_rollout_policy_invalid, _mode_invalid, _window_days_invalid, _window_start_hour_invalid, _window_length_invalid, _window_timezone_invalid)와 무엇을 고쳐야 하는지 알려 주는 메시지로 돌아옵니다. 필드별 허용 범위는 워크스페이스 환경설정 API를 참고하세요.
지원 중단 예정인 auto_agent_upgrade
auto_agent_upgrade는 한 릴리스 동안 계속 받으며, 요청을 보내기 전에 롤아웃 정책 변경으로 바뀝니다.
true는{"mode": "latest"}로,false는{"mode": "manual"}로 바뀝니다. 유지보수 시간대는 바뀌지 않습니다.- 같은 호출에
agent_rollout_policy도 전달하면,agent_rollout_policy가 지정한 필드는 그 값이 우선합니다. - 이 값을 사용한 호출의 응답에는
deprecation_note가 포함됩니다.
예시
“결제 이메일을 ops@example.com으로 설정하고, 워크스페이스 타임존을 America/New_York으로 바꿔줘”
에이전트는 billing_email="ops@example.com"과 timezone="America/New_York"을 담아 update_workspace_preferences를 호출하고, 나머지 필드는 그대로 둡니다.
“에이전트 업그레이드는 주말에만, 서울 시간 밤 10시부터 6시간 동안 하게 해줘”
에이전트는 agent_rollout_policy={"window": {"days": [5, 6], "start_hour": 22, "length_hours": 6, "timezone": "Asia/Seoul"}}를 담아 update_workspace_preferences를 호출하고, 모드는 그대로 둡니다.
관련 문서
- 접근 제어·승인 도구: 이 도구들이 조회하는 워크스페이스 전체 정책과 별개로, 토큰별 ACL과 sudo 정책을 다룹니다
- 작업 세션:
get_workspace_access_control이 반환하는 TTL 값이 적용되는 세션입니다 - 이벤트·웹훅 도구: 웹훅 엔드포인트와 이벤트 구독을 구성합니다