> Source: https://clickhouse.github.io/loom/es/getting-started/quickstart/ (Markdown: https://clickhouse.github.io/loom/es/getting-started/quickstart.md)

> El original en inglés ha cambiado desde esta traducción automática. Consulta la [página en inglés](https://clickhouse.github.io/loom/getting-started/quickstart/) para ver las instrucciones actuales.

<!-- i18n: source=docs/getting-started/quickstart.md blob=b72e7d36e1a9ffeaac7023befecdecef5ef6303b model=claude-sonnet-5-5 -->
> Esta página es una traducción automática de la [página en inglés](https://clickhouse.github.io/loom/getting-started/quickstart/), que prevalece.
> Machine-translated from the [English page](https://clickhouse.github.io/loom/getting-started/quickstart/), which is authoritative.

<a id="quickstart"></a>

# Inicio rápido

Esta página pone en marcha Loom en un portátil y guarda una primera memoria por HTTP, Python y MCP. No
necesita ninguna API key ni cuenta. Una instalación nueva del stack publicado genera embeddings con un pequeño
modelo local que incluye la imagen, de modo que la búsqueda devuelve resultados relevantes sin red (una
instalación actualizada conserva el embedder que indica su `.env`); su LLM es falso, así que la extracción y
las respuestas de `memory.ask` no producen nada. El `.env` de un checkout usa proveedores falsos para ambos.

**La instalación estándar de Docker es de un solo usuario:** sin inicio de sesión, con acceso solo desde localhost y
un espacio de nombres `dev/local` por defecto. Una persona puede conectar varios agentes sin activar el
modo multiusuario. **Los despliegues para equipos también son compatibles en OSS**, con cuentas
autenticadas y controles de acceso a los espacios de nombres; [empieza en modo multiusuario](#start-in-multi-user-mode)
o sigue [Despliegue → Modos de identidad](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#identity-modes).
Ambos modos admiten las mismas funciones de Loom; los LLM y embeddings reales requieren configurar proveedores
en cualquiera de los dos modos.

<a id="prerequisites"></a>

## Requisitos previos

| Necesidad                         | Para                                                                                       |
| --------------------------------- | ------------------------------------------------------------------------------------------ |
| Docker con el plugin compose      | El stack: ClickHouse y el servidor de Loom.                                                |
| Python 3.12 o superior            | CLI `loom` solo para contribuidores. El SDK admite 3.11+.                                  |
| Node.js 20 o superior             | El SDK de TypeScript (opcional).                                                           |
| Puerto libre `7777`               | Loom. El desarrollo desde el checkout también expone ClickHouse en `8123` y `9000`.        |
| `jq`                              | Leer la salida de `curl` en el paso 4 (opcional).                                          |

<a id="1-boot-the-stack"></a>

## 1. Arrancar el stack

<a id="fast-path-released-image-no-clone"></a>

### Camino rápido: imagen publicada, sin clonar

Requisito previo: Docker Desktop o Docker Engine con Compose 2.20 o posterior. En Windows, ejecuta
el comando en una terminal de WSL 2 donde `docker` funcione: Docker Desktop con su integración
con WSL activada para esa distribución, o Docker Engine instalado en ella. El
instalador es un script de shell POSIX.

```bash
curl -fsSL https://github.com/ClickHouse/loom/releases/latest/download/install.sh -o loom-install.sh && sh loom-install.sh && rm loom-install.sh
```

El comando guarda el instalador en el directorio actual y después ejecuta ese archivo, así que ejecútalo
desde tu directorio personal, o desde otro directorio en el que solo tú puedas escribir: en uno compartido,
otra persona puede reemplazar `loom-install.sh`, o apuntarlo a otro archivo, antes de que se ejecute. Una
descarga fallida se detiene con el error de curl y un código de salida distinto de cero; tras una instalación fallida, corrige
lo que informe y vuelve a ejecutar el comando completo. El instalador descarga
`loom-stack.tar.gz` de la última GitHub Release, verifica su SHA-256, instala la
configuración de Compose y de ClickHouse en `~/.loom`, descarga las imágenes correspondientes
`ghcr.io/clickhouse/loom:X.Y.Z` y `ghcr.io/clickhouse/loom-extractor:X.Y.Z` (el
servicio extractor de documentos) y espera a `http://localhost:7777/v1/health`. La imagen
del servidor contiene la API, los workers, las migraciones y el dashboard de React ya compilado en la raíz
del servidor; no hace falta instalar Python ni Node. Los indexadores del compilador para Python, TypeScript y Go
están incluidos y habilitados, y también el de C++ (`scip-clang`) en `amd64`. Un
repositorio indexado con el indexador de TypeScript recibe sus dependencias instaladas
automáticamente. Ambas imágenes son compatibles con Linux `amd64` y `arm64`, incluido Docker Desktop
en Apple Silicon.

Una vez que Loom responde, el instalador:

1. **Comprueba una memoria.** Una instalación nueva guarda una memoria de prueba, la lee de nuevo y la elimina,
   lo que demuestra que las escrituras y lecturas funcionan y no deja ninguna memoria activa (su versión eliminada
   aparece en Eliminadas recientemente). Una nueva ejecución después de que esa comprobación haya pasado, o una actualización, la omite.
2. **Averigua si el inicio de sesión está activado.** Con el inicio de sesión activado, no conecta ningún agente e indica de dónde
   salen los tokens.
3. **Ofrece conectar tus agentes de programación.** En una terminal pregunta, por cada uno que encuentra:
   Claude Code y Codex mediante sus plugins, VS Code mediante `code --add-mcp`.
   `LOOM_CONNECT` responde en su lugar, también en una ejecución sin terminal, y solo se examinan los clientes
   que nombra: una lista separada por comas de `claude-code`, `codex` y `vscode`, `all`, o
   `none` solo; cualquier otro valor detiene la instalación. Sin terminal y sin
   `LOOM_CONNECT`, no se examina ni se modifica ningún agente. Un plugin o servidor MCP configurado antes
   (por el plugin, `claude mcp add`, `codex mcp add` o `loom install`) se deja como está;
   para un plugin de Claude Code el instalador imprime el comando que lo apunta a esta
   instalación. El plugin de Claude Code ejecuta el Node.js 18 o posterior que esté en el PATH, así que si no hay uno
   el instalador no instala ningún plugin e imprime la línea `claude mcp add` solo para el servidor MCP;
   el de Codex encuentra Node.js también mediante nvm y similares, así que se instala, con la
   línea `codex mcp add` junto a él. El plugin de Codex siempre usa `http://localhost:7777`, así
   que para una instalación en otro lugar recibe un enlace a su página de configuración. VS Code no se
   ofrece en una sesión remota ni en WSL. Se avisa de un cliente que `LOOM_CONNECT` nombra y que no está en el PATH.
4. **Abre el dashboard** en un escritorio, en una instalación nueva; `LOOM_NO_OPEN=1` lo omite.

Antes de iniciar Loom, a una instalación nueva en una terminal con Ollama respondiendo en
`localhost:11434` también se le pregunta si ejecutar en él los trabajos de modelo de Loom (extracción, y
el asistente una vez habilitado), sin clave de API; `LOOM_LOCAL_MODELS=ollama` responde que sí
y `off` que no
([un servidor de modelos en tu máquina](https://github.com/ClickHouse/loom/blob/main/docs/getting-started/models-and-keys.md#a-model-server-on-your-machine-no-api-key)).

Si se ejecuta desde WSL, estos pasos actúan dentro de WSL: conecta un agente que se ejecute en Windows desde
Windows con la [guía de conexión](https://github.com/ClickHouse/loom/blob/main/docs/getting-started/connect-a-coding-agent.md), y abre la dirección del dashboard
que imprime el instalador en un navegador de Windows.

Ctrl-C detiene la ejecución en cualquier paso; un clon que la CLI de un agente inició para su plugin puede
terminar igualmente en segundo plano.

El stack ejecuta su propio contenedor de ClickHouse. Para usar un ClickHouse que ya tengas en marcha, un
servidor autogestionado o un servicio de ClickHouse Cloud (26.4 o posterior, con un Keeper), indica su
URL; el instalador pide la contraseña cuando la URL no la tiene, crea la base de datos `loom`
y un usuario lector de solo lectura, o imprime el SQL que debe ejecutar un administrador
([elegir el ClickHouse](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#choosing-the-clickhouse)):

```bash
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
```

El `install.sh` de cada versión instala esa versión, así que la copia que sirve `latest` instala la
última versión, y la URL propia de una versión, más abajo, instala esa versión siempre. Sobre una instalación
más reciente, la copia de una versión anterior se niega a instalar, en lugar de arrancar un Loom y
un ClickHouse más antiguos sobre datos más nuevos; para volver a una versión anterior a propósito, sigue
[volver a una versión anterior de una instalación con instalador](https://github.com/ClickHouse/loom/blob/main/docs/operations/upgrades.md#downgrading-an-installer-install).
Para fijar una versión, usa su propia URL:

```bash
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
```

Para inspeccionar todo antes de empezar, descarga los archivos y compruébalos:

```bash
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
```

Después, cuando lo que imprimen te parezca correcto, instala desde el paquete comprobado:

```bash
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`
y `LOOM_CLICKHOUSE_IMAGE` que se pasen al instalador se escriben en el `.env` del directorio de instalación,
de modo que los comandos `docker compose` posteriores allí y las ejecuciones posteriores del instalador usen el mismo
puerto e imágenes. Un `LOOM_BIND_HOST` distinto de loopback publica Loom más allá de este host,
y el servidor se niega a arrancar así sin `LOOM_PUBLIC_BASE_URL` y sin inicio de sesión:
instala con `LOOM_SKIP_START=1`, defínelos en `.env` (más abajo) y vuelve a ejecutar el comando de instalación
sin `LOOM_SKIP_START=1`.

Cada versión ejecuta la versión de ClickHouse que era la más reciente cuando se compiló, así que volver a ejecutar el
comando de instalación para la misma versión de Loom mantiene su ClickHouse; instalar una versión más reciente de
Loom lo cambia, a menos que `.env` fije `LOOM_CLICKHOUSE_IMAGE` (borra esa línea para
volver a seguir las versiones). Volver a ejecutar el comando de instalación actualiza los archivos de
Compose y de configuración gestionados y reconcilia los contenedores. Conserva `~/.loom/.env`,
añadiendo la URL del extractor y un token a uno que no los tenga, y los volúmenes con nombre de Docker. Para
detener sin borrar datos:

```bash
docker compose --project-directory "$HOME/.loom" down
```

Añade `--volumes` solo para un reinicio intencionado e irreversible.

<a id="try-it-in-github-codespaces"></a>

### Pruébalo en GitHub Codespaces

[![Abrir en GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/ClickHouse/loom?quickstart=1)

El dev container del repositorio ejecuta la última versión en un codespace, sin nada en
tu máquina: instala Loom con el instalador de arriba, lo inicia y conecta Claude
Code a él. El primer arranque descarga unos 3 GB de imágenes y tarda unos minutos. Abre
el dashboard en la dirección que imprimen las últimas líneas del registro de creación (`Loom is running in the
codespace. Dashboard: https://<codespace name>-7777.app.github.dev`, la dirección
reenviada de la pestaña **Ports** para el puerto 7777); el `http://127.0.0.1:7777/` del instalador que aparece encima es la
dirección propia del codespace. En la terminal del codespace, ejecuta `cd ~ && claude` (fuera del
checkout, cuyas instrucciones son para trabajar en el propio Loom), inicia sesión y di "Remember
that I never deploy on Friday"; en una nueva sesión de `claude`, pregunta "When can I deploy?".

La prueba se ejecuta en modo de un solo usuario, sin inicio de sesión. En el navegador, el puerto 7777 se reenvía
de forma privada: su dirección solo responde a tu cuenta de GitHub. Mantenlo privado: hacerlo público, o
privado para una organización, abre un servidor sin inicio de sesión a todos con quienes se comparta.
Los agentes dentro del codespace, como su `claude`, usan `http://localhost:7777`; las líneas de conexión
del dashboard nombran en su lugar la dirección reenviada, que necesita un inicio de sesión de GitHub
que los agentes del codespace no tienen. Abierto en VS Code de escritorio, el codespace
también reenvía el puerto al `localhost:7777` de tu portátil, donde está tan abierto como una instalación
local para todos los programas del portátil, y los agentes del portátil pueden llegar a él allí; el
reenvío necesita que ese puerto local esté libre, así que detén primero un Loom local. Usa el dashboard desde la
dirección del navegador: desde el `localhost:7777` del portátil la página se abre, pero el servidor rechaza
sus peticiones, así que no muestra datos; solo la dirección reenviada es la página propia de este servidor.

La instalación vive en `/workspaces/.loom`, así que un codespace reconstruido conserva su `.env` y su
proyecto de Compose, aunque sus memorias viven en volúmenes de Docker que una reconstrucción puede no conservar; una
reconstrucción también ejecuta sobre él el instalador de la última versión, lo que lo mueve a esa versión.
Dondequiera que estos documentos nombren `~/.loom` o `"$HOME/.loom"`, un codespace usa
`/workspaces/.loom`. Codespaces ofrece abrir el puerto 7777 en cuanto escucha; el
dashboard responde cuando el registro de creación imprime "Loom is running in the codespace". Si el
registro termina con un error, ejecuta `sh .devcontainer/start-loom.sh` en la terminal
del codespace: conserva lo que configuró la primera ejecución.

<a id="start-in-multi-user-mode"></a>

### Iniciar en modo multiusuario

Para una instalación nueva con imagen publicada, con cuentas e inicio de sesión desde el primer arranque,
prepara los archivos del stack sin iniciar contenedores:

```bash
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
```

Edita `~/.loom/.env` antes de iniciar Docker. Reemplaza las entradas existentes de identidad y autenticación,
y añade el ajuste de registro:

```dotenv
LOOM_IDENTITY_PROVIDER=trust-network
LOOM_AUTH_REQUIRED=true
LOOM_SELF_SIGNUP=open
```

Conserva los `COMPOSE_PROJECT_NAME` y `LOOM_JWT_SECRET` generados. Después descarga e inicia
el stack (con tu propio ClickHouse, ejecuta antes `ch-setup`, como indicó el instalador):

```bash
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
```

Cuando pasen las [comprobaciones de estado](#check-the-stack), abre `http://localhost:7777/` y
regístrate. Los clientes del SDK y de MCP necesitan tokens; usa la organización y los espacios de nombres concedidos a tu
cuenta, no los valores predeterminados de un solo usuario `dev/local` de los ejemplos siguientes.

Esto habilita la autenticación multiusuario, no la red pública: el stack sigue enlazado
a localhost. Antes de compartirlo con un equipo, configura el [acceso de operador](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#identity-modes)
y [TLS](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#proxy-and-tls). Configura también los [modelos reales y las claves de API](https://github.com/ClickHouse/loom/blob/main/docs/getting-started/models-and-keys.md);
seleccionar el modo multiusuario no sustituye al LLM falso.

Para un stack de un solo usuario que ya está en marcha, sigue en cambio las [instrucciones para cambiar](#2-open-the-dashboard);
recrear los contenedores conserva los volúmenes de datos existentes.

<a id="contributor-path-build-a-checkout"></a>

### Camino del colaborador: compilar un checkout

Requisito previo: Docker Compose 2.34 o posterior, que el archivo compose del checkout necesita para
descargar ClickHouse a diario.

```bash
git clone https://github.com/ClickHouse/loom && cd loom
python3 -m venv .venv && . .venv/bin/activate
pip install -e .
loom up
```

`loom up` hace tres cosas:

1. Crea los dos archivos que git no rastrea: `.env` a partir de `.env.example`, y
   `deploy/clickhouse-config/named_collections.xml` a partir de su plantilla. Nunca
   sobrescribe ninguno; a un `.env` existente sin token del extractor le da uno.
2. Ejecuta el stack compose de desarrollo con `--build`.
3. Consulta `http://localhost:7777/v1/health` hasta que el servidor esté listo, imprimiendo el número
   de migraciones pendientes. Se rinde tras `--timeout` (300 s) con el último cuerpo
   de health y las últimas líneas del registro.

El primer arranque de colaborador compila la imagen y aplica todas las migraciones de esquema, así que calcula
unos minutos. Después `loom up` imprime la URL del dashboard (`http://localhost:7777/`), una llamada `curl`
y un fragmento de Python que guardan una primera memoria, y una línea que conecta Claude Code.
Cuando la autenticación está activada, también genera un token de escritor y lo incluye en esos fragmentos.

| Flag         | Qué hace                                    |
| ------------ | ------------------------------------------- |
| `--rebuild`  | Recompila tras un cambio de código.         |
| `--no-build` | Reutiliza la imagen en caché.               |
| `--open`     | Abre el dashboard.                          |
| `--port`     | Usa otro puerto de Loom.                    |
| `--env-file` | Apunta a otro archivo env.                  |

Volver a ejecutar `loom up` sobre un stack en marcha solo vuelve a comprobar el estado. `make dev` hace lo mismo
sin la CLI y ejecuta:

```bash
docker compose --env-file .env -f compose.yaml -f dev/docker-compose.dev.yml --profile bundled up -d --build
```

Con `compose.yaml` primero, Compose lee el `.env` de la raíz del repositorio para las sustituciones
`${VAR:-default}`; `--env-file .env` solo lo indica explícitamente. `loom down`
detiene el stack y conserva sus volúmenes. `loom down --delete-data` elimina de forma permanente
solo los volúmenes con nombre de esta instalación después de que escribas el nombre generado del proyecto de
Compose; `--yes` es la confirmación no interactiva. Los targets del Makefile
hacen lo mismo: `make down` conserva los datos y `make down-all` los elimina.

<a id="what-the-stock-env-boots"></a>

### Qué arranca el `.env` por defecto

Las plantillas `.env` del checkout y del paquete de versión seleccionan ambas el modo de un solo usuario.
El paquete de versión define `LOOM_IDENTITY_PROVIDER=single-user` explícitamente; el checkout
lo deja vacío e infiere el mismo modo a partir de `LOOM_AUTH_REQUIRED=false`.

| Ajuste                                                                       | Valor         | Efecto                                                                    |
| ---------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------- |
| `LOOM_AUTH_REQUIRED=false`, `LOOM_IDENTITY_PROVIDER=single-user` (o vacío)   | `single-user` | Sin inicio de sesión. Espacio de nombres predeterminado `dev/local`. Las llamadas del SDK y de MCP no necesitan token. |
| `LOOM_LLM_PROVIDER=fake`, `LOOM_LLM_MODEL=fake-echo-1`                       | LLM falso     | La extracción, el etiquetado de entidades y la síntesis de `memory.ask` no producen nada. |
| `LOOM_EMBEDDING_MODEL=local`, `LOOM_EMBEDDING_DIM=384` (paquete de versión)  | bge-small     | Búsqueda semántica en CPU, a partir de los archivos de modelo que lleva la imagen. |
| `LOOM_EMBEDDING_MODEL=fake-ngram-3072`, `LOOM_EMBEDDING_DIM=3072` (checkout) | embedder falso | La búsqueda ordena por n-gramas de caracteres. Basta para comprobar el cableado, no la recuperación. |

Ambos instaladores generan un `COMPOSE_PROJECT_NAME` único, un secreto aleatorio de firma JWT, un
token aleatorio del extractor y `LOOM_BIND_HOST=127.0.0.1`. Por tanto, clones distintos no comparten
volúmenes de ClickHouse sin avisar, y Loom y ClickHouse solo son accesibles desde este
equipo.

Para usar proveedores reales, abre **Settings → Models & keys**, elige tus proveedores y modelos,
introduce sus claves de API y haz clic en **Test & apply**. Una sola clave de API de OpenAI puede servir tanto al
LLM como a los embeddings. No hace falta reiniciar Docker; los cambios de embeddings activan una
reconstrucción verificada, con el progreso y el reintento visibles en el dashboard.

Para un despliegue basado en variables de entorno, reemplaza las líneas de proveedor en `~/.loom/.env`
(stack publicado) o en `.env` (checkout). Definir solo `OPENAI_API_KEY` no cambia nada:
las líneas de proveedor por defecto nombran sus proveedores explícitamente. Pasar del embedder local o falso
vuelve a calcular los embeddings de lo almacenado.

```bash
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-...
```

Para Claude, OpenAI, embeddings alojados, clientes solo con suscripción y despliegues con
un único proveedor de LLM, sigue [Configurar modelos y claves de API](https://github.com/ClickHouse/loom/blob/main/docs/getting-started/models-and-keys.md).
Solo después de editar el `.env` del stack publicado, aplícalo con
`docker compose --project-directory "$HOME/.loom" up -d --force-recreate loom`;
un simple reinicio no recarga el entorno del contenedor. Los ajustes avanzados están en
[Despliegue → Proveedores](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#providers).

<a id="check-the-stack"></a>

### Comprobar el stack

```bash
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` devuelve `status: ok` cuando ClickHouse es accesible y ningún problema distinto
  de `code_tier_failing` (el fallo de un nivel del índice de código de un repositorio) es un error.
  `fake_embedding`, `fake_llm` y `providers_degraded` indican en qué modo estás;
  `problems` lista cada incidencia con su solución; `schema.pending` lista las migraciones sin aplicar.
- `loom doctor` imprime una línea por cada comprobación del lado del servidor. `--json` da JSON. Desde un stack
  de checkout de código fuente, ejecuta `docker compose --env-file .env -f compose.yaml -f dev/docker-compose.dev.yml exec loom loom doctor`.

<a id="2-open-the-dashboard"></a>

## 2. Abre el dashboard

`http://localhost:7777/` abre directamente el dashboard en modo `single-user`;
en modo multiusuario, primero regístrate o inicia sesión. En modo `single-user`
el dashboard y los valores predeterminados del agente usan `dev/local` (`LOOM_DEFAULT_NAMESPACE` cambia el nombre del
espacio de nombres). Este es un modo de conveniencia, no un límite de aislamiento entre usuarios: cualquiera que pueda
acceder al servidor puede acceder a sus datos y a la administración. Mantenlo solo en localhost.

Para probar el registro en su lugar (`trust-network`: correo electrónico y contraseña, y la primera persona que
reclame el nombre de un espacio de nombres se convierte en su administrador), reemplaza estas entradas en `~/.loom/.env`
(stack publicado) o en `.env` (checkout):

```dotenv
LOOM_IDENTITY_PROVIDER=trust-network
LOOM_AUTH_REQUIRED=true
LOOM_SELF_SIGNUP=open
```

Configurar solo `LOOM_AUTH_REQUIRED=true` no es suficiente cuando `single-user` se selecciona explícitamente:
ese modo mantiene la autenticación desactivada. Conserva el `LOOM_JWT_SECRET` generado por el instalador y los volúmenes existentes, y luego recrea el servidor para cargar el entorno:

```bash
# 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
```

Entonces el dashboard se abre en su página de inicio de sesión, que tiene una pestaña **Sign up**, y cada llamada del SDK
y de MCP necesita un token. Los modos de identidad se describen en [Identidades y espacios de
nombres](https://github.com/ClickHouse/loom/blob/main/docs/concepts/identities-and-namespaces.md#identity-modes). Indicar
`trust-network` es también lo que permite que un `LOOM_BIND_HOST` que no sea loopback arranque con el registro abierto,
de modo que cualquiera que llegue al puerto podrá registrarse. Antes de hacer que el servidor sea accesible para un
equipo, sigue la [guía de despliegue](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#identity-modes) para
el acceso de operadores y [TLS](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#proxy-and-tls).

<a id="3-get-a-token"></a>

## 3. Obtener un token

En modo de un solo usuario un token es opcional. Generar uno de todos modos mantiene tus scripts funcionando
cuando se activa la autenticación, siempre que indiquen su `org` (o la envíen en blanco), `namespace`
y `agent`: una llamada que envía una credencial, como hace el SDK cuando encuentra alguna ([SDK de Python
→ Credenciales](https://github.com/ClickHouse/loom/blob/main/docs/reference/python-sdk.md#credentials)), no recibe ninguno de ellos completado,
y una `org` en blanco es la propia del token.

- **Dashboard:** **Settings → Tokens → New token**. De forma predeterminada, el token lee todos los
  espacios de nombres y repositorios a los que perteneces (un repositorio restringido solo cuando lo añades),
  pero ninguna colección, y guarda en el espacio de nombres en el que estás. _Only what you choose_ lo limita
  a los espacios de nombres, colecciones y repositorios que marques (ninguno al principio); los marcados
  se buscan en el orden indicado, y lo cambias con las flechas de una fila o, en un
  ordenador de escritorio, arrastrando el asa de la fila. El resultado muestra el token una sola vez, con la configuración para
  tu cliente MCP o un script.
- **CLI, como operador:** ejecútalo dentro del contenedor del servidor, que guarda el secreto
  de firma:

  ```bash
  docker compose --project-directory "$HOME/.loom" exec loom loom mint-token --subject my-bot --org dev --namespaces local --roles writer
  ```

  Añade `--ttl-days 30` para cualquier token que salga de tu máquina. `loom mint-token --help`
  muestra las opciones de alcance (`--namespace-role`, `--read-scope`, `--traffic-class`).

- **Un bot que se registra solo** (solo en redes de confianza):
  `loom init --agent nightly-triage --server-url http://localhost:7777` crea el
  espacio de nombres `agent-nightly-triage`, guarda un token de escritor en `~/.loom/token` y la URL
  en `~/.loom/config.json`, e imprime un código de reclamación. Una persona lo introduce una vez en
  `/oauth/agent-claim` con una contraseña propia para asumir la propiedad.

Guarda el token donde lo buscan el SDK, la CLI y los plugins:

```bash
mkdir -p ~/.loom && (umask 077; printf '%s' "<token>" > ~/.loom/token)
export LOOM_API_KEY="<token>"
```

Los claims, roles y permisos están en [Tokens y permisos](https://github.com/ClickHouse/loom/blob/main/docs/guides/tokens-and-grants.md).

<a id="4-first-memory-over-http"></a>

## 4. Primera memoria por HTTP

Cada operación es un `POST /v1/<op>` con un cuerpo JSON. Una instalación nueva con el `.env` por defecto, ya sea desde el instalador o desde un checkout, es de un solo usuario: no hay token, y una llamada cotidiana de memoria o de búsqueda (`memory.set`, `memory.get`, `memory.search` y alguna más) que no indique `org` ni `namespace` se ejecuta en los propios de la instalación, la org `dev` y el espacio de nombres `local`, los mismos que usan MCP y el dashboard; un `memory.set` que no indique `agent` se registra con el agente `http`, y una búsqueda lee todos los agentes. Por eso las llamadas siguientes solo necesitan sus propios campos ([qué ops](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md#request)). Si una llamada sin token responde 401 `AUTH_INVALID`, la autenticación está activada: añade `-H "Authorization: Bearer $LOOM_API_KEY"` e indica el `org`, el `namespace` y el `agent` de tu cuenta; un encabezado con un token vacío se rechaza.

```bash
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'
```

La respuesta de `memory.set` incluye `memory_id`, `content_sha256` y `status`.
`memory.get` lee una clave: `found` indica si la clave contiene un valor vigente, y `value` es el valor tal como se escribió. La respuesta de la búsqueda incluye `results` y `abstain`, que indica si el mejor resultado es lo bastante sólido como para responder a partir de él. La búsqueda lee las memorias de todos los agentes del espacio de nombres, incluidas las añadidas en el dashboard; indica un `agent` para leer solo las de ese agente.
`GET /v1/operations` lista todas las operaciones, y <http://localhost:7777/docs> te permite probar cada una desde el navegador. Los formatos están en la [referencia de la API HTTP](https://github.com/ClickHouse/loom/blob/main/docs/reference/http-api.md).

<a id="5-first-memory-from-python"></a>

## 5. Primera memoria desde Python

```bash
pip install clickhouse-loom    # or, from a clone: pip install ./sdk/python
```

Una versión que aún no está en PyPI se instala desde sus assets
([instalar desde un GitHub Release](https://github.com/ClickHouse/loom/blob/main/docs/development/release-process.md#installing-from-a-github-release)).

El ejemplo indica `org` y `namespace`, por lo que funciona con o sin el token del paso
3, que el SDK envía cuando encuentra uno. En un servidor de un solo usuario, una llamada sin token
puede omitirlos: `Agent(agent="quickstart", base_url=...)` también se ejecuta en `dev`/`local`.

```python
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())
```

Dónde encuentra el SDK su servidor y su credencial se explica en
[SDK de Python → Credenciales](https://github.com/ClickHouse/loom/blob/main/docs/reference/python-sdk.md#credentials).
El SDK de TypeScript se instala con `npm install @clickhouse/loom`
([desde un clon](https://github.com/ClickHouse/loom/blob/main/docs/reference/typescript-sdk.md#install)).

Las superficies del cliente están en las referencias del [SDK de Python](https://github.com/ClickHouse/loom/blob/main/docs/reference/python-sdk.md) y
del [SDK de TypeScript](https://github.com/ClickHouse/loom/blob/main/docs/reference/typescript-sdk.md).

<a id="6-first-memory-from-a-coding-agent"></a>

## 6. Primera memoria desde un agente de código

Si el instalador conectó a tu agente, pasa al último párrafo de esta sección.

Para Claude Code, instala el plugin de Loom. Añade hooks (contexto al inicio de la sesión, captura al final) y skills sobre las herramientas MCP:

```bash
claude plugin marketplace add ClickHouse/loom
claude plugin install loom@loom
```

En un servidor de un solo usuario en esta máquina, conserva la URL del servidor predeterminada y deja el token vacío cuando Claude Code solicite la configuración del plugin.

Sin el plugin, añade la entrada MCP directamente:

```bash
claude mcp add --transport http loom "http://localhost:7777/mcp?toolset=coding" -s user
```

Ambos llegan a un servidor de un solo usuario en esta máquina sin un token tuyo.

Con la autenticación activada, crea un token en **Settings → Tokens** y elige **Claude Code** en **Connect**: el cuadro de diálogo muestra la configuración para el plugin y para una entrada `claude mcp add`, con el token incluido. Después:

1. Sobrescribe `~/.loom/config.json` con el bloque `config.json` del cuadro de diálogo más el espacio de nombres en el que guarda el token (`"namespace": "<namespace>"`): un `org` o `namespace` que una sesión de un solo usuario haya dejado en el archivo tiene prioridad sobre el token, y sin uno el plugin escribe en el primer espacio de nombres del token distinto de `*`, o en `coding`. Vuelve a añadir los valores de `code_repo` o `agent` que hubieras definido.
2. Deja vacíos `LOOM_API_KEY` (el paso 3 pudo haber exportado uno: `unset LOOM_API_KEY`) y la opción `token` del plugin, o asígnales el nuevo token: el plugin lee ambos antes que ese archivo
   ([configuración](https://github.com/ClickHouse/loom/blob/main/docs/features/integrations/claude-code.md#configuration)).
3. Elimina una entrada de `claude mcp add` creada sin token (`claude mcp remove loom -s user`) antes de ejecutar el comando del cuadro de diálogo, que rechaza un nombre que ya existe.

`loom install --client <name>` escribe la entrada MCP para Claude Desktop, Claude Code, Codex, Cursor, VS Code, Cline, Windsurf y Zed; sin la opción, conecta todos los clientes que encuentra. [Conectar un agente de código](https://github.com/ClickHouse/loom/blob/main/docs/getting-started/connect-a-coding-agent.md) cubre Codex y Cursor.

Inicia una sesión nueva y di _"Remember that I never deploy on Friday."_ El agente llama a `loom_memory_set`. En una sesión nueva, pregunta _"When can I deploy?"_ El agente llama a `loom_search` y responde a partir del dato almacenado. El modelo decide cuándo guardar y buscar a partir de las descripciones de las herramientas; no hay palabras clave que lo activen.

<a id="7-see-it-in-the-dashboard"></a>

## 7. Ver en el panel

| Página            | Muestra                                                      |
| ----------------- | ------------------------------------------------------------ |
| `/memories`       | Las memorias del espacio de nombres, con autor y hora.       |
| `/admin/activity` | El registro de auditoría: qué agente escribió qué clave y cuándo. |
| `/admin/usage`    | Costo por operación y agente.                                |

El resto está en [Panel](https://github.com/ClickHouse/loom/blob/main/docs/features/dashboard.md).

<a id="optional-index-a-repository-on-the-released-stack"></a>

## Opcional: indexar un repositorio en el stack publicado

En este stack, añadir un repositorio desde el dashboard se rechaza con `SANDBOX_UNAVAILABLE`:
requiere el [sandbox de trabajos de repositorio](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md#repository-job-sandbox),
que este stack deja desactivado porque el confinamiento predeterminado de Docker lo bloquea. Incluye solo
repositorios de confianza: sus pasos de compilación (instalaciones de TypeScript, descargas de módulos de Go,
CMake) se ejecutan sin el sandbox, en el contenedor `loom`, cuyo entorno contiene el secreto JWT
y las claves de los proveedores.

`LOOM_CODE_REPOS_JSON` es una sola línea que contiene todos los repositorios como un arreglo JSON
([Configurar la entrada](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md#configure-the-entry)).
En `~/.loom/.env`, descomenta esa línea (añádela si falta) y edítala.
`dev` es la organización con la que se ejecuta un stack de un solo usuario, y la organización en la que se registran las cuentas multiusuario
(`LOOM_SELF_SIGNUP_ORG`); si lo cambiaste, usa aquí la organización de tu cuenta y en
`--org` más abajo:

```dotenv
LOOM_CODE_REPOS_JSON=[{"org":"dev","namespace":"code-myrepo","repo":"acme/myrepo","git_branch":"main","public":true}]
```

- Loom elige los indexadores del nivel del compilador a partir de los archivos de compilación del repositorio (`go.mod`,
  `package.json`, `pyproject.toml`, un `CMakeLists.txt` en la raíz, …); `scip_producer` nombra
  uno en su lugar ([Nivel del compilador](https://github.com/ClickHouse/loom/blob/main/docs/operations/code-index-operations.md#compiler-tier)).
  C/C++ también necesita un árbol de compilación configurado, así que sin uno un repositorio C/C++ obtiene solo
  el nivel del parser.
- Para un repositorio privado, añade un token de GitHub (`LOOM_CODE_GITHUB_TOKEN` en `.env`, o
  `github_token` en la entrada) y elimina `"public":true`: ese valor es para repositorios públicos en
  su host, y permite que cualquier miembro de la organización se una al índice como lector de inmediato desde
  **Repositories**. Decídelo antes del primer `loom code init`: este establece la política de ingreso del espacio de nombres a partir de `public`,
  y editar `public` después no la cambia (un maintainer
  la cambia con `code.repo.set_access`).

Luego recrea el contenedor `loom` y ejecuta la primera indexación:

```bash
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` se ejecuta con el embedder local del stack publicado. Con un embedder falso (el `.env` de un checkout, o una instalación actualizada que aún nombra `fake-ngram-*`) se rechaza y
termina; para probar la configuración de todos modos, añade `--allow-fake-embedder`. Elegir un modelo más tarde en
**Settings → Models & keys** vuelve a generar los embeddings del índice de código; tras un cambio en `.env` necesita su
propia regeneración de embeddings, como describe [Modelos y claves](https://github.com/ClickHouse/loom/blob/main/docs/getting-started/models-and-keys.md).

En modo multiusuario, un repositorio listado no tiene maintainer, así que sin `"public":true` la solicitud de ingreso
de un lector queda esperando sin nadie que la apruebe. Después de `loom code init`, da
acceso a alguien como operador con un token generado en el contenedor: `admin` lo convierte
en el maintainer, quien aprueba a los lectores a partir de entonces, y `viewer` le permite leer. El
sujeto es el espacio de nombres con el que se registró la cuenta (su identificador de inicio de sesión, el sujeto de
sus tokens); un correo de autorregistro nunca se verifica, así que una concesión a él no admite a nadie:

```bash
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"}'
```

<a id="optional-ask-a-question-about-a-document"></a>

## Opcional: hacer una pregunta sobre un documento

```bash
loom demo
```

`loom demo` sube el `AGENTS.md` de este repositorio, lo ingiere con `knowledge.ingest` (el extractor de referencia del stack lo analiza) y hace una pregunta sobre él con `knowledge.synthesize`, e imprime
la respuesta y los fragmentos que citó. Con el LLM falso imprime en su lugar los mejores resultados de
`knowledge.search`. `--file` y `--question` lo dirigen a tu propio documento.

<a id="common-problems"></a>

## Problemas comunes

| Síntoma                                                                       | Causa y solución                                                                                                                                                                                                                                                                |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `set_from_messages` no escribe hechos                                         | El LLM es el falso. Sigue [Modelos y claves](https://github.com/ClickHouse/loom/blob/main/docs/getting-started/models-and-keys.md) para configurar uno.                                                                                                                                                                                    |
| Los resultados de búsqueda parecen arbitrarios                                | El embedder es uno falso (`fake-ngram-*` en `.env`). Cámbialo como indica [Modelos y claves](https://github.com/ClickHouse/loom/blob/main/docs/getting-started/models-and-keys.md), lo que vuelve a calcular los embeddings de lo almacenado. No borres tus volúmenes para cambiar de modelo.                                                                               |
| 401 `AUTH_INVALID` tras activar la autenticación                              | Falta el token, o está firmado con otro `LOOM_JWT_SECRET`. Genera uno nuevo con el comando de Compose en [Obtener un token](#3-get-a-token).                                                                                                                                                   |
| El dashboard devuelve 503                                                     | El servidor se ejecuta desde el código fuente (`make server`) sin un frontend compilado. Ejecuta `make frontend-build`.                                                                                                                                                                             |
| La pila publicada no pasa a estado saludable                                  | Ejecuta `docker compose --project-directory "$HOME/.loom" logs --tail 100 loom clickhouse`. Consulta [Solución de problemas](https://github.com/ClickHouse/loom/blob/main/docs/operations/troubleshooting.md).                                                                                                                             |
| Al añadir un repositorio se responde `SANDBOX_UNAVAILABLE`                    | La pila se ejecuta sin el sandbox de tareas de repositorio. Indexa el repositorio mediante `LOOM_CODE_REPOS_JSON` ([Indexar un repositorio](#optional-index-a-repository-on-the-released-stack)).                                                                                           |
| El instalador dice que el puerto `7777` está en uso                           | Otro programa, u otro Loom, escucha ahí. Deténlo, o vuelve a ejecutar el comando de instalación con `LOOM_PORT=7778` delante de `sh loom-install.sh`; `.env` conserva el puerto.                                                                                                    |
| El instalador dice que el puerto `7777` no responde                           | Un programa lo ocupa sin responder, o `LOOM_BIND_HOST`, `LOOM_PORT` o un firewall impiden que este host lo alcance.                                                                                                                                                       |
| El instalador no pudo comprobar el puerto `7777`                              | Curl falló por el motivo que indica su código de salida; revisa `LOOM_BIND_HOST` y `LOOM_PORT`.                                                                                                                                                                                      |
| En Docker Desktop sobre WSL, la instalación se detiene con `Ports are not available` | Windows ocupa o reserva el puerto, algo que la comprobación del instalador dentro de WSL no puede ver. `netsh interface ipv4 show excludedportrange protocol=tcp` muestra los rangos reservados; vuelve a ejecutar el comando de instalación con un `LOOM_PORT` fuera de ellos delante de `sh loom-install.sh`. |
| El puerto `8123` o `9000` de un clon está ocupado                             | Reasigna los puertos de host de ClickHouse ([pila local](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md#local-stack-from-a-clone)).                                                                                                                                                                       |
| El instalador no pudo descargar las imágenes                                  | Docker accede por sí mismo al registro: si estás detrás de un proxy, configura el daemon de Docker con los [ajustes de proxy](https://docs.docker.com/engine/daemon/proxy/).                                                                                                                               |

<a id="next"></a>

## Siguientes pasos

- [Evaluar Loom](https://github.com/ClickHouse/loom/blob/main/docs/getting-started/evaluate.md): convierte esta prueba de humo en una evaluación de calidad,
  latencia y costo específica para tu carga de trabajo.
- [Conectar un agente de código](https://github.com/ClickHouse/loom/blob/main/docs/getting-started/connect-a-coding-agent.md): Claude Code, Codex o Cursor
  contra este stack.
- [Tu primer agente](https://github.com/ClickHouse/loom/blob/main/docs/getting-started/first-agent.md): identidad, manejo de abstenciones, sesiones, paquetes de contexto
  y ejecuciones desde el SDK.
- [Despliegue](https://github.com/ClickHouse/loom/blob/main/docs/operations/deployment.md): cómo ejecutar Loom para un equipo.
