번역되지 않은 페이지는 영어로 열리며 영어로 표시됩니다.
이 기계 번역이 생성된 뒤 영어 원문이 변경되었습니다. 최신 지침은 영어 페이지를 확인하세요.
이 페이지는 영어 원문을 기계 번역한 것이며, 영어 원문이 기준입니다. Machine-translated from the English page, which is authoritative.
빠른 시작
이 페이지는 노트북에서 Loom을 부팅하고 HTTP, Python, MCP로 첫 메모리를 저장하는 방법을 설명합니다. API 키와 계정이 필요하지 않습니다. 릴리스된 스택을 새로 설치하면 이미지에 포함된 작은 로컬 모델로 임베딩하므로 네트워크 없이도 검색이 의미 있는 결과를 반환합니다(업그레이드한 설치는 .env에 지정된 임베더를 그대로 유지합니다). LLM은 가짜이므로 추출과 memory.ask 응답은 아무 결과도 만들지 않습니다. 체크아웃한 저장소의 .env는 둘 다 가짜 프로바이더를 사용합니다.
기본 Docker 설치는 단일 사용자용입니다. 로그인이 없고, localhost에서만 접근할 수 있으며, 기본 dev/local 네임스페이스를 사용합니다. 멀티 유저 모드를 켜지 않아도 한 사람이 여러 에이전트를 연결할 수 있습니다. 팀 배포도 OSS에서 지원되며, 인증된 계정과 네임스페이스 접근 제어를 제공합니다. 멀티 유저 모드로 시작하거나 배포 → 아이덴티티 모드를 따르세요. 두 모드 모두 동일한 Loom 기능을 지원하며, 실제 LLM과 임베딩을 사용하려면 어느 모드에서든 프로바이더 설정이 필요합니다.
사전 요구 사항
| 필요 항목 | 용도 |
|---|---|
| compose 플러그인이 있는 Docker | 스택: ClickHouse와 Loom 서버. |
| Python 3.12 이상 | 기여자 전용 loom CLI. SDK는 3.11+를 지원합니다. |
| Node.js 20 이상 | TypeScript SDK (선택 사항). |
사용 가능한 포트 7777 |
Loom. 체크아웃 개발 환경에서는 ClickHouse도 8123과 9000으로 노출됩니다. |
jq |
4단계에서 curl 출력을 읽을 때 사용 (선택 사항). |
1. 스택 부팅
빠른 방법: 릴리스된 이미지, 클론 없음
사전 요구 사항: Docker Desktop 또는 Compose 2.20 이상이 설치된 Docker Engine. Windows에서는 docker가 동작하는 WSL 2 터미널에서 명령을 실행하세요. 해당 배포판에 WSL 통합을 켠 Docker Desktop이나, 그 안에 설치한 Docker Engine이면 됩니다. 설치 프로그램은 POSIX 셸 스크립트입니다.
curl -fsSL https://github.com/ClickHouse/loom/releases/latest/download/install.sh -o loom-install.sh && sh loom-install.sh && rm loom-install.sh
이 명령은 설치 프로그램을 현재 디렉터리에 저장한 다음 그 파일을 실행합니다. 따라서 홈 디렉터리나 본인만 쓸 수 있는 다른 디렉터리에서 실행하세요. 공유 디렉터리에서는 다른 사람이 실행 전에 loom-install.sh를 바꿔치기하거나 다른 파일을 가리키게 할 수 있습니다. 다운로드가 실패하면 curl의 오류와 0이 아닌 종료 코드로 중단됩니다. 설치가 실패한 뒤에는 보고된 문제를 해결하고 전체 명령을 다시 실행하세요. 설치 프로그램은 최신 GitHub Release에서 loom-stack.tar.gz를 내려받아 SHA-256을 검증하고, Compose와 ClickHouse 설정을 ~/.loom 아래에 설치합니다. 그런 다음 버전이 일치하는 ghcr.io/clickhouse/loom:X.Y.Z와 ghcr.io/clickhouse/loom-extractor:X.Y.Z(문서 추출기 서비스) 이미지를 가져오고, http://localhost:7777/v1/health가 응답할 때까지 기다립니다. 서버 이미지에는 API, 워커, 마이그레이션, 서버 루트에서 제공되는 빌드된 React 대시보드가 들어 있어 Python이나 Node를 따로 설치할 필요가 없습니다. Python, TypeScript, Go 컴파일러 인덱서가 포함되어 활성화되어 있으며, amd64에서는 C++ 인덱서(scip-clang)도 마찬가지입니다. TypeScript 인덱서로 인덱싱한 저장소는 의존성이 자동으로 설치됩니다. 두 이미지 모두 Linux amd64와 arm64를 지원하며, Apple Silicon의 Docker Desktop도 포함됩니다.
Loom이 응답하면 설치 프로그램은 다음을 수행합니다.
- 메모리를 확인합니다. 새로 설치하면 테스트 메모리를 저장하고, 다시 읽은 뒤 삭제합니다. 이로써 쓰기와 읽기가 동작함을 보여 주며 살아 있는 메모리는 남지 않습니다(삭제된 버전은 Recently deleted에 표시됩니다). 이 확인이 통과한 뒤의 재실행이나 업그레이드에서는 건너뜁니다.
- 로그인이 켜져 있는지 확인합니다. 로그인이 켜져 있으면 에이전트를 연결하지 않고 토큰을 어디서 받는지 안내합니다.
- 코딩 에이전트 연결을 제안합니다. 터미널에서는 발견한 에이전트마다 묻습니다. Claude Code와 Codex는 플러그인으로, VS Code는
code --add-mcp로 연결합니다.LOOM_CONNECT는 질문을 대신하며 터미널이 없는 실행에서도 동작하고, 이름을 지정한 클라이언트만 확인합니다. 값은claude-code,codex,vscode의 쉼표 목록,all, 또는 단독으로 쓴none이며, 그 밖의 값이면 설치가 중단됩니다. 터미널도LOOM_CONNECT도 없으면 어떤 에이전트도 확인하거나 변경하지 않습니다. 이전에 설정한 플러그인이나 MCP 서버(플러그인,claude mcp add,codex mcp add,loom install로 설정한 것)는 그대로 둡니다. Claude Code 플러그인의 경우 설치 프로그램이 이 설치를 가리키게 하는 명령을 출력합니다. Claude Code의 플러그인은 PATH에 있는 Node.js 18 이상을 실행하므로, 없으면 설치 프로그램은 플러그인을 설치하지 않고 MCP 서버만을 위한claude mcp add줄을 출력합니다. Codex의 플러그인은 nvm 같은 곳에서도 Node.js를 찾으므로 설치되며,codex mcp add줄이 함께 출력됩니다. Codex의 플러그인은 항상http://localhost:7777을 사용하므로, 다른 곳에 설치한 경우에는 대신 설정 페이지 링크를 안내합니다. VS Code는 원격 세션이나 WSL에서는 제안하지 않습니다.LOOM_CONNECT가 지정했지만 PATH에 없는 클라이언트는 이름을 알려 줍니다. - 대시보드를 엽니다. 새로 설치한 데스크톱 환경에서 열며,
LOOM_NO_OPEN=1이면 건너뜁니다.
WSL에서 실행하면 이 단계들은 WSL 안에서 동작합니다. Windows에서 실행되는 에이전트는 Windows에서 연결 가이드로 연결하고, 설치 프로그램이 출력하는 대시보드 주소는 Windows 브라우저에서 여세요.
Ctrl-C는 어느 단계에서든 실행을 멈춥니다. 에이전트 CLI가 플러그인용으로 시작한 클론은 백그라운드에서 끝까지 진행될 수 있습니다.
스택은 자체 ClickHouse 컨테이너를 실행합니다. 이미 운영 중인 ClickHouse(자체 관리 서버 또는 Keeper가 있는 26.4 이상의 ClickHouse Cloud 서비스)를 쓰려면 그 URL을 전달하세요. URL에 비밀번호가 없으면 설치 프로그램이 비밀번호를 묻고, loom 데이터베이스와 읽기 전용 reader 사용자를 만들거나 관리자가 실행해야 할 SQL을 출력합니다(ClickHouse 선택).
curl -fsSL https://github.com/ClickHouse/loom/releases/latest/download/install.sh -o loom-install.sh \
&& sh loom-install.sh --clickhouse https://loom@abc123.us-east-1.aws.clickhouse.cloud:8443 && rm loom-install.sh
각 릴리스의 install.sh는 해당 릴리스를 설치합니다. 따라서 latest가 제공하는 사본은 최신 릴리스를 설치하고, 아래의 릴리스 전용 URL은 항상 그 릴리스를 설치합니다. 더 새로운 설치 위에 이전 릴리스의 사본을 실행하면, 더 새로운 데이터 위에서 이전 Loom과 ClickHouse를 시작하지 않도록 설치를 거부합니다. 의도적으로 다운그레이드하려면 설치 프로그램 설치 다운그레이드를 따르세요. 릴리스를 고정하려면 해당 릴리스의 URL을 사용하세요.
curl -fsSL https://github.com/ClickHouse/loom/releases/download/v1.2.3/install.sh -o loom-install.sh && sh loom-install.sh && rm loom-install.sh
시작하기 전에 모든 것을 직접 확인하려면 파일을 내려받아 검사하세요.
curl -fLO https://github.com/ClickHouse/loom/releases/latest/download/loom-stack.tar.gz
curl -fLO https://github.com/ClickHouse/loom/releases/latest/download/loom-stack.tar.gz.sha256
curl -fL https://github.com/ClickHouse/loom/releases/latest/download/install.sh -o loom-install.sh
sha256sum -c loom-stack.tar.gz.sha256
tar -tzf loom-stack.tar.gz
출력된 내용이 올바르다고 판단되면 검증한 번들로 설치하세요.
LOOM_INSTALL_BUNDLE="$PWD/loom-stack.tar.gz" \
LOOM_INSTALL_CHECKSUM="$PWD/loom-stack.tar.gz.sha256" sh loom-install.sh && rm loom-install.sh
설치 프로그램에 전달한 LOOM_PORT, LOOM_BIND_HOST, LOOM_IMAGE_REPOSITORY, LOOM_EXTRACTOR_IMAGE_REPOSITORY, LOOM_CLICKHOUSE_IMAGE는 설치 디렉터리의 .env에 기록됩니다. 그래서 이후 그 디렉터리에서 실행하는 docker compose 명령과 설치 프로그램 재실행이 같은 포트와 이미지를 사용합니다. 루프백이 아닌 LOOM_BIND_HOST는 Loom을 이 호스트 밖으로 공개하며, 이 경우 서버는 LOOM_PUBLIC_BASE_URL과 로그인 없이는 시작을 거부합니다. LOOM_SKIP_START=1로 설치하고, .env에 이 값들을 설정한 뒤(아래 참고), LOOM_SKIP_START=1 없이 설치 명령을 다시 실행하세요.
각 릴리스는 빌드 시점에 최신이던 ClickHouse 릴리스를 실행합니다. 같은 Loom 버전에 대해 설치 명령을 다시 실행하면 그 ClickHouse가 유지되고, 더 새로운 Loom 버전을 설치하면 ClickHouse도 옮겨 갑니다. 단 .env가 LOOM_CLICKHOUSE_IMAGE를 고정한 경우는 예외입니다(릴리스를 다시 따르려면 그 줄을 삭제하세요). 설치 명령을 다시 실행하면 관리되는 Compose/설정 파일을 업데이트하고 컨테이너를 재조정합니다. ~/.loom/.env와 이름이 지정된 Docker 볼륨은 보존하며, 추출기의 URL과 토큰이 없는 파일에는 이를 추가합니다. 데이터를 삭제하지 않고 중지하려면 다음을 실행하세요.
docker compose --project-directory "$HOME/.loom" down
--volumes는 되돌릴 수 없는 초기화를 의도할 때만 추가하세요.
GitHub Codespaces에서 체험하기
저장소의 dev container는 내 컴퓨터에 아무것도 설치하지 않고 codespace에서 최신 릴리스를 실행합니다. 위의 설치 프로그램으로 Loom을 설치하고, 시작하고, Claude Code를 연결합니다. 처음 시작할 때는 약 3 GB의 이미지를 내려받으며 몇 분이 걸립니다. 생성 로그의 마지막 줄들이 출력하는 주소에서 대시보드를 여세요(Loom is running in the
codespace. Dashboard: https://<codespace name>-7777.app.github.dev, 즉 Ports 탭의 7777 포트 포워딩 주소). 그 위에 있는 설치 프로그램의 http://127.0.0.1:7777/은 codespace 자체의 주소입니다. codespace의 터미널에서 cd ~ && claude를 실행하세요(Loom 자체 작업용 지침이 있는 체크아웃 밖에서 실행합니다). 로그인한 뒤 "Remember that I never deploy on Friday"라고 말하고, 새 claude 세션에서 "When can I deploy?"라고 물어보세요.
이 체험판은 로그인 없이 단일 사용자로 실행됩니다. 브라우저에서 7777 포트는 비공개로 포워딩되며, 그 주소는 내 GitHub 계정에만 응답합니다. 비공개로 유지하세요. 공개로 바꾸거나 조직에 비공개로 공유하면, 로그인 없는 서버를 공유 대상 모두에게 여는 셈입니다. codespace 안의 에이전트(예: 그 안의 claude)는 http://localhost:7777을 사용합니다. 대시보드의 연결 안내 줄은 대신 포워딩된 주소를 표시하는데, 이 주소는 GitHub 로그인이 필요하며 codespace 안의 에이전트에는 그 로그인이 없습니다. 데스크톱 VS Code에서 codespace를 열면 이 포트가 노트북의 localhost:7777로도 포워딩되는데, 이 경우 로컬 설치와 마찬가지로 노트북의 모든 프로그램에 열려 있고 노트북의 에이전트도 그곳에서 접근할 수 있습니다. 이 포워딩에는 그 로컬 포트가 비어 있어야 하므로, 로컬 Loom이 있다면 먼저 중지하세요. 대시보드는 브라우저 주소에서 사용하세요. 노트북의 localhost:7777에서는 페이지가 열리지만 서버가 그 요청을 거부해 데이터가 표시되지 않으며, 포워딩된 주소만 이 서버 자체의 페이지입니다.
설치는 /workspaces/.loom에 있으므로, codespace를 재빌드해도 .env와 Compose 프로젝트는 유지됩니다. 다만 메모리는 재빌드가 보존하지 않을 수 있는 Docker 볼륨에 저장되며, 재빌드하면 그 위에서 최신 릴리스의 설치 프로그램도 실행되어 그 릴리스로 옮겨 갑니다. 이 문서가 ~/.loom 또는 "$HOME/.loom"이라고 쓴 곳에서 codespace는 /workspaces/.loom을 사용합니다. Codespaces는 7777 포트가 열리자마자 포트를 열겠느냐고 제안합니다. 대시보드는 생성 로그에 "Loom is running in the codespace"가 출력된 뒤에 응답합니다. 로그가 대신 오류로 끝나면 codespace의 터미널에서 sh .devcontainer/start-loom.sh를 실행하세요. 첫 실행에서 설정된 내용은 유지됩니다.
다중 사용자 모드로 시작
첫 부팅부터 계정과 로그인이 있는 릴리스 이미지 신규 설치를 하려면, 컨테이너를 시작하지 않고 스택 파일만 준비하세요.
curl -fsSL https://github.com/ClickHouse/loom/releases/latest/download/install.sh -o loom-install.sh \
&& LOOM_SKIP_START=1 sh loom-install.sh && rm loom-install.sh
Docker를 시작하기 전에 ~/.loom/.env를 편집하세요. 기존 identity 및 auth 항목을 교체하고 가입 설정을 추가합니다.
LOOM_IDENTITY_PROVIDER=trust-network
LOOM_AUTH_REQUIRED=true
LOOM_SELF_SIGNUP=open
생성된 COMPOSE_PROJECT_NAME과 LOOM_JWT_SECRET은 그대로 두세요. 그런 다음 스택을 가져와 시작합니다(자체 ClickHouse를 쓴다면 설치 프로그램이 안내한 대로 먼저 ch-setup을 실행하세요).
docker compose --project-directory "$HOME/.loom" pull
docker compose --project-directory "$HOME/.loom" run --rm loom loom ch-setup # your own ClickHouse only
docker compose --project-directory "$HOME/.loom" up -d
상태 확인이 통과하면 http://localhost:7777/을 열고 가입하세요. SDK와 MCP 클라이언트에는 토큰이 필요합니다. 아래 예제의 단일 사용자 기본값 dev/local이 아니라, 내 계정에 부여된 org와 네임스페이스를 사용하세요.
이는 다중 사용자 인증을 켜는 것이지 공개 네트워킹이 아닙니다. 스택은 여전히 localhost에 바인딩됩니다. 팀과 공유하기 전에 운영자 접근과 TLS를 설정하세요. 실제 모델과 API 키도 함께 설정해야 합니다. 다중 사용자 모드를 선택한다고 가짜 LLM이 대체되지는 않습니다.
이미 실행 중인 단일 사용자 스택은 대신 전환 안내를 따르세요. 컨테이너를 다시 만들어도 기존 데이터 볼륨은 보존됩니다.
기여자 방법: 체크아웃 빌드
사전 요구 사항: Docker Compose 2.34 이상. 체크아웃의 compose 파일이 ClickHouse를 매일 가져오는 데 필요합니다.
git clone https://github.com/ClickHouse/loom && cd loom
python3 -m venv .venv && . .venv/bin/activate
pip install -e .
loom up
loom up은 세 가지를 수행합니다.
- git이 추적하지 않는 두 파일을 만듭니다.
.env.example에서.env를, 템플릿에서deploy/clickhouse-config/named_collections.xml을 만듭니다. 어느 쪽도 덮어쓰지 않으며, 추출기 토큰이 없는 기존.env에는 토큰을 추가합니다. - dev compose 스택을
--build로 실행합니다. - 서버가 준비될 때까지
http://localhost:7777/v1/health를 폴링하며 보류 중인 마이그레이션 수를 출력합니다.--timeout(300초) 후에는 마지막 health 응답 본문과 로그 줄을 보여 주고 포기합니다.
기여자의 첫 부팅은 이미지를 빌드하고 모든 스키마 마이그레이션을 적용하므로 몇 분을 예상하세요. 그런 다음 loom up은 대시보드 URL(http://localhost:7777/), 첫 메모리를 저장하는 curl 호출과 Python 스니펫, 그리고 Claude Code를 연결하는 줄을 출력합니다. 인증이 켜져 있으면 writer 토큰도 발급해 그 스니펫에 넣습니다.
| 플래그 | 동작 |
|---|---|
--rebuild |
코드 변경 후 다시 빌드합니다. |
--no-build |
캐시된 이미지를 재사용합니다. |
--open |
대시보드를 엽니다. |
--port |
다른 Loom 포트를 사용합니다. |
--env-file |
다른 env 파일을 지정합니다. |
실행 중인 스택에서 loom up을 다시 실행하면 health만 다시 확인합니다. make dev는 CLI 없이 같은 일을 하며 다음을 실행합니다.
docker compose --env-file .env -f compose.yaml -f dev/docker-compose.dev.yml --profile bundled up -d --build
compose.yaml이 먼저 오므로 Compose는 ${VAR:-default} 치환을 위해 저장소 루트의 .env를 읽습니다. --env-file .env는 그것을 명시할 뿐입니다. loom down은 스택을 중지하고 볼륨을 보존합니다. loom down --delete-data는 생성된 Compose 프로젝트 이름을 입력해야만 이 설치의 이름이 지정된 볼륨만 영구 삭제하며, --yes는 비대화형 확인입니다. Makefile 타깃도 같습니다. make down은 데이터를 보존하고 make down-all은 삭제합니다.
기본 .env가 부팅하는 것
체크아웃과 릴리스 번들의 .env 템플릿은 모두 단일 사용자 모드를 선택합니다. 릴리스 번들은 LOOM_IDENTITY_PROVIDER=single-user를 명시적으로 설정하고, 체크아웃은 비워 두고 LOOM_AUTH_REQUIRED=false로부터 같은 모드를 추론합니다.
| 설정 | 값 | 효과 |
|---|---|---|
LOOM_AUTH_REQUIRED=false, LOOM_IDENTITY_PROVIDER=single-user (또는 비어 있음) |
single-user |
로그인이 없습니다. 기본 네임스페이스는 dev/local입니다. SDK와 MCP 호출에 토큰이 필요 없습니다. |
LOOM_LLM_PROVIDER=fake, LOOM_LLM_MODEL=fake-echo-1 |
가짜 LLM | 추출, 엔티티 태깅, memory.ask 합성이 아무것도 만들지 않습니다. |
LOOM_EMBEDDING_MODEL=local, LOOM_EMBEDDING_DIM=384 (릴리스 번들) |
bge-small | 이미지에 포함된 모델 파일로 CPU에서 시맨틱 검색을 합니다. |
LOOM_EMBEDDING_MODEL=fake-ngram-3072, LOOM_EMBEDDING_DIM=3072 (체크아웃) |
가짜 임베더 | 검색이 문자 n-gram으로 순위를 매깁니다. 연결 확인에는 충분하지만 재현율 확인에는 부족합니다. |
두 설치 프로그램 모두 고유한 COMPOSE_PROJECT_NAME, 무작위 JWT 서명 비밀 값, 무작위 추출기 토큰, LOOM_BIND_HOST=127.0.0.1을 생성합니다. 따라서 별도의 클론이 ClickHouse 볼륨을 모르는 사이에 공유하지 않으며, Loom과 ClickHouse는 이 컴퓨터에서만 접근할 수 있습니다.
실제 프로바이더를 쓰려면 Settings → Models & keys를 열고, 프로바이더와 모델을 선택하고, API 키를 입력한 다음 Test & apply를 클릭하세요. OpenAI API 키 하나로 LLM과 임베딩을 모두 처리할 수 있습니다. Docker를 다시 시작할 필요는 없습니다. 임베딩을 변경하면 검증된 재빌드가 실행되며, 진행 상황과 재시도는 대시보드에 표시됩니다.
환경 변수 기반 배포를 원하면 ~/.loom/.env(릴리스 스택) 또는 .env(체크아웃)의 프로바이더 줄을 교체하세요. OPENAI_API_KEY만 설정해서는 아무것도 바뀌지 않습니다. 기본 프로바이더 줄이 프로바이더를 명시적으로 지정하기 때문입니다. 로컬 또는 가짜 임베더에서 다른 것으로 옮기면 저장된 내용이 다시 임베딩됩니다.
LOOM_EMBEDDING_MODEL=text-embedding-3-large
LOOM_EMBEDDING_DIM=3072
LOOM_LLM_PROVIDER=openai
LOOM_LLM_MODEL=gpt-6-luna
OPENAI_API_KEY=sk-...
Claude, OpenAI, 호스팅 임베딩, 구독 전용 클라이언트, LLM 프로바이더가 하나뿐인 배포는 모델과 API 키 설정을 따르세요. 릴리스 스택의 .env를 편집한 뒤에만 docker compose --project-directory "$HOME/.loom" up -d --force-recreate loom으로 적용하세요. 단순 재시작은 컨테이너의 환경을 다시 읽지 않습니다. 고급 설정은 배포 → 프로바이더에 있습니다.
스택 확인
curl -fsS http://localhost:7777/v1/health | jq '{status, fake_embedding, fake_llm, providers_degraded, problems}'
docker compose --project-directory "$HOME/.loom" exec loom loom doctor
/v1/health는 ClickHouse에 접근할 수 있고code_tier_failing(저장소의 코드 인덱스 티어 실패)을 제외한 어떤 문제도 오류가 아닐 때status: ok를 반환합니다.fake_embedding,fake_llm,providers_degraded는 현재 어떤 모드인지 알려 주고,problems는 각 문제와 해결 방법을 나열하며,schema.pending은 적용되지 않은 마이그레이션을 나열합니다.loom doctor는 서버 측 점검마다 한 줄씩 출력합니다.--json은 JSON을 출력합니다. 소스 체크아웃 스택에서는docker compose --env-file .env -f compose.yaml -f dev/docker-compose.dev.yml exec loom loom doctor를 실행하세요.
2. 대시보드 열기
http://localhost:7777/은 single-user 모드에서 대시보드로 바로 열립니다.
멀티 유저 모드에서는 먼저 가입하거나 로그인해야 합니다. single-user 모드에서는
대시보드와 에이전트의 기본값이 dev/local을 사용합니다(LOOM_DEFAULT_NAMESPACE로
네임스페이스 이름을 바꿀 수 있습니다). 이 모드는 편의를 위한 모드이며 사용자 격리 경계가 아닙니다. 서버에 접근할 수 있는 사람은 누구나 서버의 데이터와 관리 기능에 접근할 수 있습니다. localhost 전용으로만 사용하세요.
대신 가입 기능을 사용해 보려면(trust-network: 이메일과 비밀번호를 사용하며, 네임스페이스 이름을 가장 먼저 등록한 사람이 해당 네임스페이스의 관리자가 됩니다) ~/.loom/.env(릴리스 스택) 또는 .env(체크아웃)의 다음 항목을 교체하세요.
LOOM_IDENTITY_PROVIDER=trust-network
LOOM_AUTH_REQUIRED=true
LOOM_SELF_SIGNUP=open
single-user를 명시적으로 선택한 경우에는 LOOM_AUTH_REQUIRED=true만 설정해서는 충분하지 않습니다. 이 모드는 인증을 꺼 둔 상태로 유지합니다. 설치 프로그램이 생성한 LOOM_JWT_SECRET과 기존 볼륨은 그대로 두고, 서버를 다시 생성하여 환경 변수를 불러오세요.
# Released stack:
docker compose --project-directory "$HOME/.loom" up -d --force-recreate loom
# Checkout stack (run from the repository root):
docker compose --env-file .env -f compose.yaml -f dev/docker-compose.dev.yml --profile bundled up -d --force-recreate loom
그러면 대시보드는 Sign up 탭이 있는 로그인 페이지로 열리며, 모든 SDK 및 MCP 호출에는 토큰이 필요합니다. 아이덴티티 모드는 아이덴티티와 네임스페이스에서 확인할 수 있습니다. trust-network를 지정하면 루프백이 아닌 LOOM_BIND_HOST도 가입이 열린 상태로 시작할 수 있으며, 이 경우 해당 포트에 접근할 수 있는 누구나 가입할 수 있습니다. 팀이 서버에 접근할 수 있게 만들기 전에, 운영자 접근은 배포 가이드를, TLS는 해당 문서를 따르세요.
3. 토큰 발급받기
싱글 유저 모드에서는 토큰이 선택 사항입니다. 그래도 하나 발급해 두면 나중에 인증을 켰을 때 스크립트가 계속 동작합니다. 단, 스크립트가 org(또는 빈 값), namespace, agent를 직접 지정해야 합니다. SDK가 자격 증명을 찾아 보내는 경우(Python SDK → 자격 증명처럼) 자격 증명을 보내는 호출에는 이 값들이 하나도 자동으로 채워지지 않으며, 빈 org는 토큰 자체의 값이 됩니다.
- 대시보드: Settings → Tokens → New token. 기본적으로 토큰은 사용자가 속한 모든 네임스페이스와 리포지토리를 읽을 수 있고(제한된 리포지토리는 직접 추가한 경우에만), 컬렉션은 읽을 수 없으며, 현재 있는 네임스페이스에 저장합니다. Only what you choose 를 선택하면 체크한 네임스페이스, 컬렉션, 리포지토리로 범위가 제한됩니다(처음에는 아무것도 선택되어 있지 않습니다). 체크한 항목은 나열된 순서대로 검색되며, 행의 화살표로 순서를 바꾸거나 데스크톱에서는 행의 그립을 드래그해 바꿀 수 있습니다. 결과 화면에는 토큰이 한 번만 표시되며, MCP 클라이언트나 스크립트용 설정도 함께 나옵니다.
-
CLI, 운영자로서: 서명 시크릿을 가지고 있는 서버 컨테이너 안에서 실행합니다.
docker compose --project-directory "$HOME/.loom" exec loom loom mint-token --subject my-bot --org dev --namespaces local --roles writer머신 밖으로 나가는 토큰에는
--ttl-days 30을 추가하세요.loom mint-token --help에서 범위 지정 옵션(--namespace-role,--read-scope,--traffic-class)을 확인할 수 있습니다.
- 스스로 가입하는 봇 (trust-network 전용):
loom init --agent nightly-triage --server-url http://localhost:7777을 실행하면 네임스페이스agent-nightly-triage가 만들어지고, writer 토큰이~/.loom/token에, URL이~/.loom/config.json에 저장되며, 클레임 코드가 출력됩니다. 사람이/oauth/agent-claim에서 자신의 비밀번호로 이 코드를 한 번 입력하면 소유권을 가져갈 수 있습니다.
SDK, CLI, 플러그인이 찾는 위치에 토큰을 저장하세요.
mkdir -p ~/.loom && (umask 077; printf '%s' "<token>" > ~/.loom/token)
export LOOM_API_KEY="<token>"
클레임, 역할, 권한 부여는 토큰과 권한 부여에서 확인하세요.
4. HTTP로 첫 메모리 만들기
모든 연산은 JSON 본문을 담은 POST /v1/<op> 요청입니다. 설치 프로그램이나 체크아웃으로 설치한 기본 .env의 새 설치본은 단일 사용자 모드입니다. 토큰이 없고, org나 namespace를 지정하지 않는 일상적인 메모리 또는 검색 호출(memory.set, memory.get, memory.search 등)은 설치본 자체의 org dev, 네임스페이스 local에서 실행됩니다. 이는 MCP와 대시보드가 사용하는 값과 같습니다. agent를 지정하지 않은 memory.set은 에이전트 http로 기록되고, 검색은 모든 에이전트를 읽습니다. 따라서 아래 호출에는 각 호출 고유의 필드만 있으면 됩니다(해당 연산). 토큰 없이 호출했을 때 401 AUTH_INVALID가 반환되면 인증이 켜져 있는 것입니다. 이 경우 -H "Authorization: Bearer $LOOM_API_KEY"를 추가하고 계정의 org, namespace, agent를 지정하세요. 토큰이 비어 있는 헤더는 거부됩니다.
curl -sX POST http://localhost:7777/v1/memory.set -H 'Content-Type: application/json' \
-d '{"memory_key":"deploy_window","value":"Tue and Thu only; never Friday."}'
curl -sX POST http://localhost:7777/v1/memory.get -H 'Content-Type: application/json' \
-d '{"memory_key":"deploy_window"}' | jq '{found, value}'
curl -sX POST http://localhost:7777/v1/memory.search -H 'Content-Type: application/json' \
-d '{"query":"when can we deploy?"}' | jq '.results[0].content_excerpt'
memory.set 응답에는 memory_id, content_sha256, status가 들어 있습니다.
memory.get은 키 하나를 다시 읽어 옵니다. found는 해당 키에 유효한 값이 있는지를 나타내고, value는 기록된 그대로의 값입니다. 검색 응답에는 results와 abstain이 들어 있으며, 후자는 가장 좋은 결과가 답변의 근거로 삼을 만큼 충분히 강한지를 나타냅니다. 검색은 대시보드에서 추가한 메모리를 포함해 네임스페이스 안의 모든 에이전트의 메모리를 읽습니다. 특정 에이전트의 메모리만 읽으려면 agent를 지정하세요.
GET /v1/operations는 모든 연산을 나열하며, http://localhost:7777/docs에서는 브라우저로 각 연산을 직접 시험해 볼 수 있습니다. 요청과 응답 형식은 HTTP API 레퍼런스에 있습니다.
5. Python으로 첫 메모리 만들기
pip install clickhouse-loom # or, from a clone: pip install ./sdk/python
아직 PyPI에 올라오지 않은 릴리스는 해당 릴리스의 에셋으로 설치합니다 (GitHub Release에서 설치하기).
이 예제는 org와 namespace를 명시하므로, 3단계에서 만든 토큰이 있든 없든 동작합니다. SDK는 토큰을 찾으면 함께 전송합니다. 단일 사용자 서버에서는 토큰 없이 호출할 때 이 둘을 생략해도 됩니다. Agent(agent="quickstart", base_url=...)도 dev/local에서 실행됩니다.
import asyncio
from loom import Agent
async def main():
async with Agent(
org="dev",
namespace="local",
agent="quickstart", # names the writer in the audit log
base_url="http://localhost:7777",
) as a: # sends a credential it finds; none needed in single-user mode
await a.memory.set("standup_time", "Daily standup is at 9:30.")
row = await a.memory.get("standup_time") # None when the key is unset
print(row["value"] if row else "unset")
for hit in await a.memory.search("when is standup?"):
print(hit.content_excerpt)
asyncio.run(main())
SDK가 서버와 자격 증명을 찾는 방식은
Python SDK → 자격 증명에 있습니다.
TypeScript SDK는 npm install @clickhouse/loom으로 설치합니다
(클론에서 설치하기).
클라이언트 인터페이스는 Python SDK와 TypeScript SDK 레퍼런스에 정리되어 있습니다.
6. 코딩 에이전트로 첫 메모리 만들기
설치 프로그램이 에이전트를 이미 연결했다면 이 섹션의 마지막 문단으로 건너뛰세요.
Claude Code에서는 Loom 플러그인을 설치합니다. 플러그인은 MCP 도구 위에 훅(세션 시작 시 컨텍스트 로드, 세션 종료 시 캡처)과 스킬을 추가합니다:
claude plugin marketplace add ClickHouse/loom
claude plugin install loom@loom
이 머신의 단일 사용자 서버를 사용한다면, Claude Code가 플러그인 설정을 물을 때 기본 서버 URL을 그대로 두고 토큰은 비워 두세요.
플러그인 없이 MCP 항목을 직접 추가할 수도 있습니다:
claude mcp add --transport http loom "http://localhost:7777/mcp?toolset=coding" -s user
두 방법 모두 별도의 토큰 없이 이 머신의 단일 사용자 서버에 연결됩니다.
인증이 켜져 있다면 Settings → Tokens에서 토큰을 만들고 Connect 아래의 Claude Code를 선택하세요. 대화상자에 플러그인용 설정과 토큰이 포함된 claude mcp add 항목용 설정이 표시됩니다. 그런 다음 다음을 진행합니다.
~/.loom/config.json을 대화상자의config.json블록과 토큰이 저장될 네임스페이스("namespace": "<namespace>")로 덮어쓰세요. 단일 사용자 세션에서 파일에 남긴org또는namespace는 토큰보다 우선하며, 이 값이 없으면 플러그인은*가 아닌 토큰의 첫 번째 네임스페이스나coding에 기록합니다. 이전에 설정한code_repo나agent가 있다면 다시 추가하세요.LOOM_API_KEY(3단계에서 설정했을 수 있습니다:unset LOOM_API_KEY)와 플러그인의token옵션은 비워 두거나 새 토큰으로 설정하세요. 플러그인은 두 값을 그 파일보다 먼저 읽습니다 (구성).- 토큰 없이 만든
claude mcp add항목은 대화상자의 명령을 실행하기 전에 제거하세요(claude mcp remove loom -s user). 대화상자의 명령은 이미 존재하는 이름을 거부합니다.
loom install --client <name>은 Claude Desktop, Claude Code, Codex, Cursor, VS Code, Cline, Windsurf, Zed용 MCP 항목을 작성합니다. 플래그를 생략하면 발견한 모든 클라이언트를 연결합니다. Codex와 Cursor는 코딩 에이전트 연결에서 다룹니다.
새 세션을 시작하고 "Remember that I never deploy on Friday." 라고 말해 보세요. 에이전트가 loom_memory_set을 호출합니다. 새 세션에서 "When can I deploy?" 라고 물으면 에이전트가 loom_search를 호출하고 저장된 사실을 바탕으로 답합니다. 저장하고 검색할 시점은 모델이 도구 설명을 보고 판단하며, 별도의 트리거 단어는 없습니다.
7. 대시보드에서 확인하기
| 페이지 | 표시 내용 |
|---|---|
/memories |
네임스페이스의 메모리를 작성자와 시간과 함께 보여줍니다. |
/admin/activity |
감사 로그: 어떤 에이전트가 어떤 키를 언제 기록했는지 보여줍니다. |
/admin/usage |
작업별, 에이전트별 비용을 보여줍니다. |
나머지는 대시보드에서 확인할 수 있습니다.
선택 사항: 릴리스된 스택에서 리포지토리 인덱싱하기
이 스택에서는 대시보드에서 리포지토리를 추가하면 SANDBOX_UNAVAILABLE로 거부됩니다.
리포지토리 작업 샌드박스가 필요한데,
Docker의 기본 격리가 이를 막기 때문에 이 스택은 샌드박스를 꺼 둡니다. 신뢰할 수 있는 리포지토리만
등록하세요. 빌드 단계(TypeScript 설치, Go 모듈 다운로드, CMake)는 샌드박스 없이 loom 컨테이너에서
실행되며, 이 컨테이너의 환경에는 JWT 시크릿과 프로바이더 키가 들어 있습니다.
LOOM_CODE_REPOS_JSON은 모든 리포지토리를 JSON 배열로 담은 한 줄입니다
(항목 구성하기).
~/.loom/.env에서 해당 줄의 주석을 해제하고(없으면 추가하고) 수정하세요.
dev는 단일 사용자 스택이 실행되는 org이자, 다중 사용자 계정이 가입하는 org입니다(LOOM_SELF_SIGNUP_ORG).
이 값을 바꿨다면 여기와 아래 --org에 계정의 org를 사용하세요.
LOOM_CODE_REPOS_JSON=[{"org":"dev","namespace":"code-myrepo","repo":"acme/myrepo","git_branch":"main","public":true}]
- Loom은 리포지토리의 빌드 파일(
go.mod,package.json,pyproject.toml, 루트의CMakeLists.txt등)을 보고 컴파일러 티어 인덱서를 고릅니다. 대신scip_producer로 하나를 직접 지정할 수도 있습니다 (컴파일러 티어). C/C++는 구성된 빌드 트리도 필요하므로, 빌드 트리가 없으면 C/C++ 리포지토리는 파서 티어만 적용됩니다. - 비공개 리포지토리라면 GitHub 토큰을 추가하고(
.env의LOOM_CODE_GITHUB_TOKEN또는 항목의github_token)"public":true를 빼세요. 이 값은 호스트에서 공개된 리포지토리용이며, org의 누구나 Repositories에서 바로 리더로 인덱스에 참여할 수 있게 합니다. 첫loom code init전에 결정하세요. 이 명령은public을 보고 네임스페이스의 참여 정책을 정하며, 이후public을 수정해도 정책은 바뀌지 않습니다(메인테이너는code.repo.set_access로 변경합니다).
그런 다음 loom 컨테이너를 다시 만들고 첫 인덱싱을 실행합니다.
docker compose --project-directory "$HOME/.loom" up -d --force-recreate loom
docker compose --project-directory "$HOME/.loom" exec loom loom code init --namespace code-myrepo --org dev
docker compose --project-directory "$HOME/.loom" exec loom loom code backfill --namespace code-myrepo --org dev --embed
backfill --embed는 릴리스된 스택의 로컬 임베더에서 실행됩니다. 가짜 임베더를 쓰는 경우(체크아웃의
.env, 또는 여전히 fake-ngram-*를 지정한 업그레이드된 설치) 거부하고 종료합니다. 그래도 연결을
시험하려면 --allow-fake-embedder를 추가하세요. 나중에 Settings → Models & keys에서 모델을
선택하면 코드 인덱스가 다시 임베딩됩니다. .env를 변경한 뒤에는 별도의 재임베딩이 필요하며,
자세한 내용은 모델과 키를 참고하세요.
다중 사용자 모드에서는 등록된 리포지토리에 메인테이너가 없으므로, "public":true가 없으면 리더의
참여 요청을 승인할 사람이 없어 대기 상태로 남습니다. loom code init 후에 운영자로서 컨테이너에서
발급한 토큰으로 누군가에게 접근 권한을 부여하세요. admin은 이후 리더를 승인하는 메인테이너로 만들고,
viewer는 읽기만 허용합니다. subject는 계정이 가입할 때 쓴 네임스페이스(로그인 핸들이자 토큰의
subject)입니다. 자체 가입 이메일은 검증되지 않으므로, 이메일에 부여한 권한으로는 아무도 들어올 수 없습니다.
ADMIN_TOKEN=$(docker compose --project-directory "$HOME/.loom" exec -T loom loom mint-token --subject operator --org dev --namespaces code-myrepo --roles admin --ttl-days 1)
curl -s http://localhost:7777/v1/grants.create -H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{"org":"dev","namespace":"code-myrepo","subject":"your-namespace","role":"admin"}'
선택 사항: 문서에 대해 질문하기
loom demo
loom demo는 이 저장소의 AGENTS.md를 업로드하고, knowledge.ingest로 수집한 뒤(스택의 레퍼런스 추출기가 파싱합니다) knowledge.synthesize로 문서에 대한 질문을 던져 답변과 그 답변이 인용한 청크를 출력합니다. 가짜 LLM을 사용하는 경우에는 대신 상위 knowledge.search 결과를 출력합니다. --file과 --question으로 직접 가진 문서와 질문을 지정할 수 있습니다.
자주 발생하는 문제
| 증상 | 원인과 해결 방법 |
|---|---|
set_from_messages가 사실(fact)을 기록하지 않음 |
LLM이 가짜(fake) 모델입니다. 모델과 키를 따라 LLM을 설정하세요. |
| 검색 결과가 제멋대로임 | 임베더가 가짜입니다(.env의 fake-ngram-*). 모델과 키의 안내대로 바꾸면 저장된 데이터가 다시 임베딩됩니다. 모델을 바꾸려고 볼륨을 삭제하지 마세요. |
인증을 켠 뒤 401 AUTH_INVALID 발생 |
토큰이 없거나 다른 LOOM_JWT_SECRET으로 서명된 토큰입니다. 토큰 발급의 Compose 명령으로 다시 발급하세요. |
| 대시보드가 503을 반환함 | 서버를 소스에서(make server) 실행했는데 프런트엔드가 빌드되지 않았습니다. make frontend-build를 실행하세요. |
| 릴리스 스택이 정상 상태가 되지 않음 | docker compose --project-directory "$HOME/.loom" logs --tail 100 loom clickhouse를 실행하세요. 문제 해결을 참고하세요. |
리포지토리를 추가하면 SANDBOX_UNAVAILABLE이 반환됨 |
스택이 리포지토리 작업 샌드박스 없이 실행 중입니다. LOOM_CODE_REPOS_JSON으로 리포지토리를 인덱싱하세요(리포지토리 인덱싱). |
설치 프로그램이 7777 포트가 사용 중이라고 함 |
다른 프로그램이나 다른 Loom이 해당 포트에서 대기 중입니다. 그것을 중지하거나, sh loom-install.sh 앞에 LOOM_PORT=7778을 붙여 설치 명령을 다시 실행하세요. .env에 포트가 유지됩니다. |
설치 프로그램이 7777 포트가 응답하지 않는다고 함 |
어떤 프로그램이 응답 없이 포트를 점유하고 있거나, LOOM_BIND_HOST, LOOM_PORT 또는 방화벽 때문에 이 호스트가 포트에 접근하지 못합니다. |
설치 프로그램이 7777 포트를 확인하지 못함 |
curl이 종료 코드가 나타내는 이유로 실패했습니다. LOOM_BIND_HOST와 LOOM_PORT를 확인하세요. |
WSL의 Docker Desktop에서 설치가 Ports are not available로 중단됨 |
Windows가 포트를 점유하거나 예약해 두었고, WSL 내부의 설치 프로그램 검사로는 이를 알 수 없습니다. netsh interface ipv4 show excludedportrange protocol=tcp로 예약된 범위를 확인한 뒤, sh loom-install.sh 앞에 해당 범위를 벗어난 LOOM_PORT를 붙여 설치 명령을 다시 실행하세요. |
클론한 저장소에서 8123 또는 9000 포트가 이미 사용 중임 |
ClickHouse 호스트 포트를 다시 매핑하세요(로컬 스택). |
| 설치 프로그램이 이미지를 가져오지 못함 | Docker가 레지스트리에 직접 접근해야 합니다. 프록시 뒤에 있다면 Docker 데몬에 프록시 설정을 지정하세요. |
다음 단계
- Loom 평가하기: 이 스모크 테스트를 워크로드별 품질, 지연 시간, 비용 평가로 발전시킵니다.
- 코딩 에이전트 연결하기: 이 스택에 Claude Code, Codex 또는 Cursor를 연결합니다.
- 첫 에이전트 만들기: SDK로 ID, abstain 처리, 세션, 컨텍스트 팩, 실행을 다룹니다.
- 배포: 팀을 위해 Loom을 운영합니다.