Work: 격리된 워크스페이스

Work는 Libre WebUI의 네이티브 코딩 에이전트 화면입니다. 각 Work 작업은 영구 대화, 명시적인 모델 공급자 경로와 /workspace의 전용 파일 시스템을 결합합니다. 선택한 모델은 파일을 검사하고 편집하고, 작업 범위 Docker 컨테이너 또는 Kubernetes Pod에서 명령을 실행하며, 브라우저 미리 보기를 시작할 수 있습니다.

Work는 Libre WebUI에 직접 구현되어 있습니다. Libre Claw나 다른 에이전트 데몬이 필요하지 않습니다.

신뢰할 수 있는 사용자에게만 허용

모든 Work API에는 인증된 계정과 Work 접근 권한이 필요합니다. 기본적으로 관리자만 사용할 수 있으며 관리자는 설정의 사용자 관리 탭에서 모든 활성 사용자에게 Work를 열 수 있습니다. 단, 서버 경로를 바인드 마운트하는 호스트 폴더 워크스페이스는 항상 관리자 전용입니다. Work에서는 모델이 샌드박스 안에서 임의의 셸 명령을 실행할 수 있습니다. 선택한 명명 런타임 정책에서 비활성화하지 않는 한 작업은 외부 네트워크에 접근합니다. Work 접근 권한을 부여하는 모든 사용자를 단순한 채팅 사용자가 아니라 신뢰할 수 있는 런타임 운영자로 취급하세요.

릴리스 주요 내용

이번 릴리스에서는 Work를 완전한 작업 흐름으로 제공합니다.

• 기본 사이드바에 Work와 채팅 작업을 분리하고 현재 모드를 명확하게 표시합니다.
• 두 번째 작업 레일 대신 일반 사이드바에 Work 작업을 표시합니다. 실행이 업데이트되어도 기존 작업 위치가 그대로 유지되며 선택한 작업을 직접 삭제할 수 있습니다.
• 모든 작업에 전용 샌드박스 ID와 영구 Docker 볼륨 또는 Kubernetes PVC를 제공합니다. 작업 파일을 삭제하지 않고 샌드박스를 중지하거나 다시 만들 수 있습니다.
• 영구 대화, 실행 상태, 도구 활동, 모델 선택과 작업 소유권을 Libre WebUI 데이터베이스에 저장합니다.
• 어시스턴트 텍스트, 공급자가 공개한 추론, 도구 호출과 결과, 사용량, 워커 스킬, 상태 변경을 위한 인증된 실시간 실행 스트림을 제공합니다.
• 서버 소유 워커 스킬은 프로젝트에 제어 파일을 쓰지 않고 선택한 모델에 효율적인 검사, 편집, 검증과 미리 보기 방법을 알려 줍니다.
• 도구를 지원하는 로컬 Ollama 모델, Ollama Cloud 모델과 구성된 완성 또는 채팅 공급자 플러그인을 지원합니다.
• 데스크톱에서는 드래그 및 키보드로 크기를 조절할 수 있는 반응형 대화/워크스페이스 분할을, 작은 화면에서는 화면 전환기를 제공합니다.
• 파일, 활동, Git, 터미널, 미리 보기, 화면 보기를 통합합니다. 화면 보기는 관찰하고 가르칠 수 있는 Work Computer 데스크톱입니다.
• 다크/라이트 모드 구문 강조, 브라우저 측 코드 서식 지정, 저장 충돌 감지와 임시 미저장 초안을 제공합니다.
• 원격 모델 공급자를 선택하면 사용자별로 닫을 수 있는 정보 공개 알림을 표시합니다.
• 지원되는 25개 로캘 전체에 완전한 Work 번역을 제공하며, 아랍어에서는 코드, 경로, 모델 식별자와 명령 출력을 왼쪽에서 오른쪽으로 유지하면서 네이티브 오른쪽에서 왼쪽 레이아웃을 적용합니다.

영구 단위는 계속 실행되는 컨테이너가 아니라 작업 워크스페이스입니다. Libre WebUI는 필요에 따라 작업 컨테이너를 시작, 중지하거나 다시 만들 수 있으며 명명 볼륨은 유지합니다.

아키텍처

모델이나 브라우저가 아니라 Libre WebUI가 샌드박스 및 워크스페이스 이름, 이미지, 마운트, 사용자, 한도, 네트워크 모드와 미리 보기 포트를 선택합니다. 모델에는 다음 도구만 제공됩니다.

• list_files
• read_file
• write_file
• delete_file
• move_file
• search_files
• run_command
• start_preview
• stop_preview

delete_file과 move_file에는 다른 파일 도구와 같은 경로 보호가 적용됩니다. 워크스페이스 밖으로 나갈 수 없고, 심볼릭 링크를 따라가지 않으며, 디렉터리를 제거하려면 명시적 재귀 플래그가 필요하고, 이동 대상의 기존 파일을 덮어쓰지 않습니다. 셸이 아니라 파일 도우미 경로를 통해 실행되므로 미리 보기가 실행되어 run_command가 차단된 동안에도 작동합니다.

모델 요청은 Libre WebUI 백엔드에서 수행합니다. Work 컨테이너에서 시작하지 않으며 컨테이너의 네트워크 정책에 의존하지 않습니다.

요구 사항

Work에는 구성된 샌드박스 백엔드가 필요합니다.

• 기본 백엔드에는 Docker가 설치되어 있고 데몬에 접근할 수 있어야 하며, 백엔드 프로세스가 docker 또는 WORK_DOCKER_COMMAND로 구성한 실행 파일을 호출할 권한이 있어야 합니다.
• Kubernetes 백엔드에는 API 자격 증명과 함께 Helm 차트에서 work.enabled=true일 때 생성하는 네임스페이스 범위 Role, RoleBinding, 샌드박스 네임스페이스, NetworkPolicy가 필요합니다.

모든 백엔드에 다음도 필요합니다.

• 다음 경로 중 하나를 통해 제공되는 도구 지원 모델:
  • Ollama Cloud를 통해 이용하는 모델을 포함한 정상 상태의 Ollama 서비스
  • 현재 관리자의 정확한 모델과 자격 증명이 구성된 활성 완성/채팅 플러그인
• 이미지, 생성 프로젝트와 프로젝트 로컬 의존성을 위한 충분한 런타임 저장소
• Work 접근 권한이 있는 인증된 계정. Work는 기본적으로 관리자 전용이며 관리자가 모든 활성 사용자에게 열 수 있습니다.

Libre WebUI는 실행을 만들기 전에 Ollama가 공개한 모델 기능을 확인하고 tools를 명시하지 않는 Ollama 모델을 거부합니다. 플러그인 기반 모델은 해당 공급자의 도구 호출 프로토콜을 지원해야 합니다. 선택한 원격 모델이 도구를 거부하면 실행이 실패하며 Work는 다른 모델이나 공급자로 조용히 전환하지 않습니다.

로컬에서 시작하기

가장 간단하게 지원되는 Work 환경에서는 브라우저와 같은 컴퓨터에서 Libre WebUI와 Docker를 실행합니다.

docker info
npx libre-webui@latest

http://localhost:8080을 열고 관리자로 로그인한 뒤 사이드바에서 Work를 선택하고 호환 모델을 고른 다음 프로젝트 또는 변경 사항을 설명합니다.

Docker가 없거나 중지되었거나 접근할 수 없으면 Work에 백엔드 이유와 함께 런타임을 사용할 수 없음이 표시되고 실행 작성기가 비활성화됩니다. Libre WebUI는 Work 명령을 호스트에서 직접 실행하는 방식으로 절대 대체하지 않습니다.

처음 사용할 때 런타임 이미지를 검사하고 없으면 자동으로 가져옵니다. 따라서 첫 작업은 이후 작업보다 오래 걸릴 수 있습니다.

Work 인터페이스 사용하기

작업 만들고 다시 열기

사이드바에서 채팅 옆의 Work를 선택합니다. 지시를 입력하고 모델을 선택한 다음 실행을 누릅니다. 첫 메시지가 작업, 첫 실행, 공급자 경로와 영구 워크스페이스를 만듭니다.

각 작업은 기본 사이드바에 남습니다. 다시 열면 최근 대화, 파일 보기, 현재 공급자/모델 선택과 워크스페이스가 복원됩니다. 이전 대화 메시지는 페이지 단위로 더 불러올 수 있습니다. 제목에서 작업 이름을 변경하고 선택한 작업 메뉴나 사이드바에서 영구 삭제할 수 있습니다.

작업마다 한 번에 실행 하나만 활성화할 수 있습니다. 이후 지시는 같은 대화와 파일 시스템을 대상으로 새 실행을 만듭니다.

작성기에서는 받아쓰기를 사용할 수 있습니다. 마이크 버튼은 가능한 경우 브라우저 음성 API를 사용하고, 그렇지 않으면 구성된 음성 텍스트 변환 공급자 모델을 대체 경로로 사용해 기존 입력 뒤에 대본을 추가합니다. 대화에서 실행이 만들거나 이동한 파일은 이를 만든 도구 활동 아래에 클릭 가능한 칩으로 표시됩니다. 칩을 클릭하면 워크스페이스 파일 편집기에서 파일이 열리고 좁은 화면에서는 워크스페이스 화면으로 전환됩니다. 칩은 변경 도구에서만 생성되므로 파일 20개를 읽고 하나를 쓴 실행에는 해당 아티팩트 하나만 표시됩니다.

에이전트 고용하기

페르소나가 있으면 시작 화면에 에이전트로 고용이 표시됩니다. 하나를 선택하면 생성된 작업이 일회성 작업이 아니라 영구적으로 이름이 지정된 에이전트가 됩니다. 에이전트는 여러 실행에서 페르소나를 유지합니다. 페르소나의 이름과 시스템 프롬프트는 Work 시스템 프롬프트 앞에 붙지만 샌드박스 런타임 계약이 항상 우선합니다. 사이드바에서는 에이전트를 임시 작업 위의 별도 에이전트 그룹에 고정하고 페르소나 아바타, 활동 표시기와 한 줄 상태를 표시합니다. 사이드바가 축소되면 레일에는 고정된 에이전트 아바타만 남고, 일회성 Work 작업은 사이드바를 다시 펼치면 나타납니다.

상태 줄에는 두 단계가 있습니다. 고용된 에이전트의 경우 실행이 끝날 때 도구를 사용하지 않는 저비용 모델 요청 하나가 약 8단어 상태(예: "받은 편지함 정리 완료. 답변 2개 준비됨.")를 요청합니다. 응답은 90자 한 줄로 제한되며 실패하거나 시간 초과되면 결정적 단계, 즉 최종 어시스턴트 메시지의 첫 줄로 대체됩니다. 임시 작업과 실패한 실행은 결정적 단계만 사용하고 WORK_STATUS_BLURB_MODEL=0은 모델 요청을 완전히 비활성화합니다. 에이전트에는 읽지 않음 표시도 있습니다. 작업을 열면 작업별 확인 마커가 앞으로 이동하고(단조 증가하며 기기 간 동기화됨), 이후 실행이 종료 상태가 되면 사이드바에 점이 표시됩니다.

에이전트는 알림을 통해서도 상태를 알립니다. 앱 내 알림과 활성화된 경우 Web Push로 실행 완료 시 work-run-finished, 입력 대기 또는 실패 시 work-run-attention, 에이전트가 화면 직접 조작을 요청하는 순간 work-takeover가 전송됩니다. 화면 배너는 화면 탭이 열려 있을 때만 보이므로 다른 곳에서는 푸시가 이를 알려 줍니다. 각 알림은 에이전트로 바로 연결됩니다.

내가 소유하거나 공유받은 페르소나로 고용할 수 있으며 공유 보기에서 소유자의 페르소나 메모리는 절대 노출되지 않습니다. 이후 페르소나가 삭제되어도 에이전트는 페르소나 없이 계속 실행되고 경고가 기록됩니다. API는 작업 생성 시 personaId와 isAgent를 받으며 페르소나로 만든 작업은 자동으로 에이전트가 됩니다.

에이전트 탭

에이전트의 워크스페이스 창에는 첫 번째 탭으로 에이전트 전용 페이지인 에이전트 탭이 추가됩니다.

• ID: 페르소나 아바타, 이름, 활동 표시기와 최신 상태 줄
• 화면: 작업 정책에서 Work Computer를 허용하면 에이전트 화면의 작고 보기 전용인 실시간 썸네일을 표시합니다. 실제 뷰어이므로 작업별 뷰어 예산에 포함됩니다. 클릭하면 직접 조작, 가르치기, 오디오를 사용할 수 있는 전체 화면 탭이 열립니다.
• 루틴: 이 작업에 바인딩된 자동화입니다. 실행할 때마다 새 작업이 아니라 에이전트의 모델 및 런타임을 사용해 에이전트 자체 워크스페이스와 대화 안에서 실행되므로 아침 브리핑 같은 루틴이 한곳에 누적됩니다. 행에는 일정을 자연어로 표시하고 일시 중지/재개 토글을 제공하며 인라인 + 루틴 양식은 이미 에이전트에 바인딩되어 있습니다. 에이전트가 바쁜 동안 발생한 일정은 큐에 넣지 않고 work-task-busy로 정확히 실패합니다.
• 자동 검토: 에이전트별 승인 스위치와 에이전트가 모아 둔 항상 허용 규칙입니다(규칙을 지우면 그 범위를 다시 좁힐 수 있습니다). 작업 정책이 검토를 강제하면 스위치는 켜진 상태로 고정됩니다.
• 가르친 스킬: 가르치기 모드에서 시연한 절차이며 스킬별 활성화/비활성화 스위치가 있습니다.

연결된 도구(MCP 및 OpenAPI 서버)

Work 에이전트는 채팅에 설정한 것과 같은 도구 서버를 호출할 수 있습니다. MCP든 OpenAPI든 관리자가 설정 → 도구에서 등록한 서버입니다. 도구는 네임스페이스가 붙은 이름(server__tool)으로 에이전트에게 제공되며, 호출은 샌드박스 안이 아니라 Libre WebUI 백엔드에서 강화된 도구 게이트웨이(SSRF를 막는 외부 통신, 사용자별 자격 증명, 크기 및 시간 상한)를 통해 실행됩니다.

자율 실행이 실제로 쓸 수 있는 것만 정직하게 제공합니다.

• 오프라인 작업에는 아무것도 제공하지 않습니다. 백엔드가 외부로 나갈 수 있든 없든, 네트워크 접근이 없는 작업은 오프라인으로 남습니다. web_search와 같은 이유입니다.
• 사용자가 저장하지 않은 개인 자격 증명을 요구하는 서버는 제공 시점에 걸러집니다. 자율 실행은 자격 증명을 묻기 위해 멈출 수 없기 때문입니다. 설정 → 도구에서 자격 증명을 추가하면 다음 실행부터 해당 서버가 제공됩니다.
• 도구 접근 모드(관리자 전용 또는 모든 사용자)와 서버별 노출 설정은 채팅과 똑같이 적용되며, 페르소나의 도구 서버 연결이 고용한 에이전트에게 보이는 서버 범위를 좁힙니다.
• 승인이 켜져 있으면, 서버가 부작용 있음으로 분류한 연결된 도구는 다른 통제 대상 작업과 마찬가지로 사용자의 판단을 기다리며 멈춥니다. 읽기 전용 도구는 묻지 않고 실행됩니다.

에이전트 간 위임(@ 멘션)

고용한 에이전트끼리 일을 넘길 수 있습니다. Work 작성기에서 @를 입력해 내 다른 에이전트를 멘션하면, 현재 에이전트는 지침에서 동료 목록(이름과 상태 줄)을 보고 해당하는 요청을 message_agent 도구로 위임합니다. 위임은 메시지를 통한 협업이며, 컴퓨터를 공유하지 않는 것은 의도된 설계입니다. 모든 에이전트는 자기만의 격리된 워크스페이스와 샌드박스를 유지하고, 위임받은 쪽은 위임한 대화를 볼 수 없으므로 요청 자체가 필요한 맥락을 담고 있어야 합니다.

위임은 비동기입니다. 도구는 즉시 반환되고, 대상 에이전트는 자신의 작업 안에서 실행되며(그 대화에는 보낸 쪽이 위임함으로 표시됩니다), 완료·입력 필요·실패·취소 중 무엇으로 끝나든 최종 응답이 위임한 에이전트의 대화로 그 에이전트의 보고라는 표시와 함께 전달됩니다. 위임한 쪽이 아직 실행 중이면 보고는 다음 라운드에서 모델에 전달되고, 유휴 상태라면 보고는 대화에 그대로 남아 기다립니다. 보고가 실행을 자동으로 시작하지는 않으므로 두 에이전트가 서로 주고받으며 무한히 오갈 수 없습니다. 위임된 실행은 다시 위임할 수 없고, 대상이 바쁘면 큐에 넣지 않고 시도가 정확히 실패하며, 승인이 켜져 있으면 message_agent도 다른 부작용 있는 작업과 마찬가지로 검토를 위해 멈춥니다(항상 허용 규칙은 그 하나의 대상 에이전트로만 한정됩니다).

작업 승인(자동 검토)

부작용이 있는 작업은 실행 전에 멈춰 사용자의 판단을 기다릴 수 있습니다. 작업에 승인이 켜져 있으면(Work 정책에서 부작용 있는 작업에 승인 필요를 설정했거나 에이전트의 자동 검토 스위치가 켜져 있으면), 실행은 run_command, computer_act, delete_file, move_file, message_agent을 실행하기 전에 멈추고 대화에 결정 카드를 표시합니다. 선택지는 이번만 허용, 항상 허용, 거부입니다.

• 이번만 허용은 이번 호출만 실행하고 다음에 다시 묻습니다.
• 항상 허용은 호출을 실행하고 작업에 규칙을 저장합니다. 파일 및 컴퓨터 작업은 도구 전체 범위이고, run_command는 명령의 프로그램 이름(첫 토큰) 범위입니다. npm run build를 승인하면 셸 전체가 아니라 이후의 npm 명령이 미리 승인됩니다. message_agent는 그 하나의 대상 에이전트로 한정됩니다. 규칙은 에이전트 탭의 자동 검토 섹션에 나열되며 거기서 지울 수 있습니다.
• 거부는 호출을 거절합니다. 모델에는 사용자가 그 작업을 거부했으며 그대로 다시 시도해서는 안 된다고 전달되고, 실행은 그 답을 받아 계속됩니다.

보류 중인 승인은 알림도 발생시킵니다(앱 내 알림, 사용 설정한 경우 웹 푸시). 게이트에 도달할 무렵이면 실행이 이미 몇 분째 무인으로 진행 중일 수 있기 때문입니다. 5분 안에 아무도 결정하지 않으면 요청이 만료되고 작업은 실행되지 않으며, 실행은 예산을 다 쓰지 않고 정상적인 인계와 함께 입력 필요로 끝납니다.

승인이 통제하는 것은 작업이지 가시성이 아닙니다. write_file과 읽기 전용 도구는 통제 대상이 아니며, 모든 결정은 보안 감사 로그에 남습니다.

작업 상태 이해하기

인터페이스는 영구 백엔드 상태를 더 간단한 사용자 상태에 매핑합니다.

인터페이스 상태	백엔드 상태	표시 색상
유휴	idle	rgb(255, 255, 255)
생각 중	preparing 또는 running	rgb(48, 121, 255)
완료	completed	rgb(76, 212, 117)
입력 필요	needs_input 또는 cancelled	rgb(255, 204, 0)
오류	failed	rgb(255, 61, 129)

활성 실행을 중지하면 입력 필요 상태가 되고 파일은 보존됩니다. 라운드 또는 도구 호출 안전 예산을 소진한 경우에도 도구 없는 최종 인계 후 입력 필요로 끝나므로 완료되지 않은 작업이 완료로 표시되지 않습니다.

활성 실행이 대화를 잠그지는 않습니다. 에이전트가 작업하는 동안 보낸 메시지는 대화에 즉시 들어가고 다음 라운드에서 모델에 전달됩니다. 실행을 중지하지 않고 방향을 조정하거나 수정하거나 컨텍스트를 추가할 수 있으며 보내기 옆의 중지 버튼도 계속 사용할 수 있습니다.

워크스페이스 크기 조절하기

xl 데스크톱 중단점에서 대화와 워크스페이스는 드래그 가능한 분할을 공유합니다.

• 기본 대화 너비는 45%입니다.
• 선호 범위는 최소 콘텐츠 너비를 고려한 30%~70%입니다.
• 저장된 비율은 해당 브라우저의 로그인 사용자별로 분리됩니다.
• 화살표 키는 구분선을 2%씩 이동하며 Shift를 누르면 10%씩 이동합니다.
• Home과 End는 사용 가능한 최솟값과 최댓값을 선택합니다.
• Enter 또는 두 번 클릭하면 분할이 초기화됩니다.

제어 기능은 현재 쓰기 방향을 따릅니다. 아랍어에서는 대화가 오른쪽, 워크스페이스가 왼쪽에 배치되며 포인터 및 화살표 키 크기 조절도 예상되는 시각적 방향으로 작동합니다.

작은 화면에서는 작업 헤더의 대화/워크스페이스 제어 기능으로 화면을 전환하세요.

파일

파일 탭은 /workspace의 바로 아래 항목을 탐색하고 엄격히 유효한 UTF-8 텍스트 파일만 열어 변경 사항을 작업 볼륨에 저장합니다. 잘못된 바이트 시퀀스는 손실을 일으키는 자리 표시 문자로 대체하지 않고 거부합니다.

편집기는 다음 기능을 제공합니다.

• 일반적인 웹, 시스템, 스크립팅, 데이터, 마크업 언어에 대한 라이트/다크 모드 구문 강조
• 저장 단축키 Cmd/Ctrl+S
• 지원되는 파일 서식 지정 단축키 Shift+Alt+F
• 오래된 편집기 보기가 파일을 연 뒤 변경된 내용을 조용히 덮어쓰지 못하도록 하는 낙관적 저장 충돌 감지
• 브라우저 세션 저장소의 작업 및 경로별 미저장 초안
• 미저장 편집이 열려 있을 때 탐색 경고

편집 반응성을 유지하기 위해 8,000자 또는 400줄을 넘으면 실시간 강조가 중지됩니다. JavaScript/JSX, TypeScript/TSX, JSON 변형, CSS/SCSS/Less, HTML, Markdown/MDX, YAML은 최대 100,000자 및 4,000줄까지 서식을 지정할 수 있습니다.

열어 둔 파일을 모델이 변경하면 파일 탭에서 턴 시작 이후 추가되고 제거된 내용을 정확히 보여 주는 빨강/초록 변경 보기로 열리며, 변경되지 않은 긴 구간은 접힙니다. 도구 모음 토글로 diff와 편집기 사이를 전환하고 +added −removed 카운터로 턴 변경 사항을 한눈에 요약합니다. 비교 기준은 턴 전에 브라우저가 마지막으로 본 콘텐츠이므로 턴 이후 처음 연 파일에는 diff가 표시되지 않습니다.

브라우저 초안은 편의를 위한 상태일 뿐 백업이 아닙니다. 저장 성공이나 작업 삭제 후 지워지고 일반적으로 브라우저 세션이 끝나면 사라집니다.

활동

활동 탭에는 도구 호출, 도구 결과, 파일 작업, 명령 출력과 오류가 표시됩니다. 대화에서 도구 메타데이터를 펼칠 수 있습니다. 주변 인터페이스가 오른쪽에서 왼쪽이더라도 명령 및 도구 출력은 왼쪽에서 오른쪽으로 표시됩니다.

실행이 활성화된 동안 Libre WebUI는 인증된 Server-Sent Event 스트림을 열고 백엔드에서 진행 상황을 받을 때마다 렌더링합니다. 스트림에는 다음이 포함될 수 있습니다.

• 초기 snapshot과 이후 run_state 변경
• 선택한 공급자가 추론을 명시적으로 공개할 때 reasoning_delta
• assistant_delta 텍스트
• tool_call 및 tool_result 활동
• usage 측정값
• 서버 제공 워커 안내를 위한 skill_loaded 알림
• 종료 error 또는 done 이벤트

추론의 가용성과 세분성은 모델 및 공급자에 따라 다릅니다. Libre WebUI는 공급자가 API를 통해 반환한 추론 콘텐츠만 표시합니다. 숨겨진 사고 과정을 복구할 수 없으며 일부 모델은 추론 스트림을 전혀 제공하지 않습니다. 추론과 별개로 지원되는 경우 어시스턴트 텍스트와 도구 활동은 계속 스트리밍됩니다.

출력은 의도적으로 제한됩니다. 잘린 결과는 명령이 더 이상 출력을 만들지 않았다는 증거가 아닙니다. 모델에 범위를 좁힌 결과를 검사하거나 더 집중된 명령을 실행하도록 요청하세요.

Git

Git 탭은 작업 자체의 /workspace에 다음 로컬 소스 제어 작업을 제공합니다.

• main 브랜치로 저장소 초기화
• porcelain 상태, 앞섬/뒤처짐 수와 최근 커밋 최대 20개 확인
• 변경된 경로의 크기가 제한된 텍스트 diff 확인
• 한 번에 명시적으로 선택한 경로 최대 200개 스테이징
• 로그인한 관리자의 사용자 이름 및 이메일로 스테이징된 변경 사항 커밋. 계정에 이메일이 없으면 인스턴스 로컬 no-reply 주소 사용
• 첫 커밋 후 로컬 브랜치 생성
• 워크트리가 깨끗할 때 기존 로컬 브랜치로 전환

이 화면은 의도적으로 로컬 전용입니다. clone, fetch, pull, push, 원격 관리, 임의 Git 명령, 토큰, SSH 키 또는 Pull Request 제어 기능이 없습니다. 이러한 작업에는 별도의 신뢰할 수 있는 자격 증명 브로커가 필요하며, 저장소 하나와 작업 하나로 범위가 지정된 GitHub App 또는 동등한 설치 토큰이 이상적입니다. 수명이 긴 Git 자격 증명을 /workspace, 작업 컨테이너 환경 또는 저장소 구성에 넣지 마세요.

Git 읽기는 작업이 유휴 또는 활성 상태여도 실행할 수 있습니다. 모델 실행, 대화형 터미널 또는 미리 보기가 작업 컨테이너를 소유하는 동안 Git 쓰기는 거부됩니다. 브랜치 전환에는 깨끗한 워크트리도 필요합니다. 이렇게 하면 UI가 같은 파일을 두고 모델 또는 장기 실행 프로세스와 경쟁하지 않습니다.

모든 UI Git 명령은 작업 컨테이너 안에서 UID/GID 1000:1000으로 실행되는 고정 인수 배열이며 사용자 입력을 셸에서 평가하지 않습니다. 런타임은 이 화면에 대해 시스템/전역 Git 구성, 프롬프트, 훅, 자격 증명 도우미, 커밋 서명, 서브모듈 재귀, 외부 diff 드라이버, textconv와 네트워크 프로토콜을 비활성화합니다. 워크트리가 정확히 /workspace가 아니거나 Git/common 디렉터리가 /workspace 밖으로 확인되는 저장소는 거부합니다. 실행 가능한 clean, smudge 또는 process 필터가 저장소 구성에 정의되어 있으면 파일 콘텐츠를 처리할 수 있는 Git 쓰기 작업도 차단됩니다.

이 제어 기능은 Libre WebUI Git API를 보호합니다. 관리자는 여전히 터미널을 사용할 수 있고 모델은 run_command를 사용해 샌드박스 안에서 일반 Git 명령을 실행할 수 있습니다. 따라서 샌드박스와 배포 경계가 임의 명령의 보안 제어로 유지됩니다.

기본 제공 워커 스킬

모든 실행은 서버 소유 워크스페이스 가이드를 받습니다. 이 가이드는 영구 /workspace 경계, 읽기 전용 컨테이너 루트, 임시 프로세스와 /tmp 상태, 네트워크 정책, 명령 및 출력 한도, 미리 보기 수명 주기를 설명합니다. 기본 제공 스킬은 모델에 다음을 지시합니다.

• 편집 전에 프로젝트 지침, 매니페스트, 잠금 파일, 스크립트와 현재 저장소 상태 검사
• 관련 없는 작업을 보존하고 독립적인 읽기 또는 검색을 일괄 처리
• 계획 후 멈추지 않고 구현까지 계속 진행
• 광범위한 검사 전에 집중된 검증 실행
• 무작정 재시도하지 않고 실패 원인 진단
• 최종 장기 실행 프로세스로 미리 보기를 시작하기 전에 애플리케이션 검증

가이드는 모델 컨텍스트에만 존재합니다. Libre WebUI는 사용자의 워크스페이스에 AGENTS.md, 스킬 디렉터리 또는 다른 제어 파일을 만들지 않습니다. 프로젝트에서 제공하는 지침은 프로젝트 지침으로 유지되며 컨테이너 또는 도구 보안 경계를 재정의할 수 없습니다.

터미널

터미널 탭은 모델이 작업하는 동일한 샌드박스 컨테이너에 대화형 셸을 연결하므로 관리자가 브라우저를 벗어나지 않고 상태를 검사하거나 빌드를 직접 실행하거나 실행 후 남은 내용을 디버그할 수 있습니다.

셸에는 모든 모델 도구와 동일한 컨테이너 정책이 적용됩니다. 권한 없는 1000:1000 사용자로, 작업 디렉터리 /workspace에서, 이미 강화되고 기능이 제거된 컨테이너 안에서 실행됩니다. 터미널은 모델의 run_command 도구에 없는 권한을 부여하지 않습니다. 같은 경계를 사람이 사용하기 위한 인터페이스이지 우회 수단이 아닙니다.

운영 동작은 다음과 같습니다.

• 인증 — 브라우저는 일반 Authorization 헤더를 HTTP를 통해 Work 터미널 프로토콜 및 정확한 작업에 바인딩된 수명이 짧은 일회용 티켓으로 교환합니다. /ws/work-terminal 업그레이드 URL에는 해당 티켓과 작업 ID만 나타납니다. Libre는 셸 입력마다 현재 계정 상태, Work 접근 권한, 작업 존재 여부와 소유권을 다시 확인합니다. 권한을 취소하면 셸이 닫히고 런타임 임대가 즉시 해제됩니다.
• 출처 검사 — CORS_ORIGIN 또는 BASE_URL이 구성되어 있으면 브라우저 업그레이드가 해당 출처 중 하나와 일치해야 합니다. 원격 배포에서는 적어도 하나를 구성하세요. 출처 없는 업그레이드는 Electron 및 비브라우저 클라이언트를 위해 계속 허용되지만 동일한 작업 바인딩 티켓과 실시간 권한 확인이 필요합니다. TLS, 방화벽과 역방향 프록시 정책으로 이러한 클라이언트를 제어하세요.
• 허용 — 열린 터미널은 명령 또는 미리 보기와 똑같이 런타임 임대를 사용하며 WORK_MAX_ACTIVE_RUNTIMES_*에 포함됩니다.
• 컨테이너 수명 — 연결된 터미널은 컨테이너를 계속 실행하고 유휴 중지 경로가 세션 중간에 제거하지 못하게 합니다.
• 동시성 — WORK_TERMINAL_MAX_SESSIONS_PER_TASK(기본값 2)는 작업별 동시 셸 수를 제한합니다.
• 유휴 시간 초과 — WORK_TERMINAL_IDLE_TIMEOUT_MS(기본값 15분)는 입력이 없는 세션을 닫고 임대를 해제합니다.
• 실행이 활성화된 동안 — 탭은 모델이 컨테이너를 소유하고 있으며 턴이 끝나면 셸이 열린다고 설명합니다.

TTY 세션에는 Docker CLI가 실제 제어 터미널에만 제공하는 하이재킹된 양방향 스트림이 필요하므로 터미널은 Docker Engine API를 직접 사용합니다. WORK_DOCKER_SOCKET을 우선하고, 그렇지 않으면 DOCKER_HOST를 사용합니다. 이는 unix:// 소켓 또는 소켓 프록시 같은 일반 HTTP tcp:// 엔드포인트일 수 있으며, HTTP 인식 전달은 표준 Connection: Upgrade 터널을 통해 하이재킹된 스트림을 운반합니다. 둘 다 없으면 /var/run/docker.sock을 사용합니다. 이 클라이언트가 사용할 수 없는 DOCKER_HOST(ssh:// 또는 DOCKER_TLS_VERIFY가 설정된 tcp://)에서는 다른 곳에 조용히 연결하지 않고 이유와 함께 터미널을 사용할 수 없음으로 보고합니다. Work의 나머지 부분은 계속 작동합니다. Kubernetes 백엔드에서는 같은 세션이 API 서버를 통한 TTY WebSocket으로 exec 하위 리소스를 사용하며 크기 조절 프레임도 포함되고 Docker 엔드포인트는 관여하지 않습니다.

터미널 세션은 대화형이며 기록되지 않습니다. 여기에 입력한 명령은 작업의 활동 타임라인에 나타나지 않습니다.

미리 보기

미리 보기 탭은 생성된 웹 애플리케이션을 시작, 중지, 삽입하고 새 창에서 엽니다. 명령 필드가 비어 있으면 Libre WebUI가 워크스페이스를 검사해 다음을 수행합니다.

• 루트 package.json의 dev 스크립트를 필요한 호스트와 포트로 실행
• 번들된 무의존성 정적 서버로 루트 index.html 제공
• 중첩 디렉터리의 단일 앱에 동일한 규칙 적용

루트 애플리케이션이 우선합니다. 동일하게 가능성이 높은 중첩 앱이 여러 개 있거나 지원되는 진입점이 없으면 Work는 관련 없는 npm 명령을 시도하지 않고 해결 방법이 포함된 오류를 반환합니다. 다른 프로젝트 레이아웃이나 서버에서는 미리 보기 시작을 선택하기 전에 사용자 지정 명령을 입력하세요. 사용자 지정 명령은 /workspace에서 시작하므로 필요하면 상대 디렉터리를 포함합니다. 예: cd apps/web && npm run dev -- --host 0.0.0.0 --port 4173. 사용자 지정 프로세스는 0.0.0.0과 구성된 WORK_PREVIEW_PORT에서 수신해야 합니다. Work는 포트가 준비될 때까지 최대 15초 기다립니다.

모델도 start_preview 도구를 통해 미리 보기를 시작할 수 있습니다. 모델이 프로세스를 계속 실행할 수 있는 유일하게 지원되는 방법입니다. 일반 run_command 호출은 명령이 끝날 때 백그라운드 하위 프로세스를 정리합니다.

화면(Work Computer)

전체 시연 보기: Work 에이전트가 자체 화면에서 NASA 이미지 갤러리를 탐색하고 사진을 고른 다음 대화형 Three.js 갤러리를 만들고 테스트하는 실제 무편집 실행(30배속 후 실시간)입니다. 이 모든 작업이 프롬프트 하나로 이루어집니다.

정책에서 Work Computer를 활성화한 작업에는 화면 탭이 추가됩니다. 같은 샌드박스 안에서 실행되는 가상 데스크톱, 즉 창 관리자, Dock과 1280×800 디스플레이의 Chromium 브라우저를 실시간으로 보여 주는 창입니다. 에이전트가 작업하는 모습을 보고, 마우스와 키보드를 직접 조작하고, 컴퓨터 오디오를 들으며 시연으로 작업을 가르칠 수 있습니다. 탭을 열면 필요할 때 GUI 세션을 시작하고(누군가 보기 전에는 아무것도 실행되지 않음) VNC-over-WebSocket 뷰어를 연결합니다.

관리자는 클릭 한 번으로 활성화할 수 있습니다. Work 시작 페이지의 Work Computer 카드에서 활성화 버튼을 누르면 배포 자체 Docker 데몬에서 번들 GUI 이미지를 빌드하고(첫 빌드는 몇 분 걸림) 바로 사용할 수 있는 Work Computer 정책을 만듭니다. 수동 docker build나 정책 필드는 필요하지 않습니다. 필터링된 Docker API 프록시에서는 빌드 엔드포인트가 의도적으로 거부됩니다. 대신 Docker 호스트에서 게시된 이미지(ghcr.io/libre-webui/libre-work-computer, libre-work-computer:latest 태그)를 가져오거나 deploy/work-computer/에서 빌드하세요. 그러면 활성화가 빌드를 건너뛰고 정책만 만듭니다. 이 정책의 작업에는 네트워크 접근이 필요합니다. 화면은 미리 보기와 똑같이 루프백에 게시된 컨테이너 포트를 통해 연결됩니다.

보안 모델: 컨테이너 내부 VNC 서버는 세션별 비밀번호 두 개 뒤의 localhost에 바인딩됩니다. 보기 전용 비밀번호는 승인된 모든 관찰자에게 제공되고 전체 제어 비밀번호는 현재 직접 조작 임대 보유자에게만 제공되므로, VNC 서버 자체가 다른 모든 사용자의 입력을 무효화합니다. WebSocket 브리지가 유일하게 접근 가능한 표면이며 Docker 호스트 루프백에 게시되고 직접 공개되지 않습니다. 모든 뷰어는 터미널과 같은 메커니즘으로 세션 및 작업에 바인딩된 일회용 티켓을 사용해 인증합니다. 연결할 때마다 현재 Work 접근 권한을 다시 확인하므로 사용자 권한을 취소하면 화면 연결도 즉시 끊깁니다. 화면 하나를 동시에 최대 네 명이 볼 수 있으며 관찰도 유휴 정리에서 작업 활동으로 계산됩니다. 관찰과 실행은 서로 경쟁하지 않습니다. 에이전트 실행 중 화면을 열면 해당 실행의 샌드박스에 연결되고, 누군가 화면을 보고 있어도 다음 실행을 시작할 수 있으며, 실행이 끝난 뒤에도 세션이 유지됩니다. 실행이 별도 워커 프로세스에서 이루어지는 팀 배포에서도 마찬가지입니다. 브라우저 프로필은 /workspace/.browser-profile에 유지되므로 컴퓨터 내부 로그인은 컨테이너 재시작 후에도 남습니다.

에이전트 제어: Work Computer가 있는 작업은 모델에 추가 도구 두 개를 제공합니다. computer_observe는 데스크톱 전체 스크린샷과 함께 커서 위치, 활성 창 ID, 현재 브라우저 URL, 페이지와 브라우저 자체 UI 중 어느 쪽이 키보드 포커스를 갖는지, 포커스된 요소의 간략한 설명과 스크린샷 해시를 반환합니다. 의미 신호는 컨테이너 루프백에 바인딩된 DevTools 엔드포인트에서 가져오며 이 기능이 생기기 전에 빌드된 GUI 이미지에서는 제공되지 않습니다. computer_act는 마우스와 키보드 작업(이동, 클릭, 두 번 클릭, 오른쪽 클릭, 입력, 키 조합, 스크롤, 대기)을 최대 24개 일괄 실행하고 안정된 뒤 스크린샷을 반환합니다. 세 가지 런타임 보호 기능이 일괄 작업의 정확성을 유지합니다. type/key 작업에는 focus 어설션을 넣을 수 있고 지정한 필드가 키보드 포커스를 갖지 않으면 닫힌 상태로 실패하므로 텍스트가 주소 표시줄에 조용히 입력되지 않습니다. 일괄 작업 도중 창이 나타나거나 제목이 바뀌거나 포커스가 이동하면 이후 좌표가 이전 화면을 대상으로 하므로 조기에 중지합니다. 또한 예상 결과(제목, URL 또는 변경된 화면 영역)를 선언할 수 있으며 런타임이 적응형 제한 시간으로 이를 검증합니다. "대기 중"은 아직 관찰되지 않았다는 뜻이며 성공으로 가정하지 않습니다. 일괄 작업 후 고정 지연 대신 화면 변화가 멈출 때까지 폴링해 적응형으로 안정화합니다. 모든 결과에는 모델이 읽도록 지시받은 증거도 포함됩니다. 명시적 좌표 클릭은 클릭 주변 픽셀의 변경 여부를 알리는 영수증을 반환하고, scroll_until은 대상 텍스트 또는 페이지 끝을 향해 스크롤한 뒤 표시 여부를 보고하며, 각 관찰은 이전 관찰과 비교되어 화면이 변하지 않았으면 이를 명시합니다. 일괄 작업은 한 줄 subgoal을 선언할 수 있으며 이 값은 결과와 함께 체크포인트로 유지되고 복구 프롬프트에 다시 표시됩니다. 에이전트 루프는 접지 정체를 감지합니다. 변하지 않은 화면에 같은 작업을 세 번 수행하면 복구 알림을 한 번 보내고, 반복되면 남은 라운드를 소모하지 않고 입력을 요청하며 실행을 끝냅니다. 연속으로 검증되지 않은 예상이 발생하는 복합 모호성도 감지해 재접지 알림을 한 번 보냅니다. 라운드, 도구 지연 시간, 스크린샷, 보호 장치, 예상 판정 같은 루프 원격 측정은 저장된 모든 도구 레코드에 기록되고 실행 종료 시 요약됩니다.

스크린샷은 Ollama, Anthropic, Gemini, OpenAI 호환 채팅 및 Responses 플러그인 등 모든 공급자 경로에서 실제 이미지 콘텐츠로 모델에 전달됩니다. 따라서 작업을 제어하는 모델은 비전 모델이어야 합니다. 공급자가 이미지 입력을 거부하는 텍스트 전용 모델이어도 실행이 실패하지는 않습니다. 나머지 실행에서 스크린샷을 제외하고 모델에 텍스트 관찰에 의존하라고 알리며 대본에 성능 저하 설명을 남깁니다. 하지만 화면을 볼 수 없는 모델은 검증 능력이 훨씬 떨어지므로 컴퓨터 작업에는 비전 모델을 우선하세요. 모델의 실시간 컨텍스트에는 가장 최근 스크린샷만 남고 저장된 작업 대본에는 텍스트 관찰만 보관되며 이미지 바이트는 절대 저장되지 않습니다. 브라우저에는 콘텐츠 차단 기능이 기본 제공됩니다. 광고 및 추적기 차단을 위한 uBlock Origin Lite는 이미지 빌드 시 버전을 고정하고 체크섬을 검증하며 관리형 정책으로 필터링 모드를 고정합니다. 쿠키 동의 배너 자동 닫기 기능도 포함됩니다. 광고와 동의 화면은 에이전트의 스크린샷, 토큰, 클릭을 낭비하기 때문입니다. 광고 요청은 uBlock 방식으로 무력화되어 알려진 광고 스크립트가 무해한 로컬 스텁으로 확인되므로 페이지가 계속 작동합니다. 에이전트는 자격 증명을 입력하거나 CAPTCHA/2FA 문제를 해결하지 말고 차단 요소를 보고하도록 지시됩니다. 신뢰할 수 없는 작업에는 GUI 정책과 필터링 DNS 확인자를 함께 사용하세요. 데스크톱 브라우저가 있으면 네트워크 외부 통신 정책의 중요성이 줄어드는 것이 아니라 더 커집니다.

오디오: 화면은 기본적으로 음소거되어 있습니다. 이는 오디오 재생에 클릭이 필요한 브라우저 규칙 때문입니다. 화면 창의 스피커 버튼은 컴퓨터 사운드를 실시간으로 스트리밍합니다. 샌드박스 안에서 PulseAudio는 null sink로 재생하고 해당 모니터를 원시 PCM으로 캡처해 인증된 두 번째 루프백 게시 WebSocket 브리지로 제공합니다. 화면과 같은 티켓, 접근 재확인과 작업별 뷰어 한도가 적용됩니다. 이 버전 이상의 deploy/work-computer/에서 빌드한 GUI 이미지가 필요합니다.

직접 조작: 화면 창의 직접 조작 버튼을 누르면 로그인, CAPTCHA 처리 또는 에이전트가 수행해서는 안 되는 단계에서 마우스와 키보드를 사용할 수 있습니다. 완료를 누르면 화면을 에이전트에 돌려줍니다. 하나의 VNC 세션이 두 역할을 제공합니다. 컨테이너 내부 서버는 세션별로 생성되고 절대 기록되지 않는 전체 제어 및 보기 전용 비밀번호를 보유하고, 관찰자는 보기 전용 비밀번호만 받으며 제어 임대의 현재 보유자만 제어 비밀번호를 받습니다. 임대에는 TTL 한도가 있어 방치된 직접 조작은 2분 안에 만료되고, 직접 조작 UI가 열려 있는 동안 갱신되며 협력식이어서 다른 사용자에게서 빼앗을 수 없습니다. 정책 편집기의 화면 직접 조작 허용으로 직접 조작을 완전히 비활성화할 수 있습니다. 해당 정책 작업은 직접 조작과 가르치기 제어를 숨기고 직접 조작 엔드포인트는 요청을 거부하며, 에이전트의 request_takeover는 누구에게도 제어권을 넘길 수 없다고 보고합니다. 화면 관찰은 계속 사용할 수 있습니다. 사람이 제어하는 동안 에이전트의 computer_observe와 computer_act는 모두 차단되므로 에이전트가 사용자 입력과 경쟁하거나 입력하는 내용을 스크린샷으로 찍을 수 없습니다. 에이전트도 직접 조작을 요청할 수 있습니다. request_takeover 도구는 이유와 함께 화면 창에 배너를 표시하고 사용자가 직접 조작한 뒤 돌려줄 때까지 기다립니다. 직접 조작 중 입력한 자격 증명은 키보드에서 페이지로 바로 전달되며 모델이나 작업 대본을 절대 통과하지 않습니다. 직접 조작에는 이 버전 이상의 deploy/work-computer/에서 빌드한 GUI 이미지가 필요합니다. 이전 이미지의 세션은 계속 볼 수 있지만 모든 사용자에게 보기 전용입니다.

가르치기 모드: 화면 창에서 작업 가르치기를 선택하면 시연을 기록합니다. 눈에 보이는 녹화 표시와 함께 직접 조작처럼 실제 화면을 제어하며 포인터, 키보드, 스크롤 작업을 화면 좌표로 캡처합니다. 클릭마다 앵커도 지정됩니다. 읽기 전용 프로브가 포인터 아래 대화형 요소의 태그, ID, 표시 레이블과 현재 페이지 URL을 확인해 플레이북 단계에 대상을 기록합니다. 예를 들면 "button#submit (Place order) 클릭"처럼 표시되며 좌표는 시연 당시 제어 기능의 위치에 대한 보조 정보가 됩니다. 저장하면 모델을 전혀 사용하지 않고 결정적으로 플레이북을 만듭니다. 키 입력은 입력 문자열로 묶이고, 클릭과 드래그는 8픽셀 임계값으로 구분되며, 일시 중지는 명시적 대기 단계가 됩니다. 비밀 관련 어휘를 언급하거나 자격 증명 형태(8자 이상이며 세 가지 문자 클래스 혼합)인 입력 텍스트는 가려지고 해당 단계에서 request_takeover를 사용하라는 지침으로 대체됩니다. 플레이북은 자연어 절차입니다. 앵커 대상이 먼저 나오고 좌표는 힌트로 사용되며 computer_observe로 다시 해석됩니다. 사용 시점, 입력, 단계, 검증, 시연에서 실제 방문한 호스트로부터 생성된 허용 범위도 포함합니다. 재생은 이 범위를 벗어나기 전에 멈추고 물어봐야 하므로 가르친 절차가 시연된 범위 이상의 권한을 물려받지 않습니다. 승인 경계와 실패 시 중지 후 질문 처리도 포함됩니다. 일반 스킬로 저장되며 슬러그 접두사는 taught-입니다. 따라서 스킬 페이지에서 버전 관리, 편집, 공유를 할 수 있습니다. 컴퓨터가 활성화된 Work 실행은 소유자의 활성 가르친 스킬을 시스템 프롬프트에 불러오고 실행 스킬 목록에 보고합니다. 가르친 작업을 재생하는 것은 요청과 절차가 일치하는 일반 실행입니다. 실행이 끝나면 스킬 칩에서 한 번 클릭으로 성공/실패 검토를 남길 수 있습니다. 이 검토는 스킬의 추적 기록 섹션에 날짜가 있는 줄을 추가하며 최신 항목이 먼저 오고 개수가 제한되며 각 항목은 일반 스킬 버전이 됩니다. 절차 기록이 절차와 함께 유지됩니다. 녹화 중 실제 비밀번호를 입력하지 마세요. 로그인 직전까지 시연하고 저장한 뒤 재생할 때 request_takeover로 자격 증명을 처리하세요.

공급자, 라우팅, 데이터 공개

지원되는 공급자 경로

경로	검증과 동작
로컬 Ollama	Ollama가 정상 상태여야 하며 정확한 모델이 도구 지원을 명시해야 합니다.
Ollama Cloud	Ollama를 통해 명시적으로 라우팅되며 클라우드 접미사 모델에는 원격 공급자 정보 공개가 표시됩니다.
완성/채팅 플러그인	플러그인이 활성 상태이고 정확한 모델을 나열하며 현재 관리자 자격 증명이 있어야 합니다.
Anthropic 플러그인	Work의 Anthropic messages 및 tool-use 어댑터를 사용합니다.
Gemini 플러그인	Work의 Gemini contents 및 function-calling 어댑터를 사용합니다.
기타 호환 플러그인	OpenAI 형식 messages, tools, tool-choice 요청 형식을 사용합니다.

공급자 유형과 플러그인 ID는 작업과 각 실행 모두에 저장됩니다. 모델 이름만으로 경로를 선택하지 않습니다. Ollama 모델과 이름이 같은 플러그인을 활성화해도 기존 작업을 가로챌 수 없습니다.

공급자가 받는 정보

각 모델 라운드에서 선택한 공급자는 다음 정보를 받을 수 있습니다.

• Work 시스템 프롬프트
• 기본 제공 워커 스킬과 현재 런타임 한도
• 최대 256 KB로 제한된 최근 사용자/어시스턴트 대화 메시지 최대 30개
• Work 도구 정의
• 어시스턴트 도구 호출 기록
• 디렉터리 목록, 요청한 파일 내용, 검색 결과, 명령 출력과 오류가 포함될 수 있는 도구 결과

명명 볼륨 전체가 업로드되지는 않습니다. 하지만 도구를 통해 반환된 모든 파일 콘텐츠 또는 명령 출력은 모델 대화의 일부가 되어 선택한 공급자에 전송됩니다. 민감한 소스 코드를 사용하기 전에 원격 공급자의 보존, 학습, 요금, 사용 정책을 검토하세요.

공급자 자격 증명은 배포 전체 또는 개별 사용자용으로 구성되었는지와 관계없이 Libre WebUI 백엔드에 남습니다. 백엔드 모델 요청에 사용되며 Work 컨테이너에 절대 마운트되지 않습니다.

애플리케이션 계층 자격 증명 암호화는 작업 전체 암호화가 아닙니다. Work 대화, 도구 결과, 명령 출력과 작업 메타데이터는 일반 데이터베이스 콘텐츠이며, 워크스페이스 파일과 의존성은 작업 Docker 볼륨 또는 Kubernetes PVC의 일반 파일입니다. 배포 위협 모델에서 저장 데이터 암호화가 필요하면 호스트 접근 제어와 디스크 암호화를 사용하세요.

원격 공급자 정보 공개

Work는 정보 공개를 위해 플러그인 모델과 이름이 :cloud 또는 -cloud로 끝나는 Ollama 모델을 원격으로 취급합니다. 이를 선택하면 공급자 데이터 흐름과 여러 번 과금될 수 있음을 설명하는 닫을 수 있는 알림이 열립니다. 닫기 환경 설정은 Libre WebUI 사용자별로 기억됩니다.

모든 공급자 경로는 기본값 48라운드인 동일한 WORK_MAX_AGENT_ROUNDS 예산을 사용합니다. 별도의 플러그인 12라운드 제한은 없습니다. 도구 호출 안전 예산은 128회 또는 구성된 라운드당 8회 중 큰 값입니다. 라운드 예산을 소진하면 Libre WebUI는 모델에 완료한 작업, 검사, 차단 요소, 남은 단계를 설명하는 도구 없는 최종 인계를 한 번 요청합니다. 그런 다음 원시 라운드 한도 예외를 노출하거나 미완료 작업을 완료로 표시하지 않고 실행을 입력 필요로 기록합니다. 후속 실행은 같은 영구 워크스페이스에서 계속됩니다. Work 실행 하나에서도 과금되는 공급자 요청이 많이 발생할 수 있습니다.

호스트 폴더 워크스페이스(선택 기능)

Docker 백엔드에서 작업의 /workspace는 일반적으로 해당 작업에만 존재하는 명명 볼륨이므로 모델이 실제 파일에 접근할 수 없습니다. Docker 배포에서는 작업을 호스트의 실제 폴더에 바인딩하도록 허용할 수 있습니다. Kubernetes는 호스트 폴더 워크스페이스를 거부하고 작업 소유 PVC를 사용합니다.

두 변수를 모두 설정한 뒤 백엔드를 다시 시작합니다.

WORK_HOST_WORKSPACES_ENABLED=true
WORK_HOST_WORKSPACE_ROOTS=/Users/you/Projects

WORK_HOST_WORKSPACE_ROOTS는 :로 구분된 루트 목록이며 기본값은 서버 사용자의 홈 디렉터리입니다. 기능을 켜면 Work 시작 화면에 선택적 워크스페이스 폴더 필드가 추가됩니다. 비워 두면 이전과 똑같이 자체 격리 볼륨을 사용합니다.

경로를 허용하기 전에 절대 경로이고, 존재하며, 디렉터리이고, 모든 심볼릭 링크를 확인했을 때 구성된 루트 중 하나 안의 위치인지 검사합니다. .ssh, .gnupg, .aws, .config, .kube, .docker, .claude, .libre-webui, node_modules라는 이름의 디렉터리는 무조건 거부합니다. 확인된 경로는 작업과 함께 저장되고 작업 헤더에 표시되므로 작업이 어느 폴더를 대상으로 하는지 항상 확인할 수 있습니다.

샌드박스 범위가 좁아집니다

호스트 워크스페이스를 사용하면 모델이 실제 파일을 읽고 쓰며, 컨테이너의 다른 보호 기능(비-root 사용자, 제거된 기능, 리소스 한도)이 해당 디렉터리와 모델 사이의 보호막이 되지 못합니다. 필요한 경우에만 기능을 활성화하고, 루트 범위를 가능한 한 좁게 유지하며, 버전 관리되는 디렉터리를 우선하세요.

영구 저장과 런타임 수명 주기

Libre WebUI는 영구 상태와 실행 상태를 분리합니다.

상태	저장소	수명
작업 소유권, 제목, 공급자, 상태	Libre WebUI 데이터베이스	작업 또는 소유 사용자가 삭제될 때까지
실행, 오류, 메시지, 도구 활동	Libre WebUI 데이터베이스	작업이 삭제될 때까지
워크스페이스 파일	작업별 Docker 볼륨 또는 K8s PVC	실행 취소, 미리 보기 중지, 샌드박스 재시작, 앱 재시작 후에도 유지
루트 파일 시스템과 임시 파일	작업별 컨테이너 또는 Pod	일회용이며 중지하거나 다시 만들 수 있음
미리 보기 프로세스	실행 중인 작업 샌드박스	일시적이며 정상 상태가 검증된 동안만 유지
저장하지 않은 편집기 초안	브라우저 세션 저장소	브라우저 세션 동안만 유지되는 임시 편의 상태

모든 작업에는 서버에서 생성한 UUID가 부여됩니다. 샌드박스와 워크스페이스 이름은 백엔드에서 파생하며 브라우저 요청에서 절대 받지 않습니다. Libre WebUI는 관리 및 작업 소유권 레이블을 지정해 런타임 리소스를 만듭니다. 재사용 또는 삭제하기 전에 작업 소유권 레이블을 검증하고 다른 작업 소유로 표시된 리소스를 거부합니다.

샌드박스는 필요할 때 준비합니다. 파일 도우미 작업은 그 외에는 유휴 상태인 샌드박스를 중지하고, 명령은 완료 후 샌드박스를 중지하며, 검증된 미리 보기는 사용자가 앱을 살펴볼 수 있도록 계속 실행할 수 있습니다. 같은 작업 샌드박스를 재시작하거나 다시 만들면 영구 워크스페이스가 다시 마운트됩니다.

관리자는 설정의 사용자 관리 탭에서 명명 런타임 정책을 정의할 수 있습니다. 런타임 이미지, 메모리/CPU/PID 한도, 워크스페이스 크기(Kubernetes), 유휴 제한 시간, 네트워크 기본값과 두 가지 기능 스위치를 조합한 프리셋입니다. **Work Computer(GUI + 브라우저)**는 해당 정책 작업에 가상 데스크톱과 화면 탭을 제공하고, 화면 직접 조작 허용은 사용자가 화면을 직접 조작할 수 있는지, 그리고 가르치기가 직접 조작을 통해 기록되므로 가르치기 모드를 사용할 수 있는지 결정합니다. 정책으로 만든 작업은 해당 구성으로 실행됩니다. 정책에서 비워 둔 필드는 배포 전역 값을 상속하고 정책을 삭제하면 다음 컨테이너 재생성 시 해당 작업이 전역 값으로 돌아갑니다. 정책은 리소스와 이 기능 스위치만 조정합니다. 강화 프로필(비-root, 읽기 전용 rootfs, 제거된 기능, 네트워크 격리)은 정책 필드가 아니며 정책별로 약화할 수 없습니다.

WORK_RUNTIME_IDLE_TIMEOUT_MS는 미리 보기 유예 시간을 제한합니다. 설정하면 정리 작업이 지정한 시간 동안 명령 완료, 터미널 연결 또는 서명된 프록시를 통한 미리 보기 요청 등 아무 활동도 없는 샌드박스를 중지해 허용 슬롯을 해제합니다. 중지는 비용이 적고 워크스페이스는 유지되므로 유휴 중지된 미리 보기는 다음 사용 시 다시 시작됩니다. 기본값(0)은 현재 동작을 유지하며 명시적으로 중지할 때까지 미리 보기가 실행됩니다.

백엔드가 시작되면 활성 실행은 실패로 표시되고 미리 보기 상태가 지워집니다. 에이전트 루프와 미리 보기 프록시가 프로세스와 함께 종료되어 재개할 수 없기 때문입니다. 이후 선택한 드라이버가 관리 컨테이너 또는 Pod를 레이블이 지정된 쿼리 하나로 나열합니다. 알려진 작업이 소유한 실행 중 샌드박스는 감독자 없이 중단된 명령이 계속 실행될 수 있으므로 중지합니다. 이미 멈춘 샌드박스는 그대로 두며, 작업 행이 더 이상 없는 관리 샌드박스는 제거합니다. 소유권은 리소스 이름이 아니라 작업 레이블에서 가져옵니다. 고아 리소스 제거는 하나의 Libre WebUI 인스턴스가 하나의 런타임 네임스페이스 또는 Docker 데몬을 소유한다고 가정합니다. 두 인스턴스가 같은 Work 리소스를 사용하도록 지정하지 마세요. 드라이버가 정리를 증명할 수 없으면 Work는 닫힌 상태로 실패하고 10초마다 재시도하며 런타임 접근이 복구될 때까지 새 변경 작업을 차단합니다.

네트워크 동작

선택한 네트워크 정책을 검증하세요

명명 런타임 정책이 없는 작업은 네트워크가 활성화된 상태로 시작합니다. 관리자는 네트워크 기본값이 꺼진 명명 정책을 정의할 수 있고 생성자는 작업을 만들 때 이를 선택할 수 있습니다. 독립적인 작업별 네트워크 스위치는 없으며 나중에 정책을 바꾸면 새 런타임 구성을 적용하기 전에 샌드박스를 다시 만들어야 합니다.

Docker 백엔드에서 네트워크 작업은 컨테이너 간 통신이 비활성화된(com.docker.network.bridge.enable_icc=false) 전용 관리 브리지 네트워크(기본값 libre-webui-work, WORK_NETWORK_NAME)에 연결됩니다. 이에 따라 다음 두 가지가 적용됩니다.

• 한 Work 샌드박스는 다른 Work 샌드박스에 연결할 수 없습니다.
• Work 샌드박스는 의도적으로 공개하지 않은 같은 위치의 데이터베이스 또는 Ollama 컨테이너를 포함해 Docker의 공유 기본 브리지에 있는 배포 자체 컨테이너에 접근할 수 없습니다.

구성한 이름의 네트워크가 이미 있지만 관리 네트워크가 아니면 Libre WebUI는 샌드박스를 운영자 네트워크에 조용히 연결하지 않고 네트워크 작업 시작을 거부합니다.

Kubernetes에서는 샌드박스 Pod에 동일한 네트워크 활성 레이블이 지정됩니다. Helm 차트는 기본 거부 NetworkPolicy, 미리 보기 전용 인바운드와 네트워크 활성 Pod에만 적용되는 인터넷 외부 통신을 설치하며 구성된 work.networkPolicy.blockedEgressCidrs는 제외합니다. NetworkPolicy는 클러스터 CNI가 적용할 때만 유효합니다. Kubernetes 가이드를 참조하세요.

패키지 다운로드, 원격 Git 작업, 외부 API는 Work를 유용하게 만드는 기능이므로 외부 네트워크 통신은 계속 허용됩니다. 이는 외부 방화벽이 아닙니다. 생성된 코드는 배포 방식에 따라 다음 대상에 여전히 접근할 수 있습니다.

• Docker 호스트의 서비스
• 호스트 로컬 네트워크의 시스템
• 인터넷 서비스
• 인프라 메타데이터 엔드포인트

외부 통신 정책 훅

더 엄격한 경계가 필요하면 다음을 함께 사용하세요.

• WORK_RUNTIME_DNS(Docker) — 네트워크가 활성화된 모든 샌드박스에 강제로 적용하는(--dns) 쉼표로 구분된 IPv4/IPv6 확인자 주소입니다. 필터링 확인자를 지정하면 Libre WebUI를 패치하지 않고 이름 기반 허용/거부 목록을 사용할 수 있습니다. 주소가 아닌 항목은 거부되고 기록되므로 값에 추가 Docker 플래그를 삽입할 수 없습니다.
• 호스트 또는 업스트림 방화벽 규칙(Docker) — 이름이 지정되고 관리되는 브리지이므로 서브넷이 안정적입니다.
• WORK_NETWORK_NAME(Docker) — 자체 드라이버 옵션으로 미리 만든 네트워크를 지정합니다. Libre WebUI가 관리 레이블과 ICC 비활성화 옵션을 확인하므로 둘 다 포함해 만드세요.

DNS 필터링은 이름 확인을 제한할 뿐 원시 IP 외부 통신을 제한하지 않습니다. 직접 IP 통신을 확실히 금지해야 하는 배포에는 호스트, 클러스터 또는 업스트림 수준 방화벽 규칙도 필요합니다.

코드를 Work에 넣으면 데이터 전송이 방지된다고 가정하지 마세요. Work 접근 권한은 신뢰할 수 있는 사용자에게만 부여하세요. 작업을 오프라인으로 시작해야 한다면 네트워크가 비활성화된 명명 런타임 정책을 사용하세요. 기본 정책을 변경하는 배포 전체 환경 변수는 없습니다.

네트워크 접근이 자격 증명을 추가하지는 않습니다. Libre WebUI는 SSH 키, 클라우드 자격 증명, 브라우저 프로필, 호스트 홈 디렉터리 또는 Docker 소켓을 작업 컨테이너에 마운트하지 않습니다. 그래도 사용자나 모델이 /workspace에 쓴 모든 자격 증명 또는 비밀 값은 코드가 전송할 수 있습니다.

이 샌드박스 트래픽은 모델 트래픽과 별개입니다. Ollama 및 플러그인 요청은 항상 Libre WebUI 백엔드가 명시적으로 선택한 공급자 경로로 보냅니다.

샌드박스 보안 경계

Docker Work 컨테이너에는 다음 정책이 적용됩니다.

• 비-root UID/GID 1000:1000으로 실행
• /workspace를 작업 디렉터리로 사용
• 선택한 작업의 명명 볼륨만 /workspace에 마운트
• 읽기 전용 루트 파일 시스템과 크기가 제한된 /tmp 임시 파일 시스템 사용
• 모든 Linux 기능 제거
• no-new-privileges 활성화
• 비특권 모드와 init 프로세스 사용
• CPU, 메모리, 프로세스, 명령 시간, 출력 한도 적용
• swap을 메모리 한도에 고정(--memory-swap과 --memory가 같음)해 swap으로 메모리 한도를 우회하지 못하게 함
• 컨테이너 간 통신이 비활성화된 관리 샌드박스 네트워크에 연결하거나 네트워크에 전혀 연결하지 않음
• 구성된 미리 보기 포트만 Docker가 할당한 루프백 호스트 포트에 게시

컨테이너를 재사용하기 전에 이 모든 항목을 docker inspect와 대조해 다시 검증하고 전체 세트를 해시하여 ai.libre-webui.policy 컨테이너 레이블에 기록합니다. Libre WebUI 업그레이드 이전 정책을 가진 컨테이너는 재사용하지 않고 제거 후 다시 만들므로 강화 변경 사항이 기존 작업에도 자동 적용됩니다.

Kubernetes 드라이버는 동등한 Pod 보안 컨텍스트를 적용합니다. 비-root UID/GID, 읽기 전용 루트 파일 시스템, RuntimeDefault seccomp, 권한 상승 없음, 모든 기능 제거, 제한된 임시 저장소, 리소스 한도, ServiceAccount 토큰 없음과 /workspace의 작업 소유 PVC가 적용됩니다. Pod 또는 PVC를 재사용하거나 삭제하기 전에 작업 레이블과 정책 지문을 검증합니다.

경로 검증은 절대 경로, 탐색 세그먼트, 백슬래시, NUL 문자와 지나치게 긴 경로를 거부합니다. 파일 도우미는 실제 경로를 확인하고 심볼릭 링크 탈출을 거부합니다. 쓰기는 임시 파일과 원자적 이름 변경을 사용합니다.

이 제어 기능은 의도하지 않은 호스트 노출을 줄이지만 Work를 가상 머신이나 안전한 맬웨어 분석 환경으로 만들지는 않습니다. 컨테이너는 런타임 호스트의 커널을 공유합니다. Docker, Kubernetes, 런타임, 이미지, 의존성 또는 커널 취약점이 의도한 경계를 넘을 수 있습니다.

Docker 명명 볼륨에는 독립적인 디스크 할당량이 없습니다. 생성된 프로젝트나 패키지 설치가 Docker 저장소를 소진할 수 있으므로 볼륨 증가를 모니터링하고 호스트 수준 저장소 한도를 적용하세요. Kubernetes는 PVC 크기를 요청하지만 실제 할당량 적용은 선택한 저장소 프로비저너에 따라 다릅니다.

Docker 프로덕션 강화 체크리스트

이 체크리스트는 Docker 백엔드에만 적용됩니다. Kubernetes 운영자는 Kubernetes 가이드에 설명된 차트의 네임스페이스 범위 RBAC, Pod 보안 컨텍스트, 스토리지 클래스와 CNI NetworkPolicy 적용도 검증해야 합니다.

애플리케이션은 컨테이너 플래그를 설정하고 워크스페이스 경로를 검증하며 자체 API를 보호할 수 있습니다. 하지만 호스트 방화벽 정책, 스토리지 드라이버 할당량 또는 제공된 Docker 데몬의 권한 수준을 적용할 수는 없습니다. 비공개 클라이언트 인스턴스에서는 이를 명시적인 배포 작업으로 취급하세요.

1. Docker 제어 격리

기본 Libre WebUI 컨테이너는 Work 컨테이너를 만들고 검사하기 위해 데몬을 제어해야 합니다. 따라서 마운트된 Docker 소켓은 일반 데이터 마운트가 아니라 제어 영역 자격 증명입니다. 웹 애플리케이션이 침해되면 Docker 호스트 침해로 이어질 수 있습니다.

첫 번째 완화 수단은 이 저장소에 포함되어 있습니다. docker-compose.socket-proxy.yml은 Libre WebUI 컨테이너에서 소켓을 완전히 분리합니다. 내부 네트워크의 소켓 프록시가 /var/run/docker.sock을 보유하고 Work에서 사용하는 API 영역(컨테이너, 이미지, 볼륨, 네트워크, exec, info)만 전달하며 swarm, secrets, configs, build, commit, system 엔드포인트는 데몬에 도달하기 전에 거부됩니다. Libre WebUI는 DOCKER_HOST=tcp://docker-socket-proxy:2375를 사용하도록 지정되며 소켓 마운트나 소켓 그룹 자격이 필요하지 않습니다. CLI, 대화형 터미널, Docker 진단도 이 엔드포인트를 따릅니다. 프록시는 API 표면을 좁히지만 전달하는 엔드포인트의 피해 범위를 줄이지는 않습니다. 컨테이너를 만들 수 있는 주체는 여전히 호스트 경로를 바인드 마운트할 수 있으므로 아래 경계가 계속 중요합니다.

더 강한 프로덕션 경계를 위해 Libre WebUI와 Work 데몬을 관련 없는 워크로드가 없는 전용 VM에서 실행하세요. 더 강하게 격리하려면 Work에 전용 rootless Docker 데몬 또는 별도 런타임 호스트를 제공하고 Libre WebUI에는 해당 데몬만 노출하세요. 배포하기 전에 해당 데몬에서 파일 소유권, 미리 보기 라우팅, 정리와 터미널 지원을 검증합니다. 동일한 rootful 호스트 소켓을 읽기 전용으로 마운트하는 것만으로는 Docker API가 읽기 전용이 되지 않습니다.

2. 샌드박스에서 호스트 관리 서비스로의 접근 차단

컨테이너 간 통신을 비활성화하면 Work 샌드박스끼리 접근하지 못하지만 Docker 호스트에 바인딩된 서비스에 접근하는 것까지 막지는 않습니다. 주소를 가정하지 말고 실제 관리 브리지와 서브넷을 검사하세요.

docker network inspect libre-webui-work \
  --format 'id={{.Id}} subnets={{range .IPAM.Config}}{{.Subnet}} {{end}}'
ss -lntup

호스트의 영구 방화벽 관리자를 사용해 해당 브리지에서 호스트 관리 서비스, 특히 SSH, Docker API, 데이터베이스, 모니터링/관리 포트로 들어오는 트래픽을 거부하세요. libre-webui-work에 연결된 일회용 컨테이너에서 규칙과 허용된 패키지 다운로드를 테스트한 뒤 규칙을 영구화합니다. Docker의 DOCKER-USER 체인은 전달 트래픽을 제어합니다. 대상이 Docker 호스트 자체인 트래픽에는 브리지 인터페이스의 INPUT/입력 훅 규칙도 필요할 수 있습니다.

3. 외부 통신 대상 제한

프로젝트에서 명시적으로 필요로 하지 않는 한 Work 서브넷에서 클라우드 메타데이터 엔드포인트, 비공개 인프라 범위와 클라이언트 LAN 범위를 차단하세요. WORK_RUNTIME_DNS를 통한 필터링 확인자와 호스트 또는 업스트림 방화벽 규칙을 결합합니다. 리터럴 IP 주소로 우회할 수 있으므로 DNS 필터링만으로는 부족합니다. 임의 명령이 직접 네트워크 연결을 열 수 있는 한 HTTP 프록시만으로도 부족하므로 컨테이너 외부에서 라우팅 정책을 적용하세요.

클라이언트마다 다른 동작이 필요하면 오프라인/네트워크 없음 런타임, 패키지 레지스트리 전용 런타임, 외부 통신 개방 런타임처럼 별도 명명 런타임 정책을 유지합니다. 명명 정책은 Libre가 샌드박스 네트워크를 연결하는지 결정하지만, 네트워크가 활성화된 정책의 대상 수준 제한은 외부 방화벽과 프록시 규칙에서 계속 적용해야 합니다.

4. 실제 저장소 할당량 적용

CPU, 메모리, swap, PID 한도는 명명 볼륨의 크기를 제한하지 않습니다. 여러 클라이언트에 제공하기 전에 워크스페이스별 할당량을 실제로 적용할 수 있는 저장소 백엔드를 선택하세요. XFS 프로젝트 할당량, 할당량 지원 논리 볼륨 또는 크기 제한을 제공하는 볼륨/PVC 드라이버 등을 사용할 수 있습니다. 일반 ext4 파일 시스템의 기본 Docker local 드라이버는 크기 값을 문서화하는 것만으로 신뢰할 수 있는 볼륨별 할당량이 생기지 않습니다.

모든 ai.libre-webui.managed=true 볼륨과 Docker 데이터 루트를 모니터링하고 파일 시스템이 가득 차기 전에 경고하며 실패 동작을 테스트하세요. UI 카운터나 주기적 du 검사는 경고에는 도움이 되지만, 검사 사이에 컨테이너가 남은 디스크를 모두 사용할 수 있으므로 적용 경계가 아닙니다.

5. 배포된 정책 검증

이미지 또는 데몬 정책을 변경할 때마다 일회용 Work 작업을 만들고 docker inspect로 실제 상태를 검증하세요. 비-root UID, 읽기 전용 루트, 모든 기능 제거, no-new-privileges, 메모리/swap/CPU/PID 한도, 작업 볼륨만 마운트, 예상 네트워크를 확인합니다. 기본 Libre WebUI 컨테이너에 의도한 마운트만 있는지, 공개 인바운드가 실수로 공개된 Docker 또는 미리 보기 포트가 아니라 인증된 역방향 프록시나 터널을 통해 앱에 도달하는지도 확인하세요.

미리 보기 보안과 접근성

Docker 작업의 경우 드라이버는 구성된 미리 보기 포트를 백엔드 루프백에서 동적으로 할당된 포트로 게시합니다. Kubernetes에서는 클러스터 내부 백엔드가 샌드박스 Pod IP를 직접 대상으로 합니다. 모델과 브라우저는 임의 업스트림을 선택할 수 없습니다. Libre WebUI는 정확한 작업과 엔드포인트의 기능 URL에 서명하고 요청할 때마다 미리 보기가 계속 실행 중인지 확인한 뒤 /api/work/previews를 통해 HTTP 및 WebSocket 트래픽을 프록시합니다. 미리 보기를 중지하거나 다시 시작하면 이전 URL이 취소됩니다.

미리 보기 응답은 Libre WebUI 자격 증명과 업스트림 쿠키를 제거합니다. HTML은 iframe 샌드박스와 응답 CSP 양쪽의 제약을 받으며, 동일 출처 접근 권한을 부여하지 않고 스크립트, 양식, 모달, 다운로드를 허용합니다. CSP는 별도 탭에서 연 미리 보기도 보호합니다. 생성된 애플리케이션 코드는 계속 신뢰할 수 없으며 네트워크 외부 통신을 통해 자체 워크스페이스나 브라우저 입력에서 읽을 수 있는 모든 내용을 전송할 수 있습니다. 실행 중인 미리 보기 URL을 수명이 짧은 비밀 값처럼 취급하고 공유하지 마세요.

브라우저는 Libre WebUI의 자체 공개 출처에서 프록시를 불러오므로 Docker 포트나 Pod IP를 공개하거나 혼합 콘텐츠 차단을 일으키지 않고 원격 브라우저와 HTTPS 역방향 프록시에서 작동합니다. 역방향 프록시는 /api/work/previews/의 WebSocket 업그레이드를 유지해야 하며 제공되는 Nginx 구성은 이를 지원합니다.

기본 애플리케이션은 자체 출처와 Cloudflare Turnstile만 프레임 출처로 허용합니다. 미리 보기 응답은 기본 Helmet 정책을 우회해 요청 본문을 스트리밍하고 위에서 설명한 더 좁은 샌드박스 정책을 적용할 수 있습니다. 생성된 개발 서버는 일반적으로 호환되는 리소스 헤더를 내보내지 않으므로 교차 출처 삽입자 정책은 계속 비활성화됩니다.

배포 매트릭스

Work의 가용성은 브라우저나 데스크톱 인터페이스만이 아니라 Libre WebUI 백엔드를 실행하는 머신과 프로세스에 따라 달라집니다.

배포	Work 실행과 파일	내장 미리 보기
로컬 컴퓨터의 npx libre-webui	Docker가 설치되어 실행 중이고 백엔드 사용자가 호출할 수 있으면 지원됩니다.	서명된 애플리케이션 출처 프록시를 통해 지원됩니다.
로컬 컴퓨터의 소스 개발	동일한 Docker 및 공급자 요구 사항에서 지원됩니다.	포트 3001의 개발 API 출처를 통해 지원됩니다.
Electron 데스크톱 클라이언트	조건부입니다. Electron은 외부 Libre WebUI 백엔드를 사용하며 별도 Work 런타임을 제공하지 않습니다.	해당 백엔드의 서명된 프록시 URL을 통해 지원됩니다.
원격 호스트의 Bare-metal 또는 VM 백엔드	해당 호스트에서 Docker를 사용할 수 있으면 실행, 파일, 공급자 호출이 작동합니다.	공개 역방향 프록시가 HTTP 및 WebSocket 트래픽을 유지하면 지원됩니다.
표준 저장소 Docker Compose	Docker Desktop에서는 기본적으로 지원됩니다. 이미지에 Docker CLI가 포함되고 Compose가 호스트 Docker 소켓을 마운트하며 Work 포트는 host.docker.internal을 통해 라우팅됩니다. 네이티브 Docker Engine에서는 접근 가능한 비공개 WORK_PREVIEW_BIND가 추가로 필요합니다.	같은 공개 Libre WebUI 출처를 통해 지원됩니다.
현재 Kubernetes/Helm 배포	--set work.enabled=true로 지원됩니다. 샌드박스는 네임스페이스 범위 Role과 기본 거부 NetworkPolicy 아래에서 PVC 워크스페이스를 가진 Pod로 실행됩니다. 실행, 파일, 명령, git, 대화형 터미널과 Pod IP의 Work Computer 화면 및 오디오를 지원하며 Docker 소켓은 어디에도 없습니다. Kubernetes 가이드를 참조하세요.	백엔드가 클러스터 내부에서 실행되면 서명된 프록시가 샌드박스 Pod IP를 직접 대상으로 하여 지원됩니다.

Libre WebUI 자체가 Docker에서 실행될 때 Work 사용하기

모든 저장소 Compose 파일은 Work를 활성화합니다. 이미지에 Docker CLI가 포함되고 Compose 파일이 /var/run/docker.sock을 마운트합니다. Docker Desktop에서는 기본 제공되는 라우팅 기본값으로 동작합니다. 네이티브 Docker Engine에서는 아래에서 설명하는 것처럼 형제 컨테이너에서 접근할 수 있는 비공개 호스트 인터페이스를 WORK_PREVIEW_BIND에 추가로 설정해야 합니다.

Work는 해당 소켓을 통해 호스트 데몬을 제어하므로 작업 컨테이너는 Libre WebUI 컨테이너의 자식이 아니라 형제입니다. 호스트의 docker ps에 나타나고 네이티브 설치와 같은 수명 주기 규칙으로 정리됩니다.

Docker 소켓을 웹 애플리케이션에 마운트하면 해당 컨테이너가 Docker 호스트를 root와 동등하게 제어할 수 있습니다. Work는 소켓 없이 작동할 수 없으므로 Libre WebUI는 조용히 아무것도 하지 않는 기능으로 제공하는 대신 이를 활성화합니다. 결과는 명확합니다. 모든 Libre WebUI 관리자는 사실상 Docker 호스트 관리자입니다. 운영자는 데몬 보안, 네트워크, 수명 주기, 백업, 접근 제어의 영향을 책임집니다. Work를 끄려면 Compose 파일에서 /var/run/docker.sock 줄을 삭제하세요. 다른 기능은 이 소켓에 의존하지 않습니다.

웹 애플리케이션에 소켓을 넘기지 않고 Work를 유지하려면 대신 docker-compose.socket-proxy.yml로 배포합니다. 내부 네트워크의 소켓 프록시가 소켓을 보유하고 Work에서 사용하는 API 영역만 전달하며 Libre WebUI는 DOCKER_HOST를 통해 접근합니다. 이 경계가 보장하는 내용과 보장하지 않는 내용은 Docker 제어 격리를 참조하세요.

세 가지 조건을 충족해야 하며 Work 패널에는 실패한 조건이 표시됩니다.

1. 이미지에 Docker CLI가 있어야 합니다. 공식 이미지에는 포함되어 있습니다. 사용자 지정 이미지에는 docker-cli가 있거나 해당 실행 파일을 가리키는 WORK_DOCKER_COMMAND가 필요합니다. 그렇지 않으면 The "docker" CLI is not installed…가 표시됩니다.
2. 소켓이 마운트되어 있어야 합니다. 그렇지 않으면 No Docker daemon is reachable…가 표시됩니다.
3. 백엔드 사용자가 소켓 그룹에 속해야 합니다. 이미지는 nodejs(uid 1001)로 실행되고 소켓은 일반적으로 root 또는 docker 소유이므로 Compose에서 group_add: ['${DOCKER_GID:-0}']를 전달합니다. 기본값은 Docker Desktop에 적합하고 Linux 호스트에서는 자체 그룹 ID가 필요합니다. 그렇지 않으면 The Docker socket is mounted but the Libre WebUI user cannot open it…가 표시됩니다.

# Read the socket's group as seen INSIDE a container. A macOS host reports a
# different value, because Docker Desktop proxies the socket through a VM.
echo "DOCKER_GID=$(docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  alpine stat -c '%g' /var/run/docker.sock)" >> .env
docker compose up -d --force-recreate

작업 미리 보기 포트는 Docker 호스트 루프백에 계속 바인딩됩니다. Libre WebUI는 HTTP 자산과 WebSocket 업그레이드를 포함해 실행 중인 각 미리 보기를 서명된 동일 출처 프록시 URL로 공개합니다. 임시 Docker 포트를 네트워크에 열지 않고 HTTPS 및 원격 터널 뒤에서 작동합니다. 미리 보기 문서에는 제한적인 브라우저 샌드박스 정책이 적용되고 미리 보기를 중지하거나 다시 시작하면 이전 URL이 취소됩니다.

백엔드 자체가 Docker에서 실행되면 게시 주소와 연결 주소가 다를 수 있습니다. 임시 포트를 노출하지 않도록 WORK_PREVIEW_BIND=127.0.0.1을 유지하고, 백엔드 컨테이너에서 접근할 수 있는 Docker 호스트 주소(Docker Desktop에서는 host.docker.internal)를 WORK_DOCKER_PUBLISHED_HOST로 설정합니다. 기본 제공되는 Compose 프로필은 두 값을 모두 설정하고 해당 호스트 이름을 매핑합니다. 네이티브 Linux 배포에서는 WORK_PREVIEW_BIND를 Docker 브리지 게이트웨이(또는 명시적으로 접근 가능한 다른 비공개 호스트 인터페이스)로 재정의해야 합니다. host.docker.internal만 매핑해도 호스트 루프백 리스너에 접근할 수 있는 것은 아닙니다. 이러한 원시 임시 포트를 0.0.0.0에 바인딩하지 마세요.

동시성은 별도로 제한됩니다. WORK_MAX_ACTIVE_RUNTIMES_PER_USER의 기본값은 2, WORK_MAX_ACTIVE_RUNTIMES_GLOBAL의 기본값은 3이므로 한 작업이 바쁜 동안 관리자가 두 번째 작업을 실행할 수 있습니다. 기능 응답에는 두 한도와 현재 사용량이 보고됩니다. 호스트의 메모리와 CPU에 여유가 있으면 높이세요.

Kubernetes에서는 노드 런타임 소켓을 공개하지 말고 work.enabled=true로 차트를 설치합니다. 차트는 Kubernetes 가이드에 설명된 범위 지정 RBAC, 샌드박스 네임스페이스, 네트워크 정책과 Pod/PVC 구성을 만듭니다.

런타임 구성

Work는 백엔드 프로세스에서 다음 변수를 읽습니다.

변수	기본값	용도
WORK_RUNTIME_BACKEND	docker	샌드박스 드라이버: docker 또는 kubernetes
WORK_RUNTIME_IMAGE	node:22.22-bookworm@sha256:2d178f2785b96dfbf62a416ca2e40f50e30150b4ff3320d706f0d96e90600eb3	작업 샌드박스에 사용하는 이미지
WORK_DOCKER_COMMAND	docker	Docker 백엔드 CLI 실행 파일
WORK_COMMAND_TIMEOUT_MS	120000	기본 명령 제한 시간
WORK_MAX_OUTPUT_CHARS	50000	캡처되는 명령/검색 출력의 최대 길이
WORK_MAX_AGENT_ROUNDS	48	실행별 공급자 비종속 모델/도구 라운드 예산
WORK_MEMORY_LIMIT	2g	컨테이너별 메모리 한도
WORK_CPU_LIMIT	2	컨테이너별 CPU 한도
WORK_PIDS_LIMIT	256	컨테이너별 프로세스 한도
WORK_PREVIEW_PORT	4173	앱이 컨테이너 안에서 수신해야 하는 포트
WORK_PREVIEW_BIND	127.0.0.1	미리 보기 포트가 게시되는 호스트 인터페이스
WORK_DOCKER_PUBLISHED_HOST	WORK_PREVIEW_BIND와 같음	백엔드가 Docker 게시 Work 포트에 연결할 호스트/IP
WORK_COMPUTER_SCREEN_PORT	6080	화면 브리지의 컨테이너 내부 WebSocket 포트
WORK_COMPUTER_AUDIO_PORT	6081	오디오 브리지의 컨테이너 내부 WebSocket 포트
WORK_RUN_LEASE_WAIT_MS	60000	일시적인 런타임 임대 보유자가 해제하기를 기다리는 시간
WORK_MAX_ACTIVE_RUNTIMES_GLOBAL	3	Libre WebUI 인스턴스별 동시 컨테이너 기반 작업 수
WORK_MAX_ACTIVE_RUNTIMES_PER_USER	2	관리자별 동시 컨테이너 기반 작업 수
WORK_MAX_TASKS_GLOBAL	500	Libre WebUI 인스턴스별 저장 Work 작업 한도
WORK_MAX_TASKS_PER_USER	100	관리자별 저장 Work 작업 한도
WORK_NETWORK_NAME	libre-webui-work	네트워크 작업용 관리 샌드박스 브리지 네트워크
WORK_RUNTIME_DNS	설정 안 됨	네트워크 작업에 강제로 적용할 쉼표 구분 확인자 IP
WORK_DOCKER_SOCKET	DOCKER_HOST가 unix:// 또는 tcp://이면 해당 값, 아니면 /var/run/docker.sock	대화형 터미널에서 사용하는 Docker Engine 엔드포인트
WORK_TERMINAL_MAX_SESSIONS_PER_TASK	2	작업별 동시 대화형 터미널 수
WORK_TERMINAL_IDLE_TIMEOUT_MS	900000	터미널 세션이 닫히기 전 유휴 제한 시간
WORK_RUNTIME_IDLE_TIMEOUT_MS	0(비활성화)	이 시간 동안 활동이 없으면 샌드박스 중지(미리 보기도 포함)
WORK_K8S_NAMESPACE	libre-webui-work	Kubernetes 샌드박스 Pod/PVC 네임스페이스
WORK_K8S_STORAGE_CLASS	클러스터 기본값	Kubernetes 워크스페이스 PVC의 StorageClass
WORK_K8S_WORKSPACE_SIZE	5Gi	작업별 Kubernetes PVC 기본 크기
WORK_K8S_POD_READY_TIMEOUT_MS	900000	샌드박스 Pod가 준비될 때까지 최대 대기 시간
WORK_K8S_POD_GONE_TIMEOUT_MS	60000	삭제된 샌드박스 Pod가 사라질 때까지 최대 대기 시간

프로덕션에서는 고정된 이미지 버전 또는 다이제스트를 사용하세요. 변경 가능한 이미지 태그는 Libre WebUI를 변경하지 않아도 사용 가능한 명령줄 도구와 보안 경계를 모두 바꿀 수 있습니다.

실행, 미리 보기, 파일 도우미, 명령, 샌드박스 재생성 작업은 같은 프로세스 내 용량 계산을 공유합니다. 이미 계산된 작업의 중첩 작업은 별도 작업으로 계산하지 않습니다. 작업 또는 런타임 허용 한도를 넘는 요청은 HTTP 429를 반환합니다.

고정 프로토콜 및 UI 한도

항목	한도
새 작업 또는 실행 메시지	65,536자 및 UTF-8 바이트
작업 생성/업데이트의 모델 식별자	500자 및 UTF-8 바이트
플러그인 공급자 ID	200자
작업별 활성 실행	1
명령 텍스트	20,000자
도구가 요청하는 명령 제한 시간	1~600초
미리 보기 준비	15초
파일 읽기/쓰기	UTF-8 텍스트 2,000,000바이트
직접 디렉터리 목록	처음 1,000개 항목
메시지 페이지	최대 200개 메시지 및 1,000,000바이트
저장되는 개별 메시지	100 KB
모델에 보내는 대화 컨텍스트	최근 사용자/어시스턴트 메시지 30개, 최대 256 KB
저장되는 도구 출력	원본 약 20,000자와 표시
실시간 편집기 강조	8,000자 및 400줄
브라우저 측 서식 지정	100,000자 및 4,000줄
Git 상태 출력	캡처 문자 2,000,000자
Git diff 출력	캡처 문자 600,000자
Git 기록	로컬 커밋 20개
Git 스테이징 요청 하나의 경로 수	200
Git 커밋 메시지	4,000자
모든 공급자 경로의 에이전트 루프	기본 48라운드, WORK_MAX_AGENT_ROUNDS로 구성
도구 호출 안전 예산	max(128, configured rounds × 8)회 호출

파일 접근은 UTF-8 텍스트용입니다. 통합 편집기는 바이너리 파일 편집기가 아니며 2 MB보다 큰 파일은 Work 파일 API를 통해 열 수 없습니다.

API 요약

모든 엔드포인트는 /api/work 아래에 있으며 인증과 데이터베이스의 현재 Work 접근 권한이 필요합니다. Work는 기본적으로 관리자 전용이며 관리자가 일반 작업 기능을 활성 사용자에게 열 수 있습니다. 호스트 폴더 선택과 관리 정책/접근 엔드포인트는 계속 관리자 전용입니다.

메서드	경로	용도
GET	/capabilities	선택한 런타임/공급자 가용성과 한도
GET	/tasks	현재 관리자의 작업 목록
POST	/tasks	작업과 첫 비동기 실행 생성
GET	/tasks/:id	작업 상태와 최근 메시지 불러오기
GET	/tasks/:id/messages	이전 메시지 페이지 조회
PATCH	/tasks/:id	이름 또는 명시적 모델 경로 변경
DELETE	/tasks/:id	작업과 영구 워크스페이스 제거
POST	/tasks/:id/runs	후속 실행 시작
POST	/tasks/:id/messages	활성 실행 중 에이전트에 메시지 보내기
GET	/tasks/:taskId/runs/:runId/events	SSE를 사용한 인증된 실시간 실행 이벤트 스트리밍
POST	/tasks/:id/cancel	활성 실행 취소
GET	/tasks/:id/approvals	보류 중인 승인과 작업의 자동 검토 상태
PUT	/tasks/:id/approvals	작업별 승인 사용 여부 전환
POST	/tasks/:id/approvals/:approvalId	보류 중인 승인 결정(이번만/항상 허용, 거부)
DELETE	/tasks/:id/approval-rules/:ruleId	항상 허용 규칙 삭제
GET	/computer/setup	Work Computer 설정 상태(관리자)
POST	/computer/setup	GUI 이미지 빌드 및 정책 생성(관리자)
POST	/tasks/:id/computer/start	작업의 Work Computer 세션 시작
GET	/tasks/:id/computer/control	화면 제어 사용자 및 에이전트 직접 조작 요청
POST	/tasks/:id/computer/control	화면 직접 조작 또는 제어 갱신
DELETE	/tasks/:id/computer/control	화면을 에이전트에 돌려주기
POST	/tasks/:id/computer/teach	기록한 시연을 가르친 스킬로 저장
POST	/tasks/:id/computer/anchor	기록한 클릭 아래의 요소 확인
POST	/computer/skills/:slug/trace	가르친 스킬에 성공/실패 줄 추가
GET	/tasks/:id/files	워크스페이스 디렉터리 목록
GET	/tasks/:id/file	워크스페이스 텍스트 파일 읽기
PUT	/tasks/:id/file	워크스페이스 텍스트 파일 저장
GET	/tasks/:id/git	보호된 로컬 Git 상태 및 기록 읽기
GET	/tasks/:id/git/diff	크기가 제한된 로컬 diff 읽기
POST	/tasks/:id/git/init	로컬 Git 초기화
POST	/tasks/:id/git/stage	명시적 워크스페이스 경로 스테이징
POST	/tasks/:id/git/commit	스테이징된 변경 사항 커밋
POST	/tasks/:id/git/branches	로컬 브랜치 생성
POST	/tasks/:id/git/switch	깨끗한 기존 로컬 브랜치로 전환
POST	/tasks/:id/preview/start	관리되는 미리 보기 시작
POST	/tasks/:id/preview/stop	관리되는 미리 보기 중지

작업 ID는 항상 인증된 소유자와 대조됩니다. 현재 계정 상태, 역할, Work 접근 정책을 요청마다 데이터베이스에서 읽으므로 이전 JWT에 오래된 역할 클레임이 들어 있어도 권한 취소가 적용됩니다.

작업 업데이트 스키마는 내부 호환성을 위해 백엔드 networkEnabled 필드를 유지합니다. 이 필드는 독립적인 Work UI 제어 기능으로 제공되지 않습니다. 작업을 만들 때 원하는 네트워크 기본값의 명명 런타임 정책을 선택하세요. 원시 필드를 영구 구성 API로 사용하지 마세요.

삭제, 계정 변경, 백업

작업 삭제

작업 삭제는 의도적으로 되돌릴 수 없습니다.

1. 백엔드가 작업을 폐기 중으로 표시해 새 변경 작업이 시작되지 않게 합니다.
2. 활성 실행을 취소하고 작업 샌드박스를 중지합니다.
3. Libre WebUI가 런타임 리소스의 작업 소유권 레이블을 검증합니다.
4. 컨테이너/Pod와 명명 볼륨/PVC를 제거합니다.
5. 데이터베이스 작업을 삭제하고 해당 실행과 메시지를 연쇄 삭제합니다.
6. API 성공 후 해당 작업의 브라우저 초안을 지웁니다.

런타임 정리가 실패하면 Libre WebUI는 작업 데이터베이스 레코드를 유지하고 오류를 반환하므로 운영자가 Docker 또는 Kubernetes 백엔드를 복구한 뒤 다시 시도할 수 있습니다. 추적되지 않는 샌드박스나 워크스페이스를 남기면서 메타데이터만 조용히 삭제하지 않습니다.

실행 또는 미리 보기 중지는 삭제와 다릅니다. 실행을 중지하지만 명명 볼륨과 대화를 보존합니다.

관리자 권한 강등과 사용자 삭제

관리자를 강등할 때 Libre WebUI는 런타임 정리에 의존하기 전에 역할 취소를 저장합니다. 이후 모든 Work 요청은 현재 역할과 접근 모드를 확인합니다. 새 역할에 접근 권한이 없으면 백엔드가 사용자의 Work 작업을 일시 중지하고 활성 실행 중단과 샌드박스 중지를 시도합니다. 정리에 실패해도 취소된 접근 권한은 취소된 상태로 유지되고 역할 업데이트는 실패를 보고하므로 운영자가 런타임을 복원해 다시 시도할 수 있습니다.

다른 사용자를 삭제할 때는 먼저 해당 사용자가 관리하는 모든 Work 리소스를 제거합니다. 외부 런타임 정리가 실패하면 사용자 레코드를 유지하므로 안전한 정리에 필요한 소유권 메타데이터를 잃지 않고 관리자가 다시 시도할 수 있습니다.

전체 작업 백업하기

완전한 Work 백업에는 다음 두 항목이 모두 필요합니다.

• 작업 소유권, Docker 또는 Kubernetes 리소스 이름, 공급자 라우팅, 실행, 메시지, 활동을 포함하는 Libre WebUI 데이터베이스
• Work 파일을 포함하며 ai.libre-webui.managed=true 레이블이 지정된 모든 Docker 볼륨 또는 Kubernetes PVC

일회용 컨테이너와 미리 보기 프로세스는 백업할 필요가 없습니다. 일관된 백업을 위해 새 Work 활동을 중지하고 백엔드를 중지한 뒤 데이터베이스와 작업 워크스페이스를 캡처하세요. 사용 중인 백엔드에 맞는 Docker 볼륨 또는 Kubernetes 저장소 공급자 스냅샷 절차를 따릅니다.

데이터베이스와 일치하는 워크스페이스를 함께 복원하세요. 데이터베이스에 기록된 정확한 이름으로 각 볼륨 또는 PVC를 다시 만들고 ai.libre-webui.task=<task UUID> 및 ai.libre-webui.managed=true를 포함한 작업 소유권 메타데이터를 복원합니다. 파일만 복사하면 Docker 또는 Kubernetes 레이블이 보존되지 않습니다. 데이터베이스만 복원하면 파일이 없는 작업 레코드가 생기고, 저장소만 복원하면 Libre WebUI가 리소스를 찾고 검증하는 데 사용하는 작업 소유권과 생성된 리소스 이름이 사라집니다.

설치에서 암호화된 공급자 자격 증명도 사용한다면 데이터 디렉터리 및 암호화 키에 관한 기본 Libre WebUI 백업 지침을 따르세요.

현지화와 아랍어 RTL

전체 Work 인터페이스는 지원되는 25개 로캘로 번역됩니다. 영어, 아랍어, 벵골어, 체코어, 덴마크어, 독일어, 스페인어, 프랑스어, 힌디어, 인도네시아어, 아이슬란드어, 이탈리아어, 일본어, 한국어, 말레이어, 네덜란드어, 폴란드어, 포르투갈어, 러시아어, 스웨덴어, 태국어, 터키어, 우크라이나어, 베트남어, 중국어를 지원합니다.

아랍어는 React가 렌더링하기 전에 lang="ar"와 dir="rtl"을 적용합니다. 사이드바가 오른쪽으로 이동하고 데스크톱 분할에서 대화는 오른쪽, 워크스페이스는 왼쪽에 배치됩니다. 방향 아이콘이 반전되고 탭 탐색이 RTL 순서를 따르며 드래그/키보드 크기 조절이 시각적 RTL 의미 체계를 사용합니다.

방향이 정확성에 영향을 주는 기술 콘텐츠는 왼쪽에서 오른쪽으로 유지됩니다.

• 코드와 구문 강조
• 파일 시스템 경로
• 모델 식별자
• 명령과 미리 보기 로그
• 도구 출력과 메타데이터
• 코드 블록 콘텐츠

작업 이름, 자연어 프롬프트, 오류, 파일 이름과 미리 보기 명령에는 상황에 따라 자동 텍스트 방향을 사용합니다.

문제 해결

npx 사용 시 런타임을 사용할 수 없음

npx libre-webui는 호스트에서 백엔드를 실행하지만 Docker를 설치하지는 않습니다. Libre WebUI를 시작하는 것과 같은 운영 체제 사용자로 docker info를 실행하세요. 명령이 없거나 데몬에 접근할 수 없다면 Docker를 설치/시작하거나 해당 사용자의 데몬 권한을 수정한 뒤 Work를 다시 불러옵니다.

Ollama가 정상 상태이거나 현재 관리자를 위한 모델과 자격 증명이 구성된 활성 완성/채팅 플러그인이 하나 이상 있는지도 확인하세요.

Docker 또는 Kubernetes에서 런타임을 사용할 수 없음

저장소 Compose 배포에서는 이 오류가 나타나지 않아야 합니다. 이미지에 Docker CLI가 포함되고 Compose 파일이 호스트 소켓을 마운트하기 때문입니다. 오류가 나타나면 패널이 원인을 표시합니다. 사용자 지정 이미지의 CLI 누락, 제거되었거나 없는 소켓 마운트 또는 컨테이너 사용자가 속하지 않은 소켓 그룹일 수 있습니다. 마지막 경우 DOCKER_GID를 설정하고 컨테이너를 다시 만드세요. Libre WebUI 자체가 Docker에서 실행될 때 Work 사용하기를 참조하세요.

Kubernetes에서는 --set work.enabled=true로 네이티브 런타임을 활성화합니다. 그러면 Libre가 kubernetes를 보고하고 Kubernetes API를 검사하며 PVC 워크스페이스가 있는 Pod로 샌드박스를 실행합니다. 노드 컨테이너 런타임 소켓을 마운트하지 마세요. Kubernetes 가이드를 참조하세요.

Work 호환 모델이 없음

Ollama에서는 tools를 명시하는 모델을 검사하거나 선택합니다. 플러그인의 경우 다음을 확인하세요.

• 유형이 완성 또는 채팅인지
• 활성 상태인지
• 구성된 모델 맵에 정확한 모델이 표시되는지
• 현재 관리자에게 사용할 수 있는 API 키가 있는지
• 원격 모델이 해당 공급자의 도구 호출을 구현하는지

Work는 다른 공급자를 대체 경로로 사용하지 않습니다.

패키지 설치 또는 원격 Git 명령 실패

작업에 선택된 명명 런타임 정책에서 네트워크 접근이 활성화되었는지 확인합니다. 독립적인 작업별 네트워크 토글은 없습니다. 그런 다음 DNS, 프록시, 방화벽/NetworkPolicy, 레지스트리, 인증서, 런타임, 업스트림 서비스 구성을 검사하세요. 선택한 런타임 이미지에 호출하는 명령이 있는지도 확인합니다.

Git 탭은 로컬 전용이며 원격 작업을 절대 수행하지 않습니다. 작업의 네트워크 및 자격 증명 정책에서 원격 Git을 의도적으로 허용할 때만 터미널 또는 모델 명령 화면을 사용하세요. 수명이 긴 액세스 토큰을 작업 워크스페이스에 붙여 넣지 마세요.

에이전트 한도에서 실행 중지

모델이 구성된 라운드 또는 파생된 도구 호출 안전 예산을 소진했을 수 있습니다. Work는 실행을 끝내기 전에 도구 없는 최종 인계를 요청하므로 완료한 작업과 남은 단계를 검토하세요. 작업은 입력 필요 상태로 유지됩니다. 이 상태는 해당 실행의 종료 상태이지만 완료되었다고 주장하지 않습니다. 같은 영구 워크스페이스에서 계속하려면 후속 실행을 시작하세요. 호스트와 원격 공급자 비용 정책이 더 긴 실행을 허용하는 경우 모든 공급자에 대해 WORK_MAX_AGENT_ROUNDS를 의도적으로 높일 수도 있습니다.

Work 시작 시 HTTP 429

인스턴스 또는 관리자가 활성 런타임이나 저장 작업 허용 한도에 도달했습니다. 다른 실행 또는 미리 보기가 중지될 때까지 기다리고 오래된 작업을 삭제하거나, 리소스가 충분한 호스트에서 해당 WORK_MAX_* 설정을 의도적으로 높이세요.

미리 보기가 준비되지 않음

명령이 계속 실행되고 0.0.0.0에 바인딩되며 15초 안에 WORK_PREVIEW_PORT에서 수신하는지 확인합니다. 명령이 비어 있으면 Work가 단일 중첩 앱을 포함해 package.json의 dev 스크립트 또는 일반 index.html을 자동 감지합니다. 여러 앱 또는 지원되는 진입점 없음 오류가 보고되면 선택적 명령 필드에 명시적 명령을 입력합니다. 사용자 지정 명령은 /workspace에서 시작하므로 중첩 앱에는 cd <app-directory> && ...를 사용하세요.

서버에서는 미리 보기가 작동하지만 원격 브라우저에서는 작동하지 않음

배포가 서명된 Work 미리 보기 프록시가 포함된 빌드를 실행하는지 확인한 뒤 미리 보기를 다시 시작해 이전 루프백 URL을 교체합니다. 일반 페이지는 로드되지만 Hot Reload가 작동하지 않으면 역방향 프록시와 터널이 /api/work/previews/에서 WebSocket 업그레이드를 허용하는지 확인합니다. Docker 게시 포트는 백엔드 루프백에 유지해야 하며 방화벽에서 열 필요가 없습니다.

파일은 남아 있지만 미리 보기가 중지됨

취소, 백엔드 재시작, 명시적 미리 보기 중지 또는 준비 검사 실패 후 예상되는 동작입니다. 미리 보기 프로세스는 일시적이고 명명 볼륨은 영구적입니다. 작업을 다시 열고 미리 보기를 다시 시작하세요.

파일을 열거나 저장할 수 없음

통합 파일 API는 최대 2 MB의 UTF-8 텍스트 파일을 허용합니다. 파일을 연 뒤 변경되었다는 저장 오류가 나타나면 다른 모델 또는 브라우저 변경 사항을 덮어쓰지 않도록 다시 편집하기 전에 파일을 다시 불러오세요.

8,000자 또는 400줄을 넘으면 구문 강조가 의도적으로 일반 텍스트로 전환됩니다. 서식 지정에는 별도의 100,000자, 4,000줄 한도가 있으며 문서화된 파일 제품군만 지원합니다.

Work에서 샌드박스를 복구 중이라고 표시됨

시작 또는 해제 과정에서 알려진 샌드박스 하나 이상이 중지되었음을 증명할 수 없었습니다. Work는 닫힌 상태로 실패하고 10초마다 재시도합니다. Docker 데몬 또는 Kubernetes API 접근을 복원하고 백엔드 로그를 검사하세요. 레이블이 지정된 런타임 리소스의 조정이 필요한 동안 작업 데이터베이스 행을 삭제하지 마세요.

작업 삭제 실패

선택한 런타임에 접근할 수 있는지 확인합니다. 예상 ai.libre-webui.task 레이블이 없는 충돌 리소스는 제거하지 않고 의도적으로 거부합니다. 이름/소유권 충돌을 신중하게 해결한 뒤 삭제를 다시 시도하세요.

보안 요약

설치에서 Work를 활성화하기 전에 다음을 기억하세요.

• Work는 기본적으로 관리자 전용입니다. 모든 사용자에게 열면 모든 활성 계정이 샌드박스 운영자가 되므로 신중히 결정하세요. 호스트 폴더 워크스페이스는 모든 모드에서 관리자 전용입니다.
• 백엔드는 구성된 Docker 데몬 또는 Kubernetes 샌드박스 네임스페이스를 제어해야 합니다.
• 컨테이너는 파일 시스템 노출을 줄이지만 가상 머신은 아닙니다.
• 명명 오프라인 정책이 없는 작업은 외부 네트워크에 접근합니다. 명명 정책이 기본값을 선택하고 대상 수준 제한은 계속 운영자 책임입니다.
• Work 볼륨에는 독립적인 디스크 할당량이 없습니다.
• Git 탭은 로컬 전용이며 API에서 원격 자격 증명을 마운트하거나 허용하지 않습니다.
• 호스트 방화벽 정책, 데몬 격리, 외부 통신 제한, 실제 볼륨 할당량은 운영자가 적용해야 합니다.
• 원격 공급자는 요청한 도구 결과를 받으며 실행 하나에서 여러 번 호출되어 비용이 발생할 수 있습니다.
• 미리 보기 포트는 백엔드 루프백에 유지되고 서명되어 취소 가능한 프록시 URL을 통해서만 공개됩니다.
• 표준 Docker Compose는 Docker 런타임을 제공하고 Kubernetes/Helm은 work.enabled=true일 때 네이티브 Pod/PVC 런타임을 제공합니다.
• 완전한 백업에는 Libre WebUI 데이터베이스와 Work 볼륨이 모두 필요합니다.

관련 문서

• 빠른 시작
• 모델 사용하기
• 키보드 단축키
• 환경 변수
• Docker
• Kubernetes
• 인증
• 문제 해결