---
title: "워크스페이스 환경설정 API"
description: "API로 Alpacon 워크스페이스 환경설정을 조회하고 변경하는 방법을 안내합니다. 에이전트 업그레이드 시점을 정하는 롤아웃 정책과 유지보수 시간대, 지원 중단 예정인 이전 필드를 함께 설명합니다."
---

> Full documentation index: https://docs.alpacax.com/llms.ko.txt

# 워크스페이스 환경설정

**엔드포인트**: `/api/workspaces/preferences/`

**워크스페이스 설정** → **일반**에 표시되는 워크스페이스 전체 환경설정을 조회하고 변경합니다.
[에이전트 업데이트 정책](/use/workspace/settings/agent-updates/)도 여기에 포함됩니다.
워크스페이스마다 환경설정 객체가 하나씩 있습니다.

  Alpacon Cloud에서는 웹 콘솔이나
  [Alpacon MCP 서버](/reference/mcp/tools/workspace-settings/#환경설정) 같은 OAuth 클라이언트의
  로그인 세션으로 이 엔드포인트를 호출해야 합니다. API 토큰을 사용하면 `401`을 반환합니다. 자체
  호스팅 배포에서는 [`preferences`](/reference/scopes/#preferences) 범위가 있는 API 토큰을 사용할 수
  있습니다.

  
    ## 환경설정 조회

    워크스페이스 멤버라면 누구나 환경설정을 조회할 수 있습니다.

    ### 요청

    ```http
    GET /api/workspaces/preferences/-/
    ```

    ### 응답

    ```json
    {
      "front_url": "https://your-workspace.ap1.alpacon.io",
      "country": "US",
      "language": "en",
      "timezone": "America/New_York",
      "invite_ttl": 172800,
      "enabled_extensions": ["metrics"],
      "websh_session_timeout": 86400,
      "agent_rollout_policy": {
        "mode": "latest",
        "window": {
          "days": [0, 1, 2, 3, 4],
          "start_hour": 2,
          "length_hours": 4,
          "timezone": "America/New_York"
        }
      },
      "auto_agent_upgrade": true,
      "package_proxy": null,
      "billing_email": "billing@example.com"
    }
    ```

    | 필드 | 유형 | 설명 |
    |-------|------|-------------|
    | `front_url` | 문자열 | 워크스페이스의 콘솔 URL |
    | `country`, `language` | 문자열 | 워크스페이스의 국가 및 기본 표시 언어 |
    | `timezone` | 문자열 | 워크스페이스의 기본 시간대 |
    | `invite_ttl` | 정수 | 초 단위의 초대 링크 유효 기간 |
    | `enabled_extensions` | 배열 | 활성화된 [확장 기능](/use/workspace/settings/extensions/) |
    | `websh_session_timeout` | 정수 | 초 단위의 Websh 세션 제한 시간 |
    | `agent_rollout_policy` | 객체 | [에이전트 롤아웃 정책](#에이전트-롤아웃-정책) |
    | `auto_agent_upgrade` | 불리언 | **지원 중단 예정.** [지원 중단 예정인 `auto_agent_upgrade`](#지원-중단-예정인-auto_agent_upgrade) 참고 |
    | `package_proxy` | 문자열 또는 `null` | 패키지 설치용 프록시 서버 URL |
    | `billing_email` | 문자열 | 청구 담당자 이메일. Alpacon Cloud에만 해당 |
  </Tabs.Tab>

  <Tabs.Tab>
    ## 환경설정 변경

    환경설정을 하나 이상 변경할 수 있습니다. Staff와 Superuser 멤버만 변경할 수 있으며, 요청에
    포함한 필드만 바뀝니다.

    ### 요청

    ```http
    PATCH /api/workspaces/preferences/-/
    ```

    ### 요청 본문

    ```json
    {
      "agent_rollout_policy": {
        "window": {
          "days": [5, 6],
          "start_hour": 22,
          "length_hours": 6,
          "timezone": "Asia/Seoul"
        }
      }
    }
    ```

    ### 응답

    환경설정 객체 전체를 반환합니다. 형식은 [환경설정 조회](#환경설정-조회)와 같습니다.
  </Tabs.Tab>
</Tabs>

## 에이전트 롤아웃 정책

`agent_rollout_policy`는 Alpacon이 이 워크스페이스의 에이전트를 자동으로 업그레이드할지,
업그레이드한다면 어느 시간대에 진행할지 결정합니다.

```json
{
  "mode": "latest",
  "window": {
    "days": [0, 1, 2, 3, 4, 5, 6],
    "start_hour": 0,
    "length_hours": 24,
    "timezone": "UTC"
  }
}
```

| 필드 | 유형 | 설명 |
|-------|------|-------------|
| `mode` | 문자열 | `latest`는 지정한 시간대에 에이전트를 새 릴리스로 업그레이드함. `n_minus_1`은 최신 릴리스보다 한 버전 뒤에 머무름. 검증된 업그레이드가 활성화되기 전에는 `n_minus_1`을 선택하면 `preferences_agent_rollout_mode_unavailable` 오류가 발생함. `manual`은 자동 업그레이드를 하지 않으며, 각 서버에서 [`upgrade_agent` 작업](/reference/api/servers/servers/#에이전트-작업)으로 업그레이드해야 함 |
| `window.days` | 정수 배열 | 업그레이드 시간대가 시작되는 요일. `0`(월요일)부터 `6`(일요일)까지이며, 하나 이상 지정하고 중복 없이 입력해야 함 |
| `window.start_hour` | 정수 | `window.timezone`을 기준으로 업그레이드 시간대가 시작되는 시각. `0`부터 `23`까지 |
| `window.length_hours` | 정수 | 업그레이드 시간대의 길이. `1`부터 `24`까지이며, 자정을 넘어갈 수 있음. 실제 경과 시간을 기준으로 하므로 시간대가 열려 있는 동안 서머타임 전환이 일어나도 길이는 달라지지 않음 |
| `window.timezone` | 문자열 | `Asia/Seoul` 또는 `America/New_York` 같은 IANA 시간대 이름 |

위 예시는 기본값입니다. `latest` 모드에서 매일 24시간 업그레이드 시간대가 열리므로 언제든
업그레이드를 시작할 수 있습니다.

변경 요청에는 객체의 일부만 지정할 수 있습니다. `mode`만 지정하거나 `window`의 필드 하나만 지정해도
되며, 생략한 값은 현재 값으로 유지됩니다. 조회할 때는 항상 객체 전체가 반환됩니다.

Alpacon은 매주 월요일에 그 주의 자동 업그레이드를 지정된 시간대 안으로 계획합니다. 시간대를 변경하면
다음 월요일에 세우는 계획부터 적용됩니다. 이미 계획된 업그레이드가 변경 후 시간대 밖에 놓이면
다음으로 시간대가 열릴 때까지 기다립니다.

[서버 API](/reference/api/servers/servers/#서버-조회)의 각 서버 `agent_upgrade_policy` 필드에는
현재 `mode`가 담겨 있습니다.

## 지원 중단 예정인 `auto_agent_upgrade`

`auto_agent_upgrade`는 `agent_rollout_policy`로 대체된 불리언 값입니다. 앞으로 한 릴리스 동안 더 읽고 쓸 수
있으며, 그 뒤에는 삭제됩니다. 대신 `agent_rollout_policy`를 사용하세요.

- **읽기**: `mode`가 `manual`이 아니면 `true`를 반환함
- **`true` 쓰기**: `mode`를 `latest`로 설정함. 이미 자동 모드(`latest` 또는 `n_minus_1`)이면
  변경하지 않음
- **`false` 쓰기**: `mode`를 `manual`로 설정함
- 두 쓰기 모두 시간대(`window`)는 바꾸지 않음
- 요청에 두 필드가 모두 있으면 `agent_rollout_policy`를 적용하고 `auto_agent_upgrade`는 무시함
- JSON 불리언 값만 허용하며, 다른 값은 `invalid_input`으로 거부함

위 규칙은 REST API에 적용됩니다. MCP `update_workspace_preferences` 도구에서는 `agent_rollout_policy`를 직접 전달하세요. 자세한 내용은 [MCP 에이전트 롤아웃 정책](/reference/mcp/tools/workspace-settings/#에이전트-롤아웃-정책)을 확인하세요.

## 오류 응답

| 상태 | 오류 코드 | 설명 |
|--------|------------|-------------|
| 400 | `preferences_agent_rollout_policy_invalid` | `agent_rollout_policy` 또는 그 안의 `window`가 객체가 아니거나 존재하지 않는 필드를 지정함 |
| 400 | `preferences_agent_rollout_mode_invalid` | `mode`가 `latest`, `n_minus_1`, `manual` 중 하나가 아님 |
| 400 | `preferences_agent_rollout_mode_unavailable` | 검증된 업그레이드를 활성화하기 전에는 `n_minus_1`을 선택할 수 없음. `latest` 또는 `manual`을 선택해야 함 |
| 400 | `preferences_agent_rollout_window_days_invalid` | `days`가 비어 있거나, 같은 요일이 중복되거나, `0`~`6` 범위를 벗어난 값이 있음 |
| 400 | `preferences_agent_rollout_window_start_hour_invalid` | `start_hour`가 `0`부터 `23`까지의 정수가 아님 |
| 400 | `preferences_agent_rollout_window_length_invalid` | `length_hours`가 `1`부터 `24`까지의 정수가 아님 |
| 400 | `preferences_agent_rollout_window_timezone_invalid` | `timezone`이 IANA 시간대 이름이 아님 |
| 400 | `preferences_timezone_invalid` | `timezone`이 올바른 IANA 시간대 이름(예: `Asia/Seoul`)이 아님 |
| 400 | `workspace_extension_requires_extension` | `enabled_extensions`가 IP 없이 DNS나 Proxy를 켜거나, DNS나 Proxy를 그대로 둔 채 IP를 끔. 같은 목록에 `ip`를 함께 넣어야 함 |
| 401 | — | Alpacon Cloud의 API 토큰을 포함해 인증 정보가 잘못되었거나 없음. 오류 코드 없이 `{"detail": "..."}` 응답을 반환함 |
| 403 | — | Staff와 Superuser 멤버만 환경설정을 변경할 수 있음. 오류 코드 없이 `{"detail": "..."}` 응답을 반환함 |

Source: https://docs.alpacax.com/ko/reference/api/preferences/