Configurar dsh: claves API, modelos y endpoints
Aprenda dónde guarda dsh su configuración en Linux, cómo usar una clave DeepSeek o un endpoint Ollama local y qué datos salen de su equipo en cada modo.
Dónde guarda dsh su configuración
dsh (DeepSeek Harness) guarda los datos de su entorno en $DSH_HOME, cuyo valor predeterminado es ~/.dsh, y lee la configuración compartida de los agentes desde una raíz independiente, $DSH_AGENTS_HOME, cuyo valor predeterminado es ~/.agents. Todo lo que configure en la interfaz web se escribe allí como archivos de texto sin formato. Al trasladar la configuración a otro servidor, copie el directorio principal del entorno y las instrucciones y habilidades globales desde la raíz compartida de los agentes.
Cuatro rutas contienen la configuración principal del entorno, los secretos y los registros de sesión.
~/.dsh/profiles/<profile>/cordis.patch.ymlcontiene la configuración que la interfaz web escribe para ese perfil, incluidas las rutas del proveedor y del modelo.dsh webejecuta el perfilweb, por lo que el archivo es~/.dsh/profiles/web/cordis.patch.yml.~/.dsh/.credentials.yamlcontiene los secretos. La configuración sólo conserva una referencia a una credencial, por lo que el valor de la clave se encuentra en un único archivo.~/.dsh/profiles/contiene los perfiles con nombre, y~/.dsh/sessions/contiene los registros de sesión guardados.~/.dsh/cordis.patch.ymles su propia capa de parches. Se aplica sobre la configuración integrada para cada perfil y tiene prioridad sobre el archivo del perfil. Por eso, si esta capa sobrescribiría un cambio de la interfaz web, el cambio se rechaza en lugar de guardarse.
La raíz compartida de los agentes permanece fuera de $DSH_HOME porque otras herramientas de agentes también la utilizan. dsh lee las instrucciones globales del usuario desde ~/.agents/AGENTS.md y busca habilidades en ~/.agents/skills/; establezca DSH_AGENTS_HOME para mover esa raíz.
Las compilaciones anteriores guardaban esta configuración en ~/.dsh/settings.yaml. Las compilaciones actuales importan ese archivo una vez en el perfil activo y le cambian el nombre a settings.yaml.imported. Por tanto, una guía antigua que indique editar settings.yaml apunta ahora a un archivo que dsh ya no lee.
DeepSeek publica el entorno con una licencia MIT como versión preliminar para desarrolladores, y el README indica que habrá cambios incompatibles. Los nombres de los campos y las rutas de esta guía coinciden con la documentación actual del repositorio, comprobada el 5 de noviembre de 2026. Compárelos con la documentación de la versión que haya instalado antes de copiar la configuración de cualquier guía, incluida esta, porque una versión preliminar puede cambiar los nombres entre versiones.
El mínimo real para obtener la primera salida
dsh necesita Node.js 24.9 o posterior. A fecha de 5 de noviembre de 2026, su package.json declara >=24.9.0, por lo que la línea 22 no es compatible. Node 24.0 a 24.8 tampoco es suficiente. Compruebe primero la versión, porque una incompatibilidad de versiones provoca un fallo al iniciar y el error parece indicar que el paquete está dañado.
node -v
npx @deepseek-ai/dsh webnpx descarga el paquete del registro de npm e inicia la interfaz web en http://127.0.0.1:3080. Se enlaza a la dirección de loopback, por lo que el puerto no es accesible desde otra máquina aunque el firewall lo permita. En un VPS, reenvíe el puerto mediante SSH en lugar de abrir 3080 a Internet. Si la URL mostrada resulta confusa, por qué dsh se inicia en esa dirección explica qué protege el enlace a loopback y qué no protege.
ssh -N -L 3080:127.0.0.1:3080 you@your-serverAbra http://127.0.0.1:3080 en su portátil y vaya a Settings y Models. La tarjeta de DeepSeek tiene un único campo para la clave de API. Pegue la clave de platform.deepseek.com y guárdela. La ruta del modelo queda disponible de inmediato, sin reiniciar, porque el servidor en ejecución almacena la credencial y resuelve la referencia en tiempo real. Acceder a la interfaz web de dsh en un servidor remoto explica el túnel y el caso del proxy inverso, y instalar DeepSeek Harness en un VPS explica la preparación del servidor que presupone esta guía.
Después de guardar, compruebe qué ha creado la aplicación.
ls -la ~/.dsh
stat -c '%a %n' ~/.dsh/.credentials.yamlDebería ver .credentials.yaml y profiles/, con la configuración de la interfaz web en profiles/web/cordis.patch.yml. Un directorio personal creado por una compilación anterior también puede contener settings.yaml.imported. Si stat muestra un modo distinto de 600, ejecute chmod 600 ~/.dsh/.credentials.yaml. Un archivo de credenciales legible por el grupo expone la clave a las cuentas de ese grupo; uno legible por todos la expone a cualquier otra cuenta del sistema.
Para una primera ejecución sin navegador, basta con un comando.
npx @deepseek-ai/dsh --profile headless "summarise the files in this directory"El perfil sin interfaz ejecuta una sola sesión y muestra la respuesta final.
Variables de entorno o archivo de configuración
dsh puede resolver una clave a partir de credenciales guardadas o de valores alternativos del entorno.
Un proveedor del catálogo (DeepSeek, Anthropic, OpenAI y el resto de la lista integrada) acepta una clave desde la página Models o usa la variable de entorno compatible cuando ninguna credencial guardada la proporciona. El valor se almacena en ~/.dsh/.credentials.yaml, y la configuración sólo conserva una referencia a él. La Web UI no vuelve a mostrar la clave después de guardarla.
Un proveedor personalizado puede indicar una referencia de credencial mediante apiKeyEnv, que también admite valores alternativos del entorno. Esta es la estructura que muestra la documentación para una entrada en un parche de perfil como ~/.dsh/profiles/web/cordis.patch.yml.
- id: llm-pi-ai
config:
providers:
my-gateway:
apiKeyEnv: GATEWAY_API_KEY
api: openai-completions
baseURL: https://gateway.example/v1
models:
- id: legacy-chat
- id: vision-preview
input: [text, image]Añada primero un proveedor mediante la Web UI. Después, abra cordis.patch.yml del perfil y copie la estructura que escribió. Durante una vista previa para desarrolladores, la anidación es la parte con más probabilidades de cambiar. El archivo que la aplicación acaba de escribir siempre está actualizado.
apiKeyEnv se resuelve mediante el almacén de credenciales: primero se usa el archivo guardado, seguido del entorno de inicio, el .env del directorio desde el que se ejecuta el proceso y, por último, $DSH_HOME/.env. Una clave exportada sólo en una sesión interactiva no está disponible para una unidad de systemd. Por tanto, sin otra fuente de credenciales, la misma configuración que funciona al escribir dsh web manualmente devuelve MISSING_CREDENTIAL cuando se ejecuta como servicio. Asigne a la unidad su propio archivo.
[Service]
EnvironmentFile=/etc/dsh/dsh.envMantenga ese archivo con permisos 600 y con el usuario que ejecuta el servicio como propietario.
Elección de modelos y el ID que no se puede cambiar de nombre
Todos los proveedores configurados aparecen en el selector de modelos. Al seleccionar un modelo, también se establece como predeterminado para las sesiones nuevas. Las sesiones que ya han enviado una solicitud conservan el modelo registrado en ellas, por lo que el cambio no modifica una conversación anterior.
El ID del proveedor es permanente. Las solicitudes, las sesiones guardadas, los modelos predeterminados y las referencias a credenciales apuntan a él, por lo que no existe ningún botón para cambiarle el nombre. Para cambiarlo, hay que crear un proveedor nuevo y eliminar el anterior. Elija un nombre que pueda mantener: local-ollama en lugar de test2.
Los modelos personalizados sin capacidad de imagen heredada sólo admiten texto, a menos que se indique lo contrario. Añada input: [text, image] a una entrada de modelo para declarar que admite imágenes, o establezca defaultInput en el nivel de la ruta como valor alternativo para los modelos que el catálogo no describa. En la ruta propia de DeepSeek, un modelo sin modalidades declaradas se considera de sólo texto. Por tanto, seleccione una entrada del catálogo con capacidad de imagen (deepseek-flash de forma predeterminada) antes de adjuntar una imagen. Una imagen enviada a un modelo que no declara compatibilidad con imágenes se rechaza antes de enviar cualquier dato.
Apunte dsh a un endpoint local para que el código permanezca en el equipo
Ollama ofrece una API compatible con OpenAI en http://127.0.0.1:11434/v1. dsh puede comunicarse con cualquier URL base compatible con OpenAI mediante un proveedor personalizado, por lo que ambos se conectan directamente. Configure primero el servidor de modelos: alojar un LLM con Ollama en un VPS explica la instalación y la descarga del modelo.
Confirme que el endpoint responde antes de configurar dsh.
ollama list
curl -s http://127.0.0.1:11434/v1/modelsollama list muestra la etiqueta exacta de cada modelo que haya descargado. Copie esa cadena. curl devuelve los mismos modelos en formato JSON. Una lista vacía significa que Ollama está en ejecución, pero no hay ningún modelo descargado. Connection refused significa que Ollama no está en ejecución o no está escuchando en 11434.
Elija un modelo que pueda ejecutarse en esta máquina. Un servidor de Ollama con una sesión iniciada también ofrece modelos en la nube mediante la misma dirección local. Una etiqueta de nube como gemma4:cloud se ejecuta en los servidores de Ollama. Por tanto, las solicitudes salen del equipo aunque dsh sólo se comunique con 127.0.0.1.
Añada ahora el proveedor al parche del perfil. Proporcione un valor de clave API no vacío para esta configuración. El servidor local de Ollama lo ignora.
- id: llm-pi-ai
config:
providers:
local-ollama:
apiKeyEnv: OLLAMA_API_KEY
api: openai-completions
baseURL: http://127.0.0.1:11434/v1
models:
- id: <the exact tag printed by ollama list>Exporte la variable donde pueda verla el proceso de dsh.
sudo install -d -m 700 /etc/dsh
printf 'OLLAMA_API_KEY=ollama\n' | sudo tee /etc/dsh/dsh.env
sudo chmod 600 /etc/dsh/dsh.envTres fallos cubren casi todos los intentos de este tipo. MISSING_CREDENTIAL significa que la referencia indicada por apiKeyEnv no resolvió ningún valor. Revise las credenciales guardadas y el entorno de ejecución, no sólo el terminal. UNKNOWN_MODEL significa que id no coincide con ningún modelo configurado. Compárelo con ollama list carácter por carácter, incluida la etiqueta posterior a los dos puntos. Un error 401 al obtener los modelos disponibles procede del descubrimiento de modelos, que llama a GET /models en la URL base. Los endpoints que no ofrecen esa ruta requieren que introduzca los modelos manualmente.
La URL base es otro punto problemático. No elimine /v1 de ella. Si lo hace, las solicitudes llegarán a rutas que Ollama no ofrece, la llamada devolverá un error 404 y el modelo no se ejecutará. El sufijo forma parte de la interfaz compatible con OpenAI; no es decorativo.
Si Ollama se ejecuta en otra máquina, la dirección de esa máquina se convierte en la URL base. Las solicitudes cruzarán entonces la red en texto claro mediante HTTP sin cifrado. Manténgalo en el mismo host o colóquelo detrás de TLS (seguridad de la capa de transporte) y autenticación: proteger un endpoint de Ollama expuesto.
Qué sale de la máquina en cada modo
Con una clave de DeepSeek y el endpoint predeterminado, las solicitudes al modelo se envían a la API de DeepSeek. Esa solicitud contiene el prompt, el contenido de los archivos que el agente leyó para responder, la salida de los comandos que ejecutó y cualquier resultado de herramientas que decidiera incluir. El código fuente forma parte de esa carga cuando el agente abrió un archivo. Así funciona un modelo alojado y por eso debe tener en cuenta desde qué directorio inicia el agente.
Las versiones actuales también adjuntan a las solicitudes realizadas mediante el adaptador nativo de DeepSeek, incluidos los gateways configurados, un sufijo aún no aceptado del registro de eventos de la sesión, de forma predeterminada, como un campo dsh_session_log independiente. El modelo nunca lo ve, pero el destino de la solicitud sí lo recibe. Desactívelo en Settings, General ("Upload Session Log when using the official model API") o establezca enabled: false en el plugin session-log-deepseek. Los conmutadores de telemetría siguientes no controlan esta carga.
Los perfiles incluidos también envían los nombres y las versiones de los paquetes de plugins activos mediante el adaptador nativo de DeepSeek, en un campo dsh_plugin_packages independiente. Establezca enabled: false en plugin-package-inventory-deepseek para impedir ese envío.
Con otro proveedor del catálogo o con un gateway de la empresa, la misma carga se envía a ese proveedor. La URL base indica exactamente el destino.
Con un endpoint local, la solicitud al modelo se envía a 127.0.0.1:11434, pero la dirección de loopback por sí sola no garantiza que permanezca en el equipo. La documentación de Ollama indica: "To use cloud models through this server, sign in to Ollama", por lo que un modelo cloud seleccionado a través de ese mismo servidor local envía los prompts y el código a la nube de Ollama. La solicitud al modelo sólo permanece en la máquina cuando el propio modelo se ejecuta localmente. Incluso en ese caso, tres elementos siguen atravesando la red. npx descarga el paquete del registro de npm. Cualquier herramienta que ejecute el agente puede acceder a Internet por su cuenta, incluidos los servidores MCP (model context protocol) a los que se conectó; ejecutar servidores MCP en un VPS lo explica en detalle. Un plugin pertenece a la misma categoría, porque instalarlo ejecuta código de otro autor con los permisos del agente. Por eso conviene comprobar a qué puede acceder un plugin antes de instalarlo. También está la telemetría, que las versiones actuales autorizan a exportar a DeepSeek cada vez que envía comentarios, tanto con un modelo local como con uno alojado.
De forma predeterminada, la telemetría se limita a los comentarios. DSH_TELEMETRY_MODE selecciona el modo y, en la configuración base incluida actualmente, un valor no establecido o vacío se resuelve como FEEDBACK_ONLY. En ese modo, la actividad normal no autoriza ninguna captura de telemetría. Cuando envía comentarios escritos, crea o edita una valoración, edita una nota o retira comentarios, dsh autoriza la exportación a https://dsh-otel-collector.deepseeksvc.com/v1/logs del prefijo del registro de sesión que aún no se ha entregado al exportador, a través de ese evento de comentarios e incluyendo el contexto heredado. La entrega completa no está garantizada: un evento demasiado grande se rechaza sin truncarlo y los prefijos grandes pueden quedar parcialmente sin enviar al salir de la CLI. Los lotes autorizados pueden seguir enviándose sin otra interacción ni otra llamada al modelo. El README de telemetría indica que esto se aplica "for all users and providers", por lo que ejecutar el modelo localmente no la desactiva. DISABLED no construye ningún transporte de OpenTelemetry (OTel). FULL ya no se acepta: cualquier valor distinto de esos dos se rechaza con unsupported mode. Una exportación de comentarios puede contener texto de mensajes, argumentos y resultados de herramientas y rutas del workspace. Trate los comentarios como una autorización para enviar ese prefijo de la sesión a DeepSeek.
Para detenerlo por completo sin depender de escribir correctamente la cadena del modo, establezca DSH_TELEMETRY_DISABLED=1. Cualquier valor no vacío es una exclusión autorizada, incluidos 0 y false, y se lee antes de iniciar la ejecución. Por tanto, el código del proyecto no puede volver a activarlo durante la sesión. La dirección predeterminada del collector es dsh-otel-collector.deepseeksvc.com; DSH_TELEMETRY_OTLP_URL la sustituye.
Verifique la configuración en lugar de confiar en ella. Con una tarea en ejecución, enumere las conexiones salientes que mantiene el proceso.
sudo ss -tnp | grep -i nodeCon un modelo ejecutado localmente, el tráfico del modelo utiliza el puerto de loopback 11434, pero las herramientas pueden seguir creando conexiones públicas aunque no se hayan enviado comentarios. Los perfiles incluidos habilitan la búsqueda y la descarga web, y el perfil de permisos predeterminado no restringe el acceso a la red. Identifique cada destino público antes de atribuirlo a la telemetría; el momento por sí solo no demuestra que una conexión corresponda a la exportación de comentarios. Esta captura también puede no detectar conexiones de corta duración. Esta comprobación sólo cubre el proceso dsh: el tráfico de un modelo cloud sale del servidor de Ollama, así que confirme también que el modelo id no tenga una etiqueta cloud. Conviene identificar cualquier otra conexión antes de continuar. Qué envía un agente de programación a su origen ejecuta la misma comprobación con otros harnesses y explica cómo interpretar el resultado.
Dónde no deben almacenarse los secretos
- Historial del shell.
export DEEPSEEK_API_KEY=sk-...se escribe en~/.bash_historyen texto sin formato y permanece allí mucho después de rotar la clave. Anteponer un espacio al comando cuandoHISTCONTROL=ignorespaceestá definido, o evitar el shell y escribir el valor directamente en un archivo con modo 600. - Archivos dot confirmados en el repositorio. Una clave en
~/.bashrco~/.zshrcestá a ungit addde un repositorio público si mantiene los archivos dot en git. Ejecutegit grep -I -n 'sk-'en ese repositorio antes de hacer push. - Archivos de parches del perfil. Use
apiKeyEnvpara los proveedores personalizados, de modo quecordis.patch.ymlcontenga un nombre de variable en lugar de un secreto. Los archivos de configuración se pegan en informes de incidencias y chats de soporte. Los archivos de credenciales no. - Salida de
envy capturas de pantalla del terminal. Todo lo que muestre el entorno completo también muestra la clave. - Copias de seguridad. Conviene incluir
~/.dshen las copias de seguridad, pero.credentials.yamldentro de él contiene un secreto activo. Excluya ese archivo o cifre el archivo comprimido.
Estas reglas no son específicas de dsh, y mantener los secretos fuera de los archivos env de Compose aborda el mismo problema en el lado de los contenedores del mismo servidor.
Trabajar con una versión preliminar
Fije la versión que probó, porque una versión preliminar puede cambiar una clave de configuración en una versión de corrección y el proveedor puede dejar de cargarse. Si la instalación con la versión fijada se niega a iniciarse, o npx sigue entregándole una compilación que no solicitó, los errores de instalación y versión que produce una versión preliminar explican la caché de npx y la versión de npm incluida con Node. Mantenga el directorio personal cordis.patch.yml y los archivos de corrección de profiles/ bajo control de versiones, y excluya el archivo de credenciales, para poder ver qué cambió después de una actualización.
Dos opciones ayudan cuando un perfil no se comporta como espera. --dump-default-config muestra la configuración predeterminada compuesta sin iniciar el servicio, y --dump-config muestra del mismo modo la configuración compuesta de su perfil. Compararlas permite ver qué cambió realmente la capa de corrección. Es más rápido que leer las capas manualmente.
dsh --profile web --dump-configEjecute primero ese comando cuando algo falle después de una actualización. Si una clave cambió de ubicación entre versiones, aparecerá como una rama ausente en el volcado. La corrección consistirá en editar una sola línea, no en reinstalar.
FAQ
¿Dónde almacena dsh mi clave de API de DeepSeek?
En $DSH_HOME/.credentials.yaml, que es ~/.dsh/.credentials.yaml salvo que configure DSH_HOME manualmente. La página Models escribe la clave allí y la configuración sólo conserva una referencia a ella, por lo que el secreto se almacena en un único archivo. Compruebe los permisos con stat -c '%a %n' ~/.dsh/.credentials.yaml y establézcalos en 600 si son menos restrictivos. Un proveedor personalizado puede evitar por completo el archivo si especifica una variable de entorno con apiKeyEnv.
¿Cómo hago que dsh use un modelo local en lugar de la API de DeepSeek?
Añada un proveedor personalizado cuya URL base sea su endpoint local compatible con OpenAI. En Ollama es http://127.0.0.1:11434/v1, con api: openai-completions y un modelo id copiado exactamente de ollama list. Proporcione un valor de clave de API no vacío para esta configuración; el servidor local de Ollama lo ignora. Confirme que el endpoint responde con curl -s http://127.0.0.1:11434/v1/models antes de editar la configuración de dsh, porque un endpoint inactivo y una configuración incorrecta producen errores similares.
¿Envía dsh mi código a algún sitio de forma predeterminada?
Con un modelo alojado, sí. El prompt y el contenido de los archivos que lee el agente se incluyen en la solicitud de API enviada a ese proveedor. Las solicitudes realizadas mediante el adaptador nativo de DeepSeek, incluidos los gateways configurados, también incluyen de forma predeterminada un sufijo del registro de sesión hasta que desactive esa carga en Settings, General. Con un modelo que Ollama ejecuta localmente, la solicitud se dirige a loopback y permanece en la máquina. Sin embargo, un modelo en la nube como gemma4:cloud la envía a la nube de Ollama mediante la misma dirección de loopback. La búsqueda y la obtención web integradas, otras herramientas y los plugins pueden contactar con servicios públicos de forma independiente de los comentarios. La telemetría es un flujo separado: en las versiones actuales, DSH_TELEMETRY_MODE se resuelve en FEEDBACK_ONLY cuando no está configurado. Por tanto, los comentarios autorizan la exportación del prefijo del registro de sesión mediante ese evento para todos los proveedores, incluidos los modelos locales, junto con el contexto heredado. La entrega no está garantizada y las cargas autorizadas pueden continuar después de la interacción de comentarios. Establézcalo en DISABLED para no usar ningún exportador, o establezca DSH_TELEMETRY_DISABLED=1 para activar una exclusión que se lea antes de iniciar la ejecución.
¿Por qué dsh informa de MISSING_CREDENTIAL cuando mi variable está configurada?
Porque la referencia indicada por apiKeyEnv debe resolverse en las fuentes de credenciales de dsh. Las credenciales guardadas tienen prioridad, seguidas de .env y $DSH_HOME/.env del directorio desde el que se inicia el proceso. Una variable exportada en su shell no llega a un servicio de systemd, a la sesión de otro usuario ni a un proceso iniciado antes de exportarla. Guarde el valor en un EnvironmentFile con permisos 600 para la unidad, o expórtelo en el mismo shell desde el que inicia dsh. Compruebe qué contiene realmente el proceso en ejecución con sudo tr '\0' '\n' < /proc/$(pgrep -f dsh | head -1)/environ.
¿Qué versión de Node.js necesita dsh?
Node.js 24.9 o posterior, según el package.json del repositorio a fecha de 5 de noviembre de 2026. La serie 22 ya no es compatible, y Node 24.0 a 24.8 tampoco es suficiente. Ejecute node -v antes de cualquier otra acción, porque un fallo de arranque causado por un runtime no compatible parece una instalación dañada y puede llevar a reinstalar el paquete en lugar del runtime.