Apuntes de eduardófilo

Instalación OpenCode, OmniRoute y Ponytail

Sun, 26 Jul 2026 12:00:00 +0200

El desarrollo asistido por IA empezó siendo un autocompletado inteligente del código a nivel de línea. Pasó a ser una "segunda opinión" que revisaba el código a nivel de fichero y sugería cambios. En los últimos dos años se ha dado un importante paso más allá hasta llegar al paradigma actual, el desarrollo agéntico: un agente que trabaja a nivel de proyecto, edita ficheros, ejecuta comandos, realiza por sí solo los cambios que antes solo se sugerían, lanza los tests e itera hasta cerrar la tarea. El problema es que todas las herramientas comerciales de este tipo (Claude Code, Cursor, Devin, Copilot, Codex, etc.) comparten dos limitaciones: una suscripción mensual y unas cuotas que se agotan justo cuando la sesión se está poniendo interesante. Porque aquí no consideramos el uso por medio de API que para el ámbito personal resulta inasequible.

Hay además un tercer problema, más silencioso pero también caro: los agentes tienden a sobre-construir. Se les pide un selector de fechas y acaban instalando una librería, escribiendo un componente envoltorio y una hoja de estilos. Cada línea de más se paga dos veces, en tokens al generarla y en tokens cada vez que vuelve a entrar en el contexto.

En este artículo se describe cómo montar un entorno de desarrollo agéntico completo combinando tres proyectos de código abierto que resuelven precisamente estas limitaciones:

OpenCode: el agente de programación en terminal.
OmniRoute: el router/gateway de modelos que alimenta al agente.
Ponytail: el skill que impone al agente disciplina de código mínimo.

Descripción de los productos¶

OpenCode¶

OpenCode es un agente de programación que se ejecuta en la terminal (TUI), de código abierto y, lo más importante para nuestro propósito, agnóstico respecto al proveedor de modelos. A diferencia de Claude Code (atado a Anthropic) o Codex (atado a OpenAI), OpenCode permite configurar cualquier proveedor, incluidos los que exponen una API compatible con OpenAI, que a día de hoy son prácticamente todos.

Sus características principales:

Interfaz de terminal con sesiones persistentes, gestión de contexto y undo de los cambios aplicados.
Acceso a herramientas: lectura y escritura de ficheros, ejecución de comandos, búsqueda en el repositorio, control de versiones.
Fichero de contexto por proyecto (AGENTS.md) que se genera con /init y que sirve para instruir al agente sobre las convenciones del repositorio.
Soporte de MCP (Model Context Protocol) para añadir herramientas externas.
Modo CLI no interactivo (opencode run "...") para automatizaciones y scripts.
Agentes especializados y modos de trabajo (por ejemplo un modo plan que no hace cambios pensado para la fase de planificación previa).

OmniRoute¶

OmniRoute es un gateway de IA local y de código abierto. Se instala en la propia máquina (o en un VPS), levanta un endpoint compatible con la API de OpenAI y un panel web de administración, y desde ahí enruta cada petición hacia cualquiera de los cientos de proveedores que tiene catalogados, de los que unos 90 disponen de capa gratuita.

Lo interesante no es el catálogo en sí, sino lo que hace con él:

Enrutado automático: usando el modelo virtual auto, OmniRoute construye un combo con los proveedores que tengamos conectados y elige uno en cada petición según su puntuación en vivo. Existen variantes: auto/coding (calidad para generar código), auto/fast (menor latencia), auto/cheap (menor coste por token) y auto/offline (mayor margen de cuota disponible).
Fallback en cascada: cuando un proveedor devuelve un error de cuota, un rate limit o un 4xx-5xx, la petición se reintenta contra el siguiente proveedor de la lista de forma transparente para el cliente. Esto es lo que evita el clásico "se acabó tu cuota, vuelve en cinco horas".
Compresión de contexto: una batería de motores que recortan el prompt (deduplicación, poda de historial, compactado de ficheros) y que permiten ahorros importantes de tokens, especialmente valiosos cuando se trabaja contra capas gratuitas medidas en tokens/día.
Panel de control en http://localhost:20128 con estadísticas de uso por proveedor, gestión de claves API y configuración asistida de las herramientas CLI más habituales.
Local-first: las claves de los proveedores y el tráfico se quedan en la máquina; OmniRoute no es un servicio en la nube al que haya que suscribirse.

Ponytail¶

Ponytail es un skill, es decir un conjunto de instrucciones que se inyectan en el contexto del agente en cada turno para modificar su comportamiento. Su cometido es uno solo, combatir la sobre-ingeniería, y lo hace obligando al agente a recorrer una escalera de decisión antes de escribir una sola línea, deteniéndose en el primer peldaño que resuelva el problema:

1. ¿Esto necesita existir? → no: no lo hagas (YAGNI)2. ¿Ya está en este repositorio? → reutilízalo, no lo reescribas3. ¿Lo hace la librería estándar? → úsala4. ¿Es una función nativa de la plataforma? → úsala5. ¿Hay una dependencia ya instalada? → úsala6. ¿Cabe en una línea? → una línea7. Sólo entonces: lo mínimo que funcione

El ejemplo canónico del proyecto, al que hacíamos referencia en la introducción, lo resume bien: ante la petición de un selector de fechas, el resultado deja de ser una librería más un componente y pasa a ser, gracias a Ponytail, <input type="date">.

Dos matices importantes:

La escalera se aplica después de entender el problema, no en lugar de entenderlo. El agente sigue obligado a leer el código afectado y a seguir el flujo real antes de elegir peldaño. Perezoso con la solución, nunca con la lectura.
Hay cuatro cosas que nunca se recortan: validación en las fronteras de confianza, gestión de pérdida de datos, seguridad y accesibilidad. La regla no es "menos tokens", es "sólo lo que la tarea necesita".

Según el benchmark que publica el proyecto (sesiones reales de un agente sobre un repositorio FastAPI + React, con y sin el skill), los resultados frente a la línea base son un 54% menos de líneas de código, un 22% menos de tokens, un 20% menos de coste y un 27% menos de tiempo, sin penalización en las comprobaciones de seguridad. Como siempre con los benchmarks, conviene tomarlos como orden de magnitud y no como promesa: el ahorro es enorme donde hay una trampa clara de sobre-construcción y casi nulo donde el código ya era mínimo.

Ponytail funciona en un buen número de agentes (Claude Code, Codex, Copilot CLI, Gemini CLI, Cursor, Devin...), y OpenCode es uno de los que tiene soporte de primera clase mediante plugin.

El valor de la combinación¶

Por separado cada pieza es útil, pero es al combinarlas cuando desaparecen las limitaciones que mencionábamos al principio. Cada una cubre una capa distinta y no se solapan: OmniRoute decide quién responde, OpenCode decide qué se hace, y Ponytail decide cuánto código se escribe.

Problema	Cómo lo resuelve la combinación
Suscripción mensual	OpenCode es gratuito y OmniRoute se conecta a capas gratuitas de decenas de proveedores. El coste de entrada es 0 €.
Agotamiento de cuota	El fallback de OmniRoute salta al siguiente proveedor sin interrumpir la sesión del agente.
Dependencia de un proveedor	El agente sólo conoce un endpoint (`localhost:20128/v1`); cambiar de modelo o de proveedor no requiere tocar el agente.
Consumo excesivo de tokens	Los motores de compresión de OmniRoute reducen el tamaño de los prompts que envía el agente, que suelen ser grandes por el contexto del repositorio.
Falta de visibilidad del gasto	El panel de OmniRoute centraliza el consumo de todos los proveedores y de todas las herramientas conectadas.
Código sobredimensionado	Ponytail recorta lo que el agente construye, lo que a su vez reduce el código a revisar, mantener y volver a meter en el contexto en las siguientes sesiones.

La combinación de las tres piezas tiene un efecto multiplicador sobre la cuota disponible: Ponytail reduce los tokens de salida (menos código generado), la compresión de OmniRoute reduce los de entrada (menos contexto enviado) y el fallback aprovecha la cuota de todos los proveedores conectados.

Un beneficio adicional: como OmniRoute expone un endpoint estándar, el mismo gateway sirve simultáneamente a OpenCode en la terminal, a una extensión de VSCode o a cualquier otro cliente compatible con la API de OpenAI. Se configura una vez y lo aprovecha todo el entorno.

Modelos modestos, mejores resultados

Un efecto colateral interesante de Ponytail es que hace más viable trabajar con los modelos gratuitos, que suelen ser más pequeños. Cuanto menor es el volumen de código que se le pide generar a un modelo, menos oportunidades tiene de equivocarse; el skill reduce precisamente el tamaño de lo que se le encarga en cada paso.

Sobre las capas gratuitas

Las condiciones de las capas gratuitas de los proveedores cambian con frecuencia y algunas desaparecen sin previo aviso. La ventaja del enfoque con OmniRoute es que esos cambios se absorben en el gateway (conectando otro proveedor) sin tocar la configuración del agente. Conviene también revisar las políticas de privacidad de cada proveedor gratuito antes de enviarles el código de un proyecto sensible.

Instalación¶

Todo el procedimiento se ha realizado sobre Linux. En Windows y MacOS los pasos son equivalentes, cambiando la forma de instalar los requisitos.

Los tres proyectos se distribuyen vía npm, así que el único requisito común es disponer de Node.js reciente (versión 22 o superior).

1	`node --version`

Instalación de OpenCode¶

La forma recomendada es el script oficial de instalación:

1	`curl -fsSL https://opencode.ai/install \| bash`

Alternativamente, según el sistema:

npm install -g opencode-ai # npm (también bun, pnpm o yarn)brew install anomalyco/tap/opencode # MacOS / Linux con Homebrewsudo pacman -S opencode # Arch Linux (repositorios oficiales)paru -S opencode-bin # Arch Linux (AUR, última versión)

Comprobamos la instalación lanzando el agente dentro de cualquier directorio:

1	`opencode`

En este punto OpenCode arrancará pero pedirá credenciales de algún proveedor. No hace falta darle ninguna todavía: ese hueco lo va a ocupar OmniRoute. Por ahora simplemente salimos del programa.

Instalación de OmniRoute¶

12	`npm install -g omnirouteomniroute`

El comando omniroute levanta a la vez la API y el panel web en el puerto 20128:

Panel: http://localhost:20128
API compatible con OpenAI: http://localhost:20128/v1

Existen también otras formas de despliegue, útiles si se quiere dejar el gateway funcionando de forma permanente:

1	`docker run omniroute # contenedor`

Además del paquete npm y el contenedor, el proyecto distribuye una aplicación de escritorio (Electron), imágenes para arm64 (funciona en una Raspberry Pi) y es ejecutable en Android bajo Termux. Una opción interesante es dejar OmniRoute corriendo en un VPS o en un servidor casero y apuntar contra él desde todos los equipos de desarrollo.

Instalación de Ponytail¶

Ponytail no se instala en el sistema, se declara como plugin de OpenCode. Basta con añadir esta entrada al fichero de configuración opencode.json (en el apartado siguiente se muestra el fichero completo con esta y el resto de piezas):

1	`{ "plugin": ["@dietrichgebert/ponytail"] }`

OpenCode descarga el paquete desde npm la primera vez que arranca con esa configuración. Si se prefiere trabajar sobre una copia local del repositorio, para poder modificar las reglas, se clona y se apunta al fichero del plugin:

1	`git clone https://github.com/DietrichGebert/ponytail.git ~/ponytail`

1	`{ "plugin": ["/home/usuario/ponytail/.opencode/plugins/ponytail.mjs"] }`

Las rutas relativas (del tipo ./.opencode/plugins/ponytail.mjs) se resuelven respecto al opencode.json que las declara, de modo que para compartir un mismo checkout entre varios proyectos hay que usar la ruta absoluta, como en el ejemplo.

Sin plugin también funciona

El repositorio incluye las reglas en formato AGENTS.md y en los formatos de rules de Cursor, Devin, Cline, Kiro, Copilot, etc. Copiando ese fichero al proyecto se obtiene el comportamiento siempre activo en prácticamente cualquier agente. Lo que añade el plugin de OpenCode son los comandos /ponytail y los niveles de intensidad.

Configuración conjunta¶

La integración consiste en que OpenCode deje de hablar con los proveedores y hable únicamente con OmniRoute, y en que Ponytail se inyecte en cada turno de la conversación. Son cinco pasos.

1. Conectar proveedores en OmniRoute¶

Con omniroute en marcha, abrimos http://localhost:20128 y vamos a la sección Providers (recomiendo configurar el interfaz en idioma English ya que si no aparecen numerosas cadenas precedidas de la partícula __MISSING__; también utilizar el campo de búsqueda, ya que el número de grupos de configuración de OmniRoute es enorme). Ahí aparece el catálogo con un indicador de cuáles tienen capa gratuita. Conviene conectar varios, ya que el valor del sistema está justamente en la redundancia: cuando uno agota su cuota, el resto siguen disponibles. Los proveedores sin necesidad de clave (No Auth) están conectados por defecto.

El catálogo está clasificado por categorías, y la categoría marca el procedimiento de conexión:

Categoría	Cómo se conecta
No Auth	Están activos desde el primer arranque. Aunque desactivaremos algunos como luego veremos.
Free Tier	Capa gratuita que sí requiere darse de alta en el proveedor y pegar una clave de API.
OAuth	Botón de inicio de sesión para proveedores en los que ya tengamos cuenta: OmniRoute abre el flujo del proveedor y guarda el token resultante.
API Key	Proveedores de pago (algunos con crédito inicial de regalo); se pega la clave.
Local	Modelos que corren en la propia máquina (Ollama, LM Studio, vLLM…); se indica la URL local.

El filtro de la parte superior de la pantalla permite quedarse sólo con las que interesan, y el buscador acepta el nombre o el identificador del proveedor.

Proveedores sin autenticación¶

En general la elección y configuración de los proveedores es la parte más complicada, farragosa y que más tiempo consume de todo el proceso descrito en este artículo.

No solo eso, algunos de los proveedores activados por defecto como los de la categoría "No Auth", pueden provocar problemas. Durante las primeras sesiones de uso de OpenCode observé que la mayoría de las peticiones obtenían una respuesta vacía. Tras investigar encontré que el problema era la intervención de proveedor "Augment (Auggie CLI)" que por tanto recomiendo desactivar.

Además mirando los logs de la consola de OmniRoute (Monitoring > Logs), encontré que los proveedores "Chipotle Pepper AI (Free)" y "DuckDuckGo AI Chat" fallaban siempre, por lo que aunque no introducen respuestas incorrectas como "Augment (Auggie CLI)", retrasan el recorrido de la cascada de proveedores, por lo que recomiendo desactivarlos también. El proveedor "Veo AI Free" lo desactivaremos, dado que sólo ofrece modelos de vídeo que no nos van a servir para codificar.

Proveedores con clave de API gratuita¶

El procedimiento es siempre el mismo, cambiando únicamente el sitio del que se obtiene la clave:

Darse de alta en el proveedor y generar una clave de API en su panel (el enlace suele estar en la propia ficha del proveedor en OmniRoute).
En OmniRoute, Providers → buscar el proveedor → botón de conectar/configurar.
Pegar la clave en el formulario y guardar.
Pulsar el botón de Test de la tarjeta del proveedor. Si responde correctamente, sus modelos pasan a formar parte del catálogo del gateway y entran automáticamente en el pool del modelo auto.

Los proveedores de esta categoría son los que más nos van a permitir aprovechar las ventajas de OmniRoute. Son numerosos, pero como se comentaba en el apartado anterior, requiere bastante trabajo configurarlos (obtención de API Keys de distintos proveedores) y mantenerse al día de cuáles cambian en operativa o son más o menos recomendables en un momento dado.

Algunos documentos que seguir para mantener en buena forma la lista de proveedores gratuitos son los siguientes:

Algunos de los proveedores de este tipo que me parecen recomendables en el momento de escribir este artículo son:

Gemini (Google AI Studio)
Groq
Mistral
Cloudflare Workers AI: Tras introducir la API Key, se produce el intento de conexión con los modelos que fallará indicando que hace falta un "Account ID" además. El "Account ID" es el hash que aparece a continuación de la URL https://dash.cloudflare.com una vez creada e iniciada la sesión. Introduciremos ese hash en el campo "Account ID" de los ajustes del provider.
Pollinations AI: Aunque en el cuadro de conexión se indica que la API Key es opcional, es mejor crear una.

Proveedores OAuth¶

Con estos no hay clave que copiar: se pulsa el botón de conexión de la tarjeta, se abre el flujo de inicio de sesión del proveedor en el navegador, y al terminar OmniRoute guarda las credenciales cifradas en su base de datos local. Es el caso de las cuentas de herramientas que ya se estén usando (Copilot, Cursor, Kilo Code, Qoder, etc.).

Revisa los términos de servicio

Varios de estos proveedores son en realidad servicios pensados para consumirse desde su propio cliente, y algunos prohíben expresamente en sus condiciones el uso a través de proxies o clientes de terceros. La ficha del proveedor en OmniRoute lo advierte cuando es el caso. Conviene leer esos avisos antes de conectar una cuenta que interese conservar.

Depurar el pool para uso agéntico¶

Hay una cuestión que no aparece en la documentación de OmniRoute y que, en mi experiencia, ha resultado fundamental para que el montaje resulte operativo. Se trata de que no todos los proveedores del catálogo sirven para alimentar a un agente.

La razón es que un agente como OpenCode no se limita a pedir texto: envía en cada petición la lista de herramientas de las que dispone (leer ficheros, ejecutar comandos, buscar en el repositorio…) y espera que el modelo responda con llamadas a esas herramientas. Los proveedores que son la API oficial de un modelo devuelven esas llamadas al cliente, que es lo correcto. Pero el catálogo incluye también dos tipos de entradas que no se comportan así:

Proxies de un cliente web (los que se conectan con la cookie de sesión de un chat, en lugar de con una clave de API). El servicio del otro lado tiene su propio motor de herramientas e intenta ejecutarlas él, en su entorno, en lugar de devolverlas.
Front-ends de agentes (servicios pensados para consumirse desde su propia herramienta de línea de comandos). Traen su propio catálogo de herramientas y no encajan como motor de otro agente.

El síntoma es desconcertante, porque el agente no da ningún error: simplemente devuelve una respuesta vacía, o un texto en el que el modelo explica que no ha podido explorar el repositorio y nos pide, por ejemplo, que le peguemos nosotros el contenido de los ficheros.

Un test de admisión¶

La forma fiable de decidir si un proveedor entra o no en el pool es preguntárselo al gateway: enviar una petición con una herramienta y comprobar si el modelo la invoca. La respuesta debe contener un bloque tool_calls con el nombre de la herramienta y sus argumentos; si en su lugar llega prosa, ese proveedor no sirve.

No basta con lanzar una petición contra auto/coding y dar por bueno el pool. El enrutado de auto tiende a pegarse al último proveedor que funcionó y no garantiza que todos los candidatos reciban tráfico. Hay que probar cada proveedor por separado.

El comportamiento problemático que queremos detectar (proxies que ejecutan las herramientas ellos mismos, front-ends con su propio catálogo) es una propiedad del proveedor, no del modelo individual: un proxy o pasa las tool_calls al cliente o no las pasa, independientemente del modelo que tenga detrás. Por eso basta con probar un modelo representativo por proveedor, identificable por el prefijo antes de la barra (groq/, mistral/, cf/...), en lugar de los cientos de modelos del catálogo. En realidad probaremos los 5 primeros modelos de cada proveedor por si alguno falla por alguna razón específica. El filtro de jq excluye sólo los modelos virtuales auto/*:

 1 2 3 4 5 6 7 8 910111213141516171819202122232425262728293031323334353637383940

API="http://localhost:20128/v1"KEY="sk-tu-clave-omniroute"# Lista de proveedores (excluyendo auto/*)providers=$(curl -s "$API/models" -H "Authorization: Bearer $KEY" \ | jq -r '[.data[].id | select(startswith("auto/") | not)] | group_by(split("/")[0]) | map(.[0]) | .[]' \ | cut -d/ -f1 | sort -u)for prov in $providers; do # Hasta 5 modelos de este proveedor prov_models=$(curl -s "$API/models" -H "Authorization: Bearer $KEY" \ | jq -r --arg p "$prov" '[.data[].id | select(startswith($p+"/"))][:5][]') status="" tested="" for model in $prov_models; do tested="$model" resp=$(curl -s -i "$API/chat/completions" \ -H "Authorization: Bearer $KEY" \ -H "Content-Type: application/json" \ -d "{\"model\":\"$model\",\"stream\":false,\"messages\":[{\"role\":\"user\",\"content\":\"Lee el fichero /etc/hostname\"}],\"tools\":[{\"type\":\"function\",\"function\":{\"name\":\"read\",\"description\":\"Lee un fichero\",\"parameters\":{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\"}},\"required\":[\"path\"]}}}]}") http_code=$(printf '%s' "$resp" | head -1 | grep -o '[0-9][0-9][0-9]') body=$(printf '%s' "$resp" | sed -n '/^\r\?$/,$p' | tail -n +2) if [ "$http_code" = "200" ]; then if printf '%s' "$body" | jq -e '.choices[0].message.tool_calls[0].function.name' >/dev/null 2>&1; then status="OK" else status="FALLA (sin tool_calls)" fi break elif [ "$http_code" = "401" ] || [ "$http_code" = "403" ]; then status="FALLA (auth $http_code)" break else continue # 404, 400... modelo no disponible, probar el siguiente fi done [ -z "$status" ] && status="FALLA (sin modelos válidos)" printf '%-24s %-45s %s\n' "$status" "$prov" "$tested"done

Requiere jq. El script distingue tres causas de fallo:

FALLA (sin tool_calls): el proveedor respondió con un 200 pero devolvió prosa en lugar de una llamada a la herramienta. Es el problema que venimos buscando: proxy que ejecuta las tools él mismo o front-end con su propio catálogo. => Desconectar.
FALLA (auth 401/403): la clave del proveedor está caducada, mal configurada o sin cuota. No es un problema de tools, sino de configuración. => Hay que arreglar la conexión en Providers (o desconectarla si ya no tiene remedio).
FALLA (sin modelos válidos): todos los modelos probados devolvieron 404 o 400. El proveedor está caído o su catálogo ha cambiado. => Revisar en Providers.

En la salida, la columna de la derecha muestra el modelo con el que se obtuvo el resultado. Es un trabajo que se hace una vez, y que hay que repetir sólo al conectar un proveedor nuevo.

Dos síntomas que reconocer en los logs¶

En Monitoring > Logs hay dos patrones que delatan a un proveedor que conviene retirar:

200 con TO: 0 en unos pocos milisegundos: el proveedor ha devuelto una respuesta vacía con estado de éxito. Una inferencia real nunca tarda 15 ms.
Respuestas lentas cuyo contenido es texto donde debería haber tool_calls, a menudo con mensajes de error del propio servicio remoto explicando que las herramientas no existen.

El fallback no salta con los fallos disfrazados de éxito

Conviene entender bien el límite del sistema. La cascada de reintentos de OmniRoute funciona con los fallos explícitos: un 429 por cuota, un 502 o un timeout hacen que la petición se reintente contra el siguiente proveedor, y eso se aprecia perfectamente en el registro. Pero los dos casos anteriores llegan al gateway como respuestas correctas: un 200 con un cuerpo vacío es, para un router, una respuesta válida. Ningún gateway puede arbitrar eso sin inspeccionar semánticamente el contenido de cada respuesta.

De ahí que la curación del pool sea responsabilidad nuestra, y que sea un paso que conviene no saltarse. Dicho de otro modo: el enrutado automático es tan bueno como el peor proveedor aparentemente sano del pool.

2. Crear una clave de API de OmniRoute¶

En el panel, sección API Manager → Create API Key. Le damos un nombre descriptivo (por ejemplo opencode) y copiamos la clave generada, con formato sk-xxxxxxxx-xxxxxxxx.

Esta clave es local: es la que usarán nuestros clientes (OpenCode en este caso) para autenticarse contra OmniRoute, y no tiene nada que ver con las claves de los proveedores, que quedan custodiadas por OmniRoute.

Podemos verificar que el gateway responde y ver qué modelos ofrece:

1	`curl http://localhost:20128/v1/models -H "Authorization: Bearer sk-tu-clave-omniroute"`

3. Declarar OmniRoute como proveedor en OpenCode¶

OpenCode admite cualquier proveedor compatible con OpenAI declarándolo en su fichero de configuración. Para que la configuración aplique a todos los proyectos, la escribimos en ~/.config/opencode/opencode.json:

 1 2 3 4 5 6 7 8 910111213141516171819202122

{ "$schema": "https://opencode.ai/config.json", "plugin": ["@dietrichgebert/ponytail"], "provider": { "omniroute": { "npm": "@ai-sdk/openai-compatible", "name": "OmniRoute", "options": { "baseURL": "http://localhost:20128/v1", "apiKey": "sk-tu-clave-omniroute" }, "models": { "auto": { "name": "Auto (equilibrado)" }, "auto/coding": { "name": "Auto (calidad para código)" }, "auto/cheap": { "name": "Auto (menor coste)" }, "auto/fast": { "name": "Auto (menor latencia)" }, "auto/offline": { "name": "Auto (máxima cuota disponible)" } } } }, "model": "omniroute/auto/coding"}

Los puntos importantes de esta configuración:

npm: el adaptador @ai-sdk/openai-compatible es el que se usa con endpoints /v1/chat/completions, que es el caso de OmniRoute.
options.baseURL: el endpoint del gateway. Si OmniRoute está en otra máquina, aquí va su IP o dominio.
options.apiKey: la clave de API que creamos en OmniRoute.
models: no hace falta enumerar modelos concretos de proveedores; basta con declarar los modelos virtuales auto, que son los que activan el enrutado inteligente y el fallback. Si se quiere fijar un modelo concreto, se puede añadir con el identificador que devuelve /v1/models, la consulta del punto anterior.
model: modelo por defecto al arrancar. auto/coding es una buena elección para desarrollo; auto/offline resulta útil cuando lo prioritario es no quedarse sin cuota.
plugin: la lista de plugins de OpenCode, donde entra Ponytail.

Clave fuera del fichero de configuración

Si el fichero de configuración se va a versionar (por ejemplo en un repositorio de dotfiles), es preferible no escribir la clave en él. OpenCode permite almacenar credenciales con el comando /connect (opción Other, id omniroute), en cuyo caso se puede omitir options.apiKey del JSON.

También es posible ubicar el fichero como opencode.json en la raíz de un proyecto concreto, en cuyo caso su configuración se combina con la global. Esto resulta práctico para forzar un modelo distinto en un proyecto determinado.

4. Ajustar el nivel de Ponytail¶

Ponytail no necesita fichero de configuración: funciona nada más declararlo como plugin. Lo único que conviene decidir es el nivel de intensidad, que se cambia en caliente desde la TUI:

/ponytail → informa del nivel actual/ponytail lite → recorte suave/ponytail full → nivel por defecto/ponytail ultra → recorte agresivo/ponytail off → desactivado para esta sesión

El nivel por defecto es full. Para fijar otro en todas las sesiones nuevas se usa la variable de entorno PONYTAIL_DEFAULT_MODE o el campo defaultMode de ~/.config/ponytail/config.json:

1	`export PONYTAIL_DEFAULT_MODE="full"`

Mientras está activo, el conjunto de reglas se inyecta también en los subagentes que lance el agente principal. Si interesa excluir a alguno (por ejemplo los subagentes de búsqueda, que no escriben código), se puede acotar con una expresión regular contra el tipo de subagente definida en la siguiente variable de entorno:

1	`export PONYTAIL_SUBAGENT_MATCHER="build\|code"`

5. Verificar la integración¶

Arrancamos el agente y comprobamos que aparece el proveedor:

1	`opencode`

Dentro de la TUI, el comando /models debe mostrar las entradas de OmniRoute.

Desde un directorio que contenga un repositorio o un proyecto, ejecutamos una prueba rápida en modo CLI no interactivo:

1	`opencode run "Resume en tres líneas qué hace este repositorio" --model omniroute/auto/coding`

Mientras se ejecuta, en el panel de OmniRoute puede verse en tiempo real qué proveedor ha atendido la petición (Monitoring > Logs), cuántos tokens se han consumido y cuántos ha ahorrado la compresión. Si un proveedor falla, en el registro se aprecia el salto automático al siguiente.

Para comprobar que Ponytail está cargado basta con ejecutar /ponytail en la TUI, que responde con el nivel activo, o /ponytail-help, que lista sus comandos.

Aparente ERROR de arranque de Ponytail

Si se arranca OpenCode con --print-logs puede aparecer esta línea al cargar la configuración:

1	`ERROR message="failed to load plugin" path=@dietrichgebert/ponytail error="path must be a string or a file descriptor"`

Es engañosa: OpenCode intenta cargar el plugin por dos rutas y una de ellas falla, pero la otra lo carga correctamente. La prueba de que Ponytail está operativo es que /ponytail responda con el nivel activo. Hay que tener en cuenta además que el nivel se persiste entre sesiones (en ~/.config/opencode/.ponytail-active): un /ponytail off de una prueba anterior deja el plugin cargado pero desactivado. Ante la duda: /ponytail full y preguntar al agente qué dice su system prompt sobre PONYTAIL.

Variables de entorno para el resto de herramientas

Exportando estas variables en el .bashrc o .zshrc, cualquier otra herramienta que respete la convención de OpenAI usará también el gateway sin configuración adicional:

12	`export OPENAI_BASE_URL="http://localhost:20128/v1"export OPENAI_API_KEY="sk-tu-clave-omniroute"`

Tipos de proyectos y operativa¶

Una vez montado el entorno, la operativa es esencialmente la misma con independencia del lenguaje, del tamaño del proyecto o la naturaleza de la tarea. Lo que cambia entre unos casos y otros no es el procedimiento, sino el modelo que conviene seleccionar, el nivel de recorte que interesa y la cantidad de contexto que hay que preparar. Por eso describimos primero el flujo común y después los ajustes por tipo de proyecto.

Operativa común¶

Situarse en el repositorio y arrancar el agente:
12
cd mi-proyectoopencode
Generar el fichero de contexto la primera vez, con el comando /init dentro de la TUI. OpenCode explora el repositorio y escribe un AGENTS.md con la descripción del proyecto, los comandos de compilación y test y las convenciones detectadas. Merece la pena revisarlo y completarlo a mano: es el documento que más influye en la calidad de los resultados posteriores, y conviene versionarlo con el proyecto.
Planificar antes de ejecutar. Para cualquier cambio que no sea trivial, pedir primero un plan en lugar de la implementación directa. OpenCode dispone de un modo de planificación que no escribe en disco, y revisar el plan cuesta mucho menos que revisar un diff equivocado de 400 líneas.
Iterar en pasos pequeños, validando con las herramientas del propio proyecto (compilador, linter, tests) tras cada paso. El agente puede ejecutar esos comandos por sí mismo si están documentados en AGENTS.md.
Pasar la revisión de Ponytail antes de dar la tarea por buena, con /ponytail-review. Analiza el diff actual buscando sobre-ingeniería y devuelve una lista de cosas a borrar. Es el paso que más rápido amortiza el tiempo invertido.
Revisar el diff y confirmar con el control de versiones. Conviene trabajar siempre sobre una rama y hacer commits pequeños: es la red de seguridad natural cuando quien escribe el código es un agente.
Limpiar el contexto entre tareas con /new. Arrastrar el contexto de una tarea terminada empeora los resultados y dispara el consumo de tokens. En el apartado siguiente se detalla la gestión de sesiones.
Vigilar el panel de OmniRoute de vez en cuando para ver qué proveedores se están usando, cuáles se han agotado y si el ahorro por compresión es el esperado.

Gestión de sesiones en OpenCode¶

Al empezar a trabajar con OpenCode sorprende comprobar que, por mucho que se salga de la TUI con Ctrl-d o con /exit, las sesiones siguen apareciendo en el listado. No es un problema de cierre incompleto ni un proceso que se quede colgado: es que una sesión no es un proceso, es una conversación persistida. Salir de la TUI termina la interfaz, pero el historial de la conversación (mensajes, herramientas ejecutadas, ficheros tocados, consumo de tokens) se guarda en la base de datos local de OpenCode para poder retomarlo después. Y como cada invocación de opencode sin argumentos abre una sesión nueva, en un par de días de uso el listado tiene decenas de entradas.

Dicho de otra forma: "cerrar" no significa "borrar". Lo que hay que adquirir es la costumbre de reutilizar y de podar.

Retomar en lugar de crear¶

Lo primero es dejar de arrancar siempre en blanco. Estas son las tres formas de continuar un trabajo previo:

opencode --continue # retoma la última sesión del proyecto actual (-c)opencode --session <sessionID> # retoma una sesión concreta (-s)opencode --session <sessionID> --fork # la bifurca en una copia, dejando la original intacta

Y desde dentro de la TUI, el comando /sessions (alias /resume y /continue, atajo Ctrl-x l) abre el selector para saltar de una sesión a otra sin salir del programa.

La opción --fork es especialmente útil cuando una conversación ha llegado a un punto interesante y se quiere probar dos caminos distintos: se bifurca y cada rama sigue por su lado, igual que con git branch.

Cerrar bien cada tarea¶

Dentro de la TUI hay dos comandos que marcan el final de una tarea:

/new (alias /clear, atajo Ctrl-x n): abre una sesión nueva y limpia. Es lo que hay que usar al cambiar de tarea, en lugar de seguir escribiendo en la conversación anterior.
/compact (alias /summarize, atajo Ctrl-x c): resume la conversación actual para liberar ventana de contexto sin perder el hilo. Es la alternativa cuando se quiere continuar con la misma tarea pero el contexto se ha vuelto pesado.

Si de una sesión interesa conservar el resultado, /export vuelca la conversación a Markdown y la abre en el editor, y opencode export <sessionID> hace lo propio en JSON desde la línea de comandos.

Inventariar y podar¶

Desde fuera de la TUI se gestiona el inventario completo:

opencode session list # listado de sesionesopencode session list -n 20 # limitar el número de entradasopencode session list --format json # salida procesable por scriptopencode session delete <sessionID> # eliminar una sesión

Y para ver el coste de lo acumulado, que en este montaje es lo que determina cuánta cuota gratuita se está quemando:

123	`opencode stats # consumo de tokens y costeopencode stats --days 7 --models # últimos 7 días, desglosado por modeloopencode stats --project # sólo el proyecto actual`

Flujo de trabajo¶

Reuniendo lo anterior, la rutina que mantiene el listado bajo control es:

Una sesión por tarea, no por jornada ni por proyecto. La unidad natural es lo que acaba en un commit.
Retomar con -c cuando se vuelve a una tarea a medias, en vez de arrancar opencode a secas y volver a explicar el contexto (que además se paga en tokens).
/new al cambiar de tarea y /compact si la tarea se alarga pero sigue siendo la misma.
Exportar lo que merezca la pena antes de dar por cerrada una sesión con conclusiones valiosas.
Poda periódica, por ejemplo semanal, revisando opencode session list y borrando con opencode session delete todo lo que ya esté commiteado y no aporte nada.
Revisar opencode stats en esa misma poda, para tener la foto del consumo junto a la del panel de OmniRoute.

Las sesiones van por proyecto

OpenCode asocia las sesiones al directorio de trabajo desde el que se lanzó, así que --continue o -c retoma la última sesión de ese proyecto, no la última en términos absolutos. Es un detalle que ayuda: trabajar siempre desde la raíz del repositorio mantiene los listados ordenados por proyecto de forma natural.

Comandos de Ponytail¶

Más allá del nivel de intensidad, el skill aporta un puñado de comandos que encajan en distintos momentos del flujo anterior:

Comando	Para qué sirve
`/ponytail [lite \\| full \\| ultra \\| off]`	Ajusta la intensidad o la desactiva. Sin argumento informa del nivel actual.
`/ponytail-review`	Revisa el diff actual en busca de sobre-ingeniería y devuelve una lista de borrado.
`/ponytail-audit`	Lo mismo, pero sobre todo el repositorio en lugar de sobre el diff.
`/ponytail-debt`	Recopila en un registro los atajos marcados con `ponytail:` que se hayan ido aplazando.
`/ponytail-gain`	Muestra el marcador de impacto medido (menos código, menos coste, más velocidad).
`/ponytail-help`	Referencia rápida de los comandos anteriores.

Cuando el agente decide no construir algo, deja un comentario del tipo ponytail: browser has one explicando el peldaño de la escalera en el que se detuvo. Esos comentarios son los que después recoge /ponytail-debt, de forma que las decisiones de "esto ya se hará si hace falta" quedan registradas en lugar de perderse.

Ajustes según el tipo de proyecto¶

Lo único que varía de forma apreciable entre escenarios es la elección de modelo y la preparación del contexto:

Proyectos nuevos desde cero (greenfield). Hay poco contexto que cargar y mucho código que generar. Es el escenario ideal para las capas gratuitas: auto/cheap o auto/offline dan buen resultado y el consumo de tokens de entrada es bajo. Conviene empezar pidiendo el andamiaje del proyecto y el fichero de dependencias, y sólo después las funcionalidades. También es donde más se nota Ponytail, porque es donde el agente tiene más libertad para inventar estructura de más.
Mantenimiento y evolución de código existente. Aquí el cuello de botella es el contexto: el agente necesita leer bastante código antes de tocar nada. Interesa un AGENTS.md detallado, activar la compresión de contexto de OmniRoute y usar auto/coding para las tareas de modificación. Es también el caso donde más se nota el fallback, porque las sesiones son largas. El peldaño "¿ya está en este repositorio?" de Ponytail resulta especialmente valioso, ya que evita el clásico duplicado de un helper que ya existía tres directorios más allá.
Depuración de errores. El flujo es el mismo, pero funciona mucho mejor si se le proporciona al agente una forma de reproducir el fallo (un test que falle, la traza completa, el comando exacto). Modelos con capacidad de razonamiento explícito dan mejores resultados; en OmniRoute se pueden seleccionar las variantes thinking de los modelos que las ofrezcan. Un nivel lite de Ponytail, o incluso off, puede ser preferible aquí: al depurar interesa entender, no recortar.
Scripting y automatización. Aquí interesa el modo CLI no interactivo, que permite integrar el agente en scripts, hooks de git o tareas programadas:
12
opencode run "Actualiza el CHANGELOG con los commits desde la última etiqueta" \ --model omniroute/auto/fast
Refactorizaciones amplias y repetitivas. Trocear el trabajo en tareas independientes y lanzarlas por separado, en lugar de pedir un cambio masivo en una sola sesión. Además de dar mejores resultados, evita agotar la ventana de contexto y la cuota de un proveedor de una sentada. Si lo que se busca es precisamente adelgazar código heredado, /ponytail-audit sobre el repositorio completo y /ponytail ultra son el punto de partida natural.
Proyectos con código sensible. Si no se puede enviar el código a terceros, la misma configuración sirve conectando en OmniRoute un proveedor local (Ollama o LM Studio en la propia máquina) en lugar de los servicios gratuitos. Cambia el proveedor conectado en el panel; ni OpenCode ni el flujo de trabajo se tocan.

Conclusión¶

La combinación de OpenCode, OmniRoute y Ponytail proporciona un entorno de desarrollo agéntico completo con coste de entrada nulo y sin las interrupciones por cuota agotada que caracterizan a las alternativas comerciales. Cada pieza ataca un frente distinto: el agente aporta las capacidades, el gateway la cuota y la independencia de proveedor, y el skill la disciplina para que el código generado sea el mínimo necesario. Y las tres se declaran en un único fichero de configuración de unas veinte líneas.

El precio a pagar es una configuración inicial algo más laboriosa que la de un producto cerrado y la necesidad de revisar de vez en cuando qué proveedores gratuitos siguen operativos. A cambio se obtiene algo que las suscripciones no dan: independencia respecto al proveedor, visibilidad completa de lo que consume el agente y menos código del que arrepentirse.

OpenCode, OmniRoute, and Ponytail Installation

Sun, 26 Jul 2026 12:00:00 +0200

AI-assisted development began as intelligent line-level code completion. It evolved into a "second opinion" that reviewed file-level code and suggested changes. In the last two years, a major step forward has been taken to reach the current paradigm, agentic development: an agent that works at the project-level, edits files, executes commands, performs changes that were previously only suggested, runs tests, and iterates until the task is complete. The problem is that all commercial tools of this type (Claude Code, Cursor, Devin, Copilot, Codex, etc.) share two limitations: a monthly subscription and quotas that run out just when the session is getting interesting. Because here we don't consider the use via API, which for the personal scope is unaffordable.

There is also a third, quieter but also expensive problem: agents tend to over-build. They are asked for a date picker and end up installing a library, writing a wrapper component, and adding a stylesheet. Every extra line is paid for twice: in tokens when generating it and in tokens every time it re-enters the context.

This article describes how to set up a complete agentic development environment by combining three open-source projects that address these exact limitations:

OpenCode: the terminal-based programming agent.
OmniRoute: the model router/gateway that powers the agent.
Ponytail: the skill that enforces minimal code discipline on the agent.

Product Description¶

OpenCode¶

OpenCode is an open-source programming agent that runs in the terminal (TUI) and, most importantly for our purpose, is model-provider agnostic. Unlike Claude Code (tied to Anthropic) or Codex (tied to OpenAI), OpenCode allows configuring any provider, including those exposing an OpenAI-compatible API, which today is practically all of them.

Its main features:

Terminal interface with persistent sessions, context management, and undo for applied changes.
Access to tools: file reading and writing, command execution, repository search, version control.
Per-project context file (AGENTS.md) generated with /init to instruct the agent on repository conventions.
MCP (Model Context Protocol) support to add external tools.
Non-interactive CLI mode (opencode run "...") for automations and scripts.
Specialized agents and work modes (e.g., a plan mode that makes no changes, designed for the pre-planning phase).

OmniRoute¶

OmniRoute is a local, open-source AI gateway. It is installed on your own machine (or a VPS), sets up an OpenAI-compatible API endpoint and a web administration panel, and from there routes each request to any of the hundreds of cataloged providers, about 90 of which have a free tier.

The interesting thing is not the catalog itself, but what it does with it:

Automatic routing: using the auto virtual model, OmniRoute builds a combo of your connected providers and chooses one for each request based on live scoring. Variants exist: auto/coding (quality for code generation), auto/fast (lowest latency), auto/cheap (cheapest per token), and auto/offline (most available quota margin).
Cascading fallback: when a provider returns a quota error, rate limit, or 4xx-5xx, the request is transparently retried against the next provider in the list. This prevents the classic "quota exceeded, come back in five hours" message.
Context compression: a set of engines that trim the prompt (deduplication, history pruning, file compacting), enabling significant token savings, especially valuable when working with free tiers measured in tokens/day.
Control panel at http://localhost:20128 with per-provider usage stats, API key management, and assisted configuration for common CLI tools.
Local-first: provider keys and traffic stay on your machine; OmniRoute is not a cloud service requiring a subscription.

Ponytail¶

Ponytail is a skill, a set of instructions injected into the agent's context every turn to modify its behavior. Its sole mission is to combat over-engineering by forcing the agent to go through a decision ladder before writing a single line, stopping at the first rung that solves the problem:

1. Does this need to exist? → no: don't do it (YAGNI)2. Already in this codebase? → reuse it, don't rewrite3. Stdlib does it? → use it4. Native platform feature? → use it5. Installed dependency? → use it6. One line? → one line7. Only then: the minimum that works

The project's canonical example, which we referenced in the introduction, sums it up well: when asked for a date picker, the result is no longer a library plus a component but, thanks to Ponytail, <input type="date">.

Two important nuances:

The ladder is applied after understanding the problem, not instead of it. The agent is still required to read the affected code and trace the actual flow before picking a rung. Lazy about the solution, never about reading.
Four things are never cut: trust-boundary validation, data-loss handling, security, and accessibility. The rule is not "fewer tokens," it's "only what the task needs."

According to the project's published benchmark (real agent sessions on a FastAPI + React repo, with and without the skill), results vs. the baseline show 54% fewer lines of code, 22% fewer tokens, 20% lower cost, and 27% less time, with no penalty to security checks. As always with benchmarks, take them as an order of magnitude rather than a promise: savings are huge where there's a clear over-build trap and near zero where code was already minimal.

Ponytail works with a good number of agents (Claude Code, Codex, Copilot CLI, Gemini CLI, Cursor, Devin...), and OpenCode is one of those with first-class plugin support.

The Value of the Combination¶

Separately each piece is useful, but combined, the limitations mentioned at the beginning vanish. Each covers a different layer and they don't overlap: OmniRoute decides who responds, OpenCode decides what is done, and Ponytail decides how much code is written.

Problem	How the combination solves it
Monthly subscription	OpenCode is free and OmniRoute connects to dozens of providers' free tiers. The entry cost is €0.
Quota exhaustion	OmniRoute's fallback jumps to the next provider without interrupting the agent's session.
Provider dependence	The agent only knows one endpoint (`localhost:20128/v1`); changing models or providers requires no changes to the agent.
Excessive token consumption	OmniRoute's compression engines reduce the size of agent prompts, which are typically large due to repository context.
Lack of spending visibility	The OmniRoute panel centralizes consumption across all providers and connected tools.
Oversized code	Ponytail trims what the agent builds, reducing code to review, maintain, and re-enter context in future sessions.

The combination of these three pieces has a multiplier effect on available quota: Ponytail reduces output tokens (less code generated), OmniRoute compression reduces input tokens (less context sent), and fallback utilizes every connected provider's quota.

An additional benefit: since OmniRoute exposes a standard endpoint, the same gateway simultaneously serves OpenCode in the terminal, a VSCode extension, or any other OpenAI-compatible client. Configure once, use everywhere.

Modest models, better results

An interesting side effect of Ponytail is that it makes working with free (typically smaller) models more viable. The less code a model is asked to generate, the fewer chances it has to make a mistake; the skill specifically reduces the size of the task in each step.

About Free Tiers

Provider free tier conditions change frequently and some disappear without notice. The advantage of the OmniRoute approach is that these changes are absorbed by the gateway (by connecting another provider) without touching the agent's configuration. It's also wise to review each free provider's privacy policy before sending them code from a sensitive project.

Installation¶

The entire procedure was performed on Linux. On Windows and MacOS, the steps are equivalent, only the method of installing requirements changes.

All three projects are distributed via npm, so the only common requirement is a recent version of Node.js (v22 or higher).

1	`node --version`

OpenCode Installation¶

The recommended way is through the official install script:

1	`curl -fsSL https://opencode.ai/install \| bash`

Alternatively, depending on the system:

npm install -g opencode-ai # npm (also bun, pnpm, or yarn)brew install anomalyco/tap/opencode # MacOS / Linux with Homebrewsudo pacman -S opencode # Arch Linux (official repos)paru -S opencode-bin # Arch Linux (AUR, latest version)

Verify the installation by launching the agent in any directory:

1	`opencode`

At this point, OpenCode will start but ask for provider credentials. No need to provide any yet: OmniRoute will fill that gap. For now, simply exit the program.

OmniRoute Installation¶

12	`npm install -g omnirouteomniroute`

The omniroute command starts both the API and the web panel on port 20128:

Panel: http://localhost:20128
OpenAI-compatible API: http://localhost:20128/v1

Other deployment methods exist, useful if you want to keep the gateway running permanently:

1	`docker run omniroute # container`

Besides the npm package and container, the project distributes a desktop app (Electron), arm64 images (works on a Raspberry Pi), and is executable on Android via Termux. An interesting option is to leave OmniRoute running on a VPS or home server and point all development machines at it.

Ponytail Installation¶

Ponytail isn't installed on the system; it's declared as an OpenCode plugin. Simply add this entry to your opencode.json configuration file (the next section shows the full file with this and the other pieces):

1	`{ "plugin": ["@dietrichgebert/ponytail"] }`

OpenCode downloads the package from npm the first time it starts with this configuration. If you prefer working with a local repo copy to modify rules, clone it and point to the plugin file:

1	`git clone https://github.com/DietrichGebert/ponytail.git ~/ponytail`

1	`{ "plugin": ["/home/user/ponytail/.opencode/plugins/ponytail.mjs"] }`

Relative paths (like ./.opencode/plugins/ponytail.mjs) resolve relative to the opencode.json declaring them; to share a single checkout across projects, use the absolute path, as shown in the example.

Works Without a Plugin Too

The repo includes rules in AGENTS.md format and rule formats for Cursor, Devin, Cline, Kiro, Copilot, etc. Copying that file to your project yields the same always-on behavior in almost any agent. The OpenCode plugin specifically adds the /ponytail commands and intensity levels.

Joint Configuration¶

The integration involves OpenCode stopping direct talk to providers to speak only to OmniRoute, while Ponytail is injected at every turn of the conversation. There are five steps.

1. Connect Providers in OmniRoute¶

With omniroute running, open http://localhost:20128 and go to the Providers section (I recommend setting the interface to English, otherwise you'll see many strings prefixed with __MISSING__; also use the search field, as the number of configuration groups in OmniRoute is huge). The catalog appears there with an indicator for free tiers. Connect several, as the system's value lies in redundancy: when one runs out of quota, the others remain available. Providers requiring no key (No Auth) are connected by default.

The catalog is classified by categories, and the category determines the connection procedure:

Category	How to connect
No Auth	They are active from the start. Although we will deactivate some as we see later.
Free Tier	Free tier that requires signing up with the provider and pasting an API key.
OAuth	Sign-in button for providers where you already have an account: OmniRoute opens the provider flow and saves the resulting token.
API Key	Paid providers (some with initial free credits); paste the key.
Local	Models running on your own machine (Ollama, LM Studio, vLLM…); specify the local URL.

The top filter allows you to narrow down to your interests, and the search bar accepts the provider's name or ID.

No Auth Providers¶

In general, the selection and configuration of providers is the most complicated, cumbersome, and time-consuming part of the entire process described in this article.

Not only that, but some of the providers activated by default, such as those in the "No Auth" category, can cause problems. During the first sessions of using OpenCode, I observed that most requests returned empty responses. After investigating, I found that the issue was caused by the intervention of the "Augment (Auggie CLI)" provider, which I therefore recommend deactivating.

Additionally, checking the logs in the OmniRoute console (Monitoring > Logs), I found that the providers "Chipotle Pepper AI (Free)" and "DuckDuckGo AI Chat" always failed, so although they don't introduce incorrect responses like "Augment (Auggie CLI)", they delay the provider cascade traversal, so I recommend deactivating them as well. We will deactivate the "Veo AI Free" provider, as it only offers video models that we won't use for coding.

Free API Key Providers¶

The procedure is always the same, only the site for obtaining the key changes:

Sign up with the provider and generate an API key in their panel (the link is usually in the provider's own card in OmniRoute).
In OmniRoute, go to Providers → search for the provider → click connect/configure.
Paste the key into the form and save.
Click the Test button on the provider card. If it responds correctly, its models join the gateway catalog and automatically enter the auto model pool.

The providers in this category are those that will allow us to take full advantage of OmniRoute. They are numerous, but as mentioned in the previous section, it requires quite a bit of work to configure them (obtaining API keys from different providers) and to stay up to date with which ones change in operation or are more or less recommended at a given time.

Some documents to follow to keep the list of free providers in good shape are the following:

Some of the providers in this type that I find recommendable at the time of writing this article are:

Gemini (Google AI Studio)
Groq
Mistral
Cloudflare Workers AI: After entering the API Key, the attempt to connect to the models will fail, indicating that an "Account ID" is also required. The "Account ID" is the hash that appears below the URL https://dash.cloudflare.com once the session is created and started. We will enter that hash in the "Account ID" field of the provider settings.
Pollinations AI: Although the connection box indicates that the API Key is optional, it is better to create one.

OAuth Providers¶

With these, there's no key to copy: click the connection button, sign in through the provider's browser flow, and OmniRoute will save encrypted credentials in its local database. This applies to existing tool accounts (Copilot, Cursor, Kilo Code, Qoder, etc.).

Review Terms of Service

Several of these providers are services designed for their own clients; some expressly prohibit use via proxies or third-party clients. The OmniRoute provider card includes a warning when this is the case. It's wise to read these notices before connecting an account you want to keep.

Curating the Pool for Agentic Use¶

There is one issue that isn't mentioned in the OmniRoute documentation and that, in my experience, has been essential to getting the setup up and running. The point is that not all vendors in the catalog are suitable for assigning to an agent.

The reason is that an agent like OpenCode doesn't just ask for text: every request carries the list of tools at its disposal (read files, run commands, search the repository…) and it expects the model to reply with calls to those tools. Providers that are the official API of a model return those calls to the client, which is the correct behaviour. But the catalog also includes two kinds of entries that behave differently:

Proxies of a web client (those you connect to with a chat session cookie rather than an API key). The service on the other end has its own tool engine and tries to execute the tools itself, in its own environment, instead of returning them.
Agent front-ends (services designed to be consumed from their own command line tool). They ship their own tool catalog and don't fit as the engine behind another agent.

The symptom is baffling, because the agent reports no error at all: it simply returns an empty response, or a text in which the model explains that it could not explore the repository and asks us, for example, to paste the contents of the files ourselves.

An Admission Test¶

The reliable way to decide whether a provider belongs in the pool is to ask the gateway: send a request with a tool and check whether the model invokes it. The response must contain a tool_calls block with the tool name and its arguments; if prose arrives instead, that provider is no good.

A single request against auto/coding is not enough to validate the pool. auto routing tends to stick to the last working provider and does not guarantee that all candidates receive traffic. Each provider must be tested separately.

The problematic behavior we want to detect (proxies that execute tools themselves, front-ends with their own tool catalog) is a property of the provider, not of the individual model: a proxy either passes tool_calls back to the client or it doesn't, regardless of which model sits behind it. That is why it is enough to test one representative model per provider, identified by the prefix before the slash (groq/, mistral/, cf/...), instead of the hundreds of models in the catalog. In reality we will test the first 5 models of each provider in case one fails for some specific reason. The jq filter excludes only the virtual auto/* models:

 1 2 3 4 5 6 7 8 910111213141516171819202122232425262728293031323334353637383940

API="http://localhost:20128/v1"KEY="sk-your-omniroute-key"# List of providers (excluding auto/*)providers=$(curl -s "$API/models" -H "Authorization: Bearer $KEY" \ | jq -r '[.data[].id | select(startswith("auto/") | not)] | group_by(split("/")[0]) | map(.[0]) | .[]' \ | cut -d/ -f1 | sort -u)for prov in $providers; do # Up to 5 models from this provider prov_models=$(curl -s "$API/models" -H "Authorization: Bearer $KEY" \ | jq -r --arg p "$prov" '[.data[].id | select(startswith($p+"/"))][:5][]') status="" tested="" for model in $prov_models; do tested="$model" resp=$(curl -s -i "$API/chat/completions" \ -H "Authorization: Bearer $KEY" \ -H "Content-Type: application/json" \ -d "{\"model\":\"$model\",\"stream\":false,\"messages\":[{\"role\":\"user\",\"content\":\"Read the file /etc/hostname\"}],\"tools\":[{\"type\":\"function\",\"function\":{\"name\":\"read\",\"description\":\"Reads a file\",\"parameters\":{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\"}},\"required\":[\"path\"]}}}]}") http_code=$(printf '%s' "$resp" | head -1 | grep -o '[0-9][0-9][0-9]') body=$(printf '%s' "$resp" | sed -n '/^\r\?$/,$p' | tail -n +2) if [ "$http_code" = "200" ]; then if printf '%s' "$body" | jq -e '.choices[0].message.tool_calls[0].function.name' >/dev/null 2>&1; then status="OK" else status="FAIL (no tool_calls)" fi break elif [ "$http_code" = "401" ] || [ "$http_code" = "403" ]; then status="FAIL (auth $http_code)" break else continue # 404, 400... model unavailable, try the next one fi done [ -z "$status" ] && status="FAIL (no valid models)" printf '%-24s %-45s %s\n' "$status" "$prov" "$tested"done

Requires jq. The script distinguishes three failure causes:

FAIL (no tool_calls): the provider returned a 200 but with prose instead of a tool call. This is the problem we are after: a proxy that runs the tools itself or a front-end with its own catalog. => Disconnect it.
FAIL (auth 401/403): the provider's key is expired, misconfigured, or out of quota. This is not a tools problem but a configuration one. => Fix the connection in Providers (or disconnect it if there's no remedy).
FAIL (no valid models): every model tested returned 404 or 400. The provider is down or its catalog has changed. => Review it in Providers.

In the output, the right-hand column shows the model that produced the result. This is a one-time setup step that you only need to repeat when adding a new provider.

Two Symptoms to Spot in the Logs¶

In Monitoring > Logs there are two patterns that give away a provider worth retiring:

200 with TO: 0 in a few milliseconds: the provider returned an empty response with a success status. A real inference never takes 15 ms.
Slow responses whose content is text where tool_calls should be, often carrying error messages from the remote service itself explaining that the tools don't exist.

Fallback doesn't trigger on failures disguised as success

It's worth understanding the limits of the system. OmniRoute's retry cascade works with explicit failures: a 429 for quota, a 502 or a timeout cause the request to be retried against the next provider, and this is perfectly visible in the log. But the two cases above reach the gateway as correct responses: a 200 with an empty body is, to a router, a valid response. No gateway can arbitrate that without semantically inspecting the content of every response.

Hence curating the pool is our responsibility, and it's a step that shouldn't be skipped. Put another way: automatic routing is only as good as the worst apparently healthy provider in the pool.

2. Create an OmniRoute API Key¶

In the panel, go to API Manager → Create API Key. Give it a descriptive name (e.g., opencode) and copy the generated key, which looks like sk-xxxxxxxx-xxxxxxxx.

This is a local key: it's used by your clients (OpenCode in this case) to authenticate against OmniRoute and has nothing to do with provider keys, which are held by OmniRoute.

You can verify the gateway is responding and see available models:

1	`curl http://localhost:20128/v1/models -H "Authorization: Bearer sk-your-omniroute-key"`

3. Declare OmniRoute as a Provider in OpenCode¶

OpenCode supports any OpenAI-compatible provider by declaring it in its config file. To apply configuration globally, write it to ~/.config/opencode/opencode.json:

 1 2 3 4 5 6 7 8 910111213141516171819202122

{ "$schema": "https://opencode.ai/config.json", "plugin": ["@dietrichgebert/ponytail"], "provider": { "omniroute": { "npm": "@ai-sdk/openai-compatible", "name": "OmniRoute", "options": { "baseURL": "http://localhost:20128/v1", "apiKey": "sk-your-omniroute-key" }, "models": { "auto": { "name": "Auto (balanced)" }, "auto/coding": { "name": "Auto (coding quality)" }, "auto/cheap": { "name": "Auto (cheapest)" }, "auto/fast": { "name": "Auto (fastest)" }, "auto/offline": { "name": "Auto (max quota)" } } } }, "model": "omniroute/auto/coding"}

Important points of this configuration:

npm: the @ai-sdk/openai-compatible adapter is used for /v1/chat/completions endpoints, which OmniRoute uses.
options.baseURL: the gateway endpoint. If OmniRoute is on another machine, use its IP or domain here.
options.apiKey: the API key created in OmniRoute.
models: no need to list specific provider models; simply declare the auto virtual models to enable smart routing and fallback. To fix a specific model, add it using the ID returned by /v1/models (see previous point).
model: default model at startup. auto/coding is a good choice for development; auto/offline is useful when quota headroom is the priority.
plugin: the list of OpenCode plugins, where Ponytail belongs.

Key Outside the Config File

If the config file will be versioned (e.g., in a dotfiles repo), it's better not to write the key in it. OpenCode allows storing credentials with /connect (choose Other, ID omniroute), in which case you can omit options.apiKey from the JSON.

You can also place an opencode.json file in a specific project's root, merging its settings with the global ones. This is practical for forcing a different model for a specific project.

4. Adjust Ponytail Level¶

Ponytail needs no config file: it works as soon as it's declared as a plugin. The only thing to decide is the intensity level, which can be changed on the fly from the TUI:

/ponytail → reports current level/ponytail lite → mild trimming/ponytail full → default level/ponytail ultra → aggressive trimming/ponytail off → disabled for this session

The default level is full. To set a different default for all new sessions, use the PONYTAIL_DEFAULT_MODE environment variable or the defaultMode field in ~/.config/ponytail/config.json:

1	`export PONYTAIL_DEFAULT_MODE="full"`

While active, the ruleset is also injected into subagents spawned by the main agent. To exclude some (e.g., read-only search agents), use a regex against the subagent type defined in the following environment variable:

1	`export PONYTAIL_SUBAGENT_MATCHER="build\|code"`

5. Verify Integration¶

Start the agent and verify the provider appears:

1	`opencode`

Within the TUI, the /models command should show OmniRoute entries.

From a directory containing a repository or project, run a quick test in CLI non-interactive mode:

1	`opencode run "Summarize this repo in three lines" --model omniroute/auto/coding`

While it runs, the OmniRoute panel (Monitoring > Logs) shows in real-time which provider handled the request, tokens consumed, and compression savings. If a provider fails, the log shows the automatic jump to the next.

To check if Ponytail is loaded, simply run /ponytail in the TUI (it returns the active level) or /ponytail-help (lists its commands).

Apparent Ponytail Startup ERROR

If OpenCode is started with --print-logs, this line may appear when loading the configuration:

1	`ERROR message="failed to load plugin" path=@dietrichgebert/ponytail error="path must be a string or a file descriptor"`

It's misleading: OpenCode tries to load the plugin by two paths and one of them fails, but the other loads it correctly. The test that Ponytail is operational is that /ponytail responds with the active level. Note that the level is persisted between sessions (in ~/.config/opencode/.ponytail-active): a /ponytail off from a previous test leaves the plugin loaded but disabled. When in doubt: /ponytail full and ask the agent what its system prompt says about PONYTAIL.

Environment Variables for Other Tools

Exporting these variables in your .bashrc or .zshrc makes any other OpenAI-convention-respecting tool use the gateway without further configuration:

12	`export OPENAI_BASE_URL="http://localhost:20128/v1"export OPENAI_API_KEY="sk-your-omniroute-key"`

Project Types and Operations¶

Once the environment is set up, the workflow is essentially the same regardless of language, project size, or task nature. What changes between cases is not the procedure, but the choice of model, trimming level, and context preparation. Thus, we first describe the common flow and then the adjustments per project type.

Common Operations¶

Navigate to the repository and start the agent:
12
cd my-projectopencode
Generate the context file the first time using the /init command in the TUI. OpenCode explores the repo and writes an AGENTS.md with the project description, build/test commands, and detected conventions. It's worth reviewing and manual completion; it's the most influential document for result quality and should be versioned with the project.
Plan before executing. For any non-trivial change, ask for a plan first rather than direct implementation. OpenCode has a planning mode that doesn't write to disk; reviewing a plan costs much less than reviewing a 400-line incorrect diff.
Iterate in small steps, validating with your project tools (compiler, linter, tests) after each step. The agent can execute these commands itself if documented in AGENTS.md.
Pass the Ponytail review before finalizing the task with /ponytail-review. It analyzes the current diff for over-engineering and returns a delete-list. This step quickly pays off in saved time.
Review the diff and commit using version control. Always work on a branch and make small commits: it's the natural safety net when an agent writes the code.
Clear context between tasks with /new. Dragging context from a finished task worsens results and spikes token consumption. The next section details session management.
Monitor the OmniRoute panel occasionally to see which providers are in use, which are exhausted, and if compression savings are as expected.

Session Management in OpenCode¶

When starting with OpenCode, it's surprising to find that sessions remain listed even after exiting the TUI with Ctrl-d or /exit. It's not a hang or incomplete closure: a session is not a process, it's a persisted conversation. Exiting the TUI ends the interface, but the conversation history (messages, tools, files, token usage) is stored in OpenCode's local database for later resumption. Since each opencode call without arguments starts a new session, you'll have dozens of entries in a few days.

In other words: "closing" doesn't mean "deleting." You must build the habit of reusing and pruning.

Resume Instead of Create¶

First, stop starting from scratch. Here are three ways to continue previous work:

opencode --continue # resumes the last session of the current project (-c)opencode --session <sessionID> # resumes a specific session (-s)opencode --session <sessionID> --fork # forks it into a copy, leaving the original intact

From within the TUI, the /sessions command (aliases: /resume, /continue; shortcut: Ctrl+x l) opens a selector to switch sessions without exiting.

The --fork option is particularly useful when a conversation reaches an interesting point and you want to test two different paths: it forks, and each branch goes its own way, much like a git branch.

Closing Tasks Properly¶

Two TUI commands mark the end of a task:

/new (alias: /clear, shortcut: Ctrl+x n): opens a new, clean session. Use this when switching tasks instead of continuing in the old conversation.
/compact (alias: /summarize, shortcut: Ctrl+x c): summarizes the current conversation to free up the context window without losing the thread. Use this if the same task is getting too "heavy" context-wise.

To keep a session's result, /export dumps the conversation to Markdown and opens your editor, while opencode export <sessionID> does the same in JSON from the CLI.

Inventory and Pruning¶

From outside the TUI, you manage the complete inventory:

opencode session list # list sessionsopencode session list -n 20 # limit number of entriesopencode session list --format json # script-processable outputopencode session delete <sessionID> # delete a session

To see cumulative cost, which in this setup determines how much free quota you're burning:

123	`opencode stats # token usage and costopencode stats --days 7 --models # last 7 days, per-model breakdownopencode stats --project # current project only`

Workflow¶

Putting it all together, the routine to keep the list under control is:

One session per task, not per day or project. The natural unit is whatever ends in a commit.
Resume with -c when returning to a partial task, instead of starting opencode fresh and re-explaining context (which costs tokens).
/new when switching tasks and /compact if the task grows but remains the same.
Export what's worth keeping before closing a session with valuable conclusions.
Periodic pruning (e.g., weekly), reviewing opencode session list and deleting anything already committed that adds no value with opencode session delete.
Review opencode stats during the same prune to get the consumption picture alongside the OmniRoute panel.

Sessions Are Per Project

OpenCode associates sessions with the working directory they were launched from; thus, --continue or -c resumes the last session of that project, not the last overall. This helps: always working from the repo root naturally keeps lists project-ordered.

Ponytail Commands¶

Beyond intensity levels, the skill provides a few commands fitting different workflow stages:

Command	Purpose
`/ponytail [lite \\| full \\| ultra \\| off]`	Adjusts intensity or disables it. Reports current level if no argument is provided.
`/ponytail-review`	Reviews the current diff for over-engineering and returns a delete-list.
`/ponytail-audit`	Same, but for the entire repo instead of just the diff.
`/ponytail-debt`	Harvests `ponytail:` shortcuts deferred into a ledger.
`/ponytail-gain`	Shows the measured impact scoreboard (less code/cost, more speed).
`/ponytail-help`	Quick reference for the above commands.

When the agent decides not to build something, it leaves a comment like ponytail: browser has one, explaining the ladder rung where it stopped. These comments are what /ponytail-debt harvests, so "defer for now" decisions are recorded rather than lost.

Adjustments by Project Type¶

The only significant variation between scenarios is model choice and context preparation:

New projects from scratch (greenfield). Little context to load and lots of code to generate. Ideal for free tiers: auto/cheap or auto/offline yield good results and input token consumption is low. Start by asking for project scaffolding and dependency files, then functionalities. Ponytail shines here, as agents have more freedom to invent extra structure.
Maintenance and evolution of existing code. Context is the bottleneck here; the agent needs to read significant code before touching anything. A detailed AGENTS.md, active OmniRoute context compression, and auto/coding for modifications are key. Fallback is most noticeable here due to long sessions. Ponytail's "Already in this codebase?" rung is especially valuable, preventing duplicate helpers.
Error debugging. The flow is the same but works much better if you provide a way to reproduce the failure (failing test, full trace, exact command). Explicit reasoning models yield better results; choose thinking variants in OmniRoute. A lite or off Ponytail level might be preferable here: debugging is about understanding, not trimming.
Scripting and automation. CLI non-interactive mode is useful here for integration into scripts, git hooks, or scheduled tasks:
12
opencode run "Update CHANGELOG with commits since the last tag" \ --model omniroute/auto/fast
Large, repetitive refactors. Break work into independent tasks and launch them separately instead of one massive change. This yields better results and avoids exhausting context windows or provider quotas in one go. If slimming down legacy code is the goal, /ponytail-audit on the whole repo and /ponytail ultra are the natural starting point.
Sensitive code projects. If code cannot be sent to third parties, the same setup works by connecting a local provider in OmniRoute (Ollama, LM Studio) instead of free services. Only the provider in the panel changes; OpenCode and the workflow remain the same.

Conclusion¶

The combination of OpenCode, OmniRoute, and Ponytail provides a complete agentic development environment with zero entry cost and no quota interruptions. Each piece attacks a different front: the agent provides capabilities, the gateway provides quota and provider independence, and the skill provides discipline for minimal code generation. All three are declared in a single 20-line config file.

The price is a slightly more laborious initial setup compared to closed products and the need to occasionally check active free providers. In return, you get what subscriptions don't offer: provider independence, full consumption visibility, and less code to regret.

G&W Zelda hack

Sun, 08 Mar 2026 15:45:00 +0100

Un conocido fabricante japonés de videojuegos empezó a comercializar a finales de 2022, un par de máquinas replicando el aspecto de algunas de las viejas G&W, sobre la base de un microcontrolador STM32H7 que ejecuta un firmware baremetal con emuladores de NES y GB, tres juegos clásicos y una aplicación reloj inspirados en la franquicia Zelda. La máquina resulta muy interesante por las virtudes de estar basada en un microcontrolador, en lugar de un microprocesador, es decir gran duración de la pequeña batería que contiene (la de un joycon de Switch), arranque y modo suspensión instantáneos. El soporte de datos es un pequeño chip flash NOR de 4MB (en el caso del modelo Zelda), suficiente para alojar los emuladores y juegos mencionados, pero muy escaso si se quiere sacar partido de la máquina y de su relativamente potente CPU.

El firmware original sirve para comprobar la solvencia de la plataforma para emular al menos las máquinas de 8 bit que funcionan originalmente, por lo que en seguida el dispositivo resultó atractivo para la comunidad hacker. Al poco tiempo de empezar a comercializarse ya aparecieron procedimientos para desbloquear y modificar la máquina de manera que se pudieran instalar más emuladores y juegos.

La primera modificación importante propuesta por la comunidad consistía en sustituir el chip flash por otro de 64MB para disponer de más espacio para juegos y emuladores. Tiempo después la modificación evolucionó para incluir un slot de tarjetas microSD donde almacenar los juegos y savestates, así como para simplificar enormemente el proceso de actualización, convirtiendo a la máquina así modificada en una máquina de emulación portátil inigualable en aspectos como portabilidad, tamaño, duración de la batería y tiempos de arranque.

Con cualquiera de las dos modificaciones se consigue emular las siguientes máquinas:

Amstrad CPC6128 (beta)
Atari 2600
Atari 7800
ColecoVision
Gameboy / Gameboy Color
Game & Watch / LCD Games
MSX1/2/2+
Nintendo Entertainment System
PC Engine / TurboGrafx-16
Pokémon Mini
Sega Game Gear
Sega Genesis / Megadrive
Sega Master System
Sega SG-1000
Tamagotchi P1
Watara Supervision

En este artículo vamos a describir los pasos para realizar las dos modificaciones. La modificación para añadir el slot microSD requiere también la sustitución de la flash, ya que cada vez que carguemos un juego nuevo de la microSD se grabará en el chip flash, y el original de 4MB soporta pocos ciclos de escritura dado que no estaba previsto que se utilizara de esta forma.

Todo el proceso ha sido realizado sobre un sistema Linux. En principio el desarrollo sobre sistemas Windows y MacOS X también es posible, pero los pasos para instalar los requerimientos y el software que utilizaremos necesariamente cambiarán.

Conexión al puerto SWD¶

El desbloqueo del procesador y la modificación del firmware se hacen a través del puerto SWD que habitualmente tienen los microcontroladores STM32 para programar su memoria flash interna y depurar los desarrollos. Este puerto SWD se encuentra en la PCB sin poblar, es decir sin pines o conectores soldados.

Para hacer la conexión con dicho puerto hay varias opciones:

Soldar cables directamente.
Introducir cables limpios o cables de pin macho, inclinándolos para forzar el contacto.
Utilizar pinzas sonda de conexión especializadas.
Utilizar pinzas pogo pin (Single row 5pin).
Rutear los pines SWDIO y SWCLK hacia el puerto USB-C.

Versión difícil¶

Como empecé a cacharrear con la máquina antes de que apareciera el mod de microSD, en su momento realicé el ruteado del puerto SWD al USB-C. Si se va a terminar realizando el mod de microSD no merece la pena el esfuerzo, dado que a partir de entonces el flasheo del firmware se realizará desde la propia microSD. De todas formas, a propósitos de documentación vamos a describir cómo se haría el ruteado.

El puerto USB-C sólo tiene conectados los pines de alimentación ya que está previsto únicamente para cargar la máquina. Por tanto se pueden utilizar los pines D+ y D- que están libres para cablearlos a los pines SWDIO y SWCLK que son los únicos imprescindibles del puerto SWD. Necesitaremos también conectar a 5V y GND, pero estos ya se encuentran cableados en el puerto USB-C. El ruteado se hace con un fino cable barnizado (enamel) de los que se utilizan para construir bobinas. La soldadura a los dos pines centrales del puerto USB-C que son los que corresponden a D+ y D- es complicada al tener un paso muy pequeño, pero con paciencia y flux puede lograrse.

Una vez resuelto la única parte difícil del procedimiento, es decir soldar los cables al puerto USB, estos se van sujetando cada cierta distancia con cinta Kapton y dirigiendo hacia la zona de la batería por donde se aprovecha el rebaje a ambos lados que hay del alojamiento que la rodea para pasar uno de los cables. El otro se conduce por el espacio que hay entre alojamiento de la batería y la PCB. De esta forma se consigue que ambos cables no puedan tocarse, aunque en teoría al estar barnizados no debería haber problema, se adopta este camino separado como precaución adicional.

Una vez que los cables alcanzan las proximidades del puerto SWD, se utilizan los dos test pads que pueden verse en la foto para realizar las soldaduras.

La correspondencia entre D+ y D- en el puerto USB-C con los SWDIO y SWCLK del puerto SWD, puede hacerse de cualquier forma siempre que tengamos claro donde está cada cual para más tarde hacer el adaptador USB-SWD que necesitaremos. En este montaje se ha optado por la siguiente correspondencia.

D+ ↔ SWDIO
D- ↔ SWCLK

Warning

La idea en un principio era adoptar la correspondencia utilizada en esta otra guía, pero por un error cometido al principio, se terminó haciendo justo al revés. Como se comentaba antes, en realidad no es problema siempre que se tenga claro cómo están hechas las conexiones. Este aviso es sólo por si alguien intenta seguir ambas guías de forma simultánea, para que se tenga en cuenta dicha diferencia.

Una vez hecho el ruteado del puerto, necesitaremos construir el adaptador para poder extraer las señales SWDIO y SWCLK del puerto USB-C. Para ello se corta un cable USB-A convencional para tener acceso a los cuatro cables que contiene por separado y se sueldan a ellos conectores hembra de pin. El adaptador se completa con un adaptador USB-A a USB-C que se marca para orientarlo correctamente cuando lo vayamos a utilizar, ya que sólo hemos ruteado los pines D+ y D- de uno de los dos lados (el puerto USB-C es reversible).

Los colores de los cables suelen estar estandarizados de la siguiente forma:

Rojo: 5V
Negro: GND
Verde: D+
Blanco: D-

Versión fácil¶

La manera recomendada para hacer la conexión al puerto SWD (si no se quiere soldar, que es la opción más fiable) es mediante pinzas sonda de conexión especializadas. Para aplicar dichas pinzas, es recomendable desconectar previamente la batería de la consola. El conector de la batería salta fácilmente al introducir una pieza fina de plástico por debajo del mismo.

Sonda de programación¶

Ya tenemos resuelto dónde conectar en la consola. Ahora necesitamos un dispositivo capaz de comunicarse con ese puerto SWD del microcontrolador. Las opciones son:

Me decanté por usar una Raspberry Pi Pico. Para que funcione como sonda de programación SWD hay que cargarle el firmware debugprobe. En mi caso utilicé el fichero picoprobe.uf2 de esta release en concreto. Para flashear la Pico sólo hay que conectarla al ordenador por USB mientras pulsamos el botón BOOTSEL para forzar el modo en el que se monta como una unidad de almacenamiento y arrastrar el fichero .uf2 a esa unidad. Tras autoflashearse, la Pico se reiniciará automáticamente y empezará a funcionar como sonda de programación SWD.

Una vez programada la Pico, solo queda hacer las conexiones de los cables que habíamos conectado al puerto SWD de la Game&Watch. Podemos utilizar el mismo tipo de pinzas que aplicamos a la consola, aunque en mi caso utilicé otras similares pero un poco más robustas, ya que el espaciado de los pines GPIO de la Pico es mucho mayor.

El conexionado entre Game&Watch y Raspberry Pi Pico es:

Pico	GnW	Color
3	3	Negro
4	5	Blanco
5	2	Verde

Desbloqueo del microcontrolador¶

Una vez resuelta la conectividad a la placa, el primer paso en la modificación es el desbloqueo del microcontrolador STM32H7 para que podamos sustituir el firmware que hay en su memoria flash interna así como poder escribir en la memoria flash externa (con código que inyectaremos en el propio microcontrolador).

Esta tarea se efectúa con el conjunto de utilidades gnwmanager. Este paquete se encuentra registrado en PyPI por lo que se puede instalar muy fácilmente con pip (preferiblemente dentro de un entorno virtual Python).

12	`$ pip install gnwmanager$ gnwmanager install openocd`

Ahora, tras volver a conectar la batería de la consola si la habíamos desconectado, ejecutaremos el siguiente comando:

1	`(gnwmanager) $ gnwmanager unlock`

El proceso se interrumpirá en un par de ocasiones dando instrucciones por la terminal que deberemos seguir. Una salida típica sería:

 1 2 3 4 5 6 7 8 910111213141516171819202122

(gnwmanager) [edu@thinkpad ~]$ gnwmanager unlockIf interrupted, resume unlocking with: gnwmanager unlock --backup-dir=backups-2025-10-27-19-28-14Detected ZELDA game and watch.Backing up itcm to "backups-2025-10-27-19-28-14/itcm_backup_zelda.bin"... complete!Backing up external flash to "backups-2025-10-27-19-28-14/flash_backup_zelda.bin"... complete!Flashing payload to external flash... complete!Payload successfully flashed. Perform the following steps:1. Fully remove power, then re-apply power.2. Press the power button to turn on the device; the screen should turn blue.Press the "enter" key when the screen is blue: Backing up internal flash to "backups-2025-10-27-19-28-14/internal_flash_backup_zelda.bin"... complete!Unlocking device... complete!Restoring firmware... complete!Unlocking complete!Pressing the power button should launch the original firmware.

Aparecerán los ficheros internal_flash_backup_zelda.bin, flash_backup_zelda.bin y itcm_backup_zelda.bin en un directorio backups-FECHA-HORA que conviene guardar.

Si encendemos en este momento la consola, no notaremos ningún cambio, es decir ejecutará el firmware original, pero ahora el chip estará desprotegido y podremos flashearle otro firmware.

Modificación 1: retro-go¶

Sustitución de la flash¶

En este momento toca empezar a modificar la consola seriamente. Como se comentaba al principio, el chip de almacenamiento externo del microcontrolador es una memoria flash de solo 4MB (modelo Zelda). No solo es pequeño para poder cargar muchos juegos, sino que tiene pocos ciclos de escritura, por lo que sustituir los juegos frecuentemente, o cachearlos cuando se hace la modificación para añadir la microSD, puede desgastarlo rápidamente. La modificación habitual es desoldar el chip flash de 4MB original y sustituirlo por otro de 64MB, concretamente el modelo MX25U51245GZ4I00.

Para retirar el chip flash original, es muy recomendable extraer la placa de la consola, desconectando las dos fajas de datos de la pantalla, desoldando el altavoz y retirando todos los tornillos. Una vez que tengamos la placa sobre la mesa de trabajo, protegemos con cinta kapton los alrededores del chip y lo extraemos aplicando flux y aire caliente con una pistola.

A continuación limpiamos con malla desoldadora la huella del chip que acabamos de retirar. También, aunque hay que hacerlo con sumo cuidado, ayuda rascar (con la punta de las pinzas por ejemplo) la máscara de soldadura de la PCB para ampliar hacia el exterior la superficie soldable de la huella de soldadura del chip.

El nuevo chip flash tiene formato QFN-8 de soldadura superficial que no resulta sencillo de soldar. Es recomendable aplicar flux y preestañar los pads de dicho chip por la parte inferior. También recomiendo poner una tira de cinta kapton en la parte inferior de manera que este no quede directamente apoyado sobre la PCB, lo que dificultaría el flujo de estaño por los pads.

Hay que fijarse bien en el punto que lleva el chip en su encapsulado que marca el pin número 1 que se corresponde con el que tiene un triángulo indicador en la PCB como se puede ver en la segunda foto de las siguientes.

Flasheo retro-go¶

Una vez instalado el chip, es hora de flashear el firmware. Para esta modificación, me decanto por no hacer dual boot, es decir no instalar el firmware original parcheado junto a retro-go, para así tener todo el espacio de la memoria flash dedicado a los juegos. Para ello empezamos bajando el repositorio del mismo:

123	`cd ~/gitgit clone --recursive https://github.com/sylverb/game-and-watch-retro-go -b filesystem_wipcd game-and-watch-retro-go`

Una vez bajado el código, toca instalar las ROMs en los directorios correspondientes a las distintas máquinas soportadas que encontraremos en ~/git/game-and-watch-retro-go/roms/. Por ejemplo, para instalar las ROMs de NES, copiamos las ROMs a ~/git/game-and-watch-retro-go/roms/nes/. Si queremos portadillas para los juegos, situaremos en los mismos directorios y con los mismos nombres de fichero de las ROMs correspondientes, las imágenes en formato jpg o png. Por ejemplo, para la ROM zelda.nes, situaremos la portada en ~/git/game-and-watch-retro-go/roms/nes/zelda.jpg.

Tenemos que tener en cuenta que todas las ROMs y sus portadillas tienen que caber en el chip flash de 64 MB que hemos instalado a la consola. La mayoría de las ROMs se comprimen, por lo que como regla de partida, utilizaremos el criterio de elegir ROMs por un tamaño total de aproximadamente el doble (128MB).

Ahora toca compilar el firmware (si no vamos a utilizar portadillas para aprovechar el espacio de sus ficheros para poder poner más ROMs, no incluir las variables de entorno COVERFLOW y JPG_QUALITY en los comandos de compilación y flasheo):

12345678

make docker_buildmake docker(docker) gnwmanager install openocd(docker) export GNW_TARGET=zelda(docker) export ADAPTER=cmsis-dap(docker) make clean(docker) COVERFLOW=1 JPG_QUALITY=90 EXTFLASH_SIZE_MB=64 make -j$(nproc)

Al terminar la compilación se nos informará del tamaño resultante del binario que se flasheará en el chip. Por ejemplo:

1234	`External flash usage Capacity: 61050880 Bytes ( 58.223 MB) Usage: 54335345 Bytes ( 51.818 MB) Free: 6715535 Bytes ( 6.404 MB)`

Con esa información a la vista podremos iterar el proceso añadiendo o retirando ROMs hasta obtener un binario de unos 55MB, ya que hay que prever algo para los savestates de los juegos.

Una vez que estemos satisfechos con la ocupación del espacio, flashearemos el firmware volviendo a conectar la sonda de programación que comentamos en el apartado Sonda de programación.

1	`(docker) COVERFLOW=1 JPG_QUALITY=90 EXTFLASH_SIZE_MB=64 make flash`

Una salida típica sería:

 1 2 3 4 5 6 7 8 91011121314

docker@53335bdd9199:/opt/workdir$ COVERFLOW=1 JPG_QUALITY=90 EXTFLASH_SIZE_MB=64 make flash_gnwmanagerEntering 'LCD-Game-Emulator'Entering 'blueMSX-go'Entering 'caprice32-go'Entering 'fceumm-go'Entering 'gwenesis'Entering 'potator'Entering 'prosystem-go'Entering 'retro-go-stm32'Entering 'smw'Entering 'tamalib'Entering 'zelda3'[ BASH ] Checking for updated roms100%|█████████████████████████████████████████████████████████████████| 208/208 [04:20<00:00, 1.25s/it]

Es importante que guardemos el fichero build/gw_retro_go.elf porque lo necesitaremos para extraer los savestates en el futuro.

Respaldar savestates retro-go¶

Si más adelante queremos extraer los savestates de los juegos, para poder volverlos a instalar tras flashear un nuevo firmware, en primer lugar necesitaremos depositar en el directorio build el fichero gw_retro_go.elf que obtuvimos en el paso anterior. Después podremos arrancar de nuevo el entorno docker y ejecutar el script de backup:

cd ~/git/game-and-watch-retro-gomake docker(docker) export GNW_TARGET=zelda(docker) export ADAPTER=cmsis-dap(docker) ./scripts/saves_backup.sh build/gw_retro_go.elf

Los savestates aparecerán en el subdirectorio ~/git/game-and-watch-retro-go/save_states. Una vez que hayamos compilado y flasheado un nuevo firmware, podremos restaurarlos ejecutando el script de restauración:

1	`(docker) ./scripts/saves_restore.sh`

La restauración se hace de forma inteligente, es decir, si tenemos savestates de un juego que no está en el nuevo firmware, dicho savestate no se instalará en la consola, para evitar desperdiciar espacio de la memoria flash.

Modificación 2: retro-go-sd¶

Instalación módulo slot microSD¶

Al igual que con la modificación para el retro-go normal, para utilizar retro-go-sd hay que empezar haciendo una modificación hardware a la consola. Esta vez es más complicada, sobre todo la fase final de soldadura del módulo directamente sobre las patitas del microcontrolador, que tienen un paso muy pequeño.

El módulo se compone del propio lector de tarjetas microSD y 4 componentes. Todo ello soldado sobre una PCB tipo flex. La lista de componentes completa es:

1 lector de tarjetas microSD
1 resistencia 100kΩ 0603 o 0805
2 condensadores de 1μF 0603 o 0805
1 regulador de tensión RT9193-28GB. Hay personas que han reportado problemas con este modelo comprado en Aliexpress y recomiendan como reemplazo el "MIC5504-2.8YM5-TR".
1 PCB flex: Aquí se utiliza la versión de PrimoAngelo. La original que suele referenciarse en la mayoría de las guías es la de Tim Schuerewegen / hundshamer.

Empezaremos soldando los componentes sobre el PCB flex.

Lo siguiente como decíamos al principio será el difícil paso de instalar el módulo en la consola. Retiramos los cuatro tornillos que caen en su superficie y lo presentamos de forma que consigamos que los pads de la flex se encuentren alineados con las patitas del microcontrolador a la vez que estos quedan a sus pies, es decir de esta forma.

Una vez que se encuentre alineado a nuestro gusto, procederemos a fijarlo en su posición atornillando los cuatro tornillos. Ahora será cuando tendremos que armarnos de paciencia y flux de buena calidad para lograr hacer las soldaduras de los pads del flex y evitar a la vez los puentes entre las mismas. Será necesario comprobar continuidad de las soldaduras así como la no existencia de puentes entre las patitas adyacentes. Si finalmente lo conseguimos, solo resta añadir un punto de soldadura entre el pad marcado con +4V y el terminal del condensador que queda a su lado.

Flasheo bootloader¶

Lo siguiente será flashear el bootloader junto al firmware original parcheado de la consola para permitir el dual boot (esta vez sí merece la pena al contar con espacio prácticamente ilimitado para ROMs en la microSD). Desde el directorio donde estén los ficheros de backup de la consola y con un entorno Python que tenga instalado gnwmanager, ejecutaremos el siguiente comando:

1	`(gnwmanager) $ gnwmanager flash-patch zelda internal_flash_backup_zelda.bin flash_backup_zelda.bin --bootloader`

Una salida típica sería:

(gnwmanager) $ gnwmanager flash-patch zelda internal_flash_backup_zelda.bin flash_backup_zelda.bin --bootloader100%|███████████████████████████████████████████████████████████████████| 16/16 [00:58<00:00, 3.66s/it]

Si encendemos en ese momento la consola, tras haber retirado la sonda de programación, veremos que arranca el firmware original (parcheado). Tras pulsar GAME + LEFT se ejecutará el bootloader y, como en ese momento Retro-Go SD todavía no estará instalado en la flash interna del STM32, se nos muestrará el siguiente aviso:

Instalación de Retro-Go SD¶

Solo nos restará instalar el firmware de Retro-Go SD. Para ello, copiaremos el fichero retro-go_update.bin que descargaremos de la última release publicada por Sylverb en el repositorio de Retro-Go SD al directorio raíz de la microSD. Al arrancar por primera vez, veremos en pantalla cómo se copian los ficheros de retro-go y los cores de los emuladores a la misma microSD.

A la vez se creará en la microSD la estructura de directorios siguiente:

 1 2 3 4 5 6 7 8 9101112131415161718192021222324252627

retro-go/├── CONFIG├── bios/│ ├── coleco/│ ├── msx/│ ├── nes/├── cores/│ ├── mappers/│ ├── a2600.bin│ ├── a2600_defprops.bin│ ├── a7800.bin│ └── ...├── data/│ ├── a2600/│ ├── a7800/│ ├── amstrad/│ └── ...├── fonts/│ ├── cp1251_greybeard.bin│ ├── cp1251_sans_serif.bin│ ├── cp1251_sans_serif_bold.bin│ └── ...└── roms/ ├── a2600/ ├── a7800/ ├── amstrad/ └── ...

Sólo restará copiar las ROMs que queramos emular en los directorios correspondientes. Si queremos portadillas para los juegos, tendremos que crear el subdirectorio covers con los mismos subdirectorios del directorio roms y colocar allí las imágenes. Estas tienen que estar en un formato especial IMG que generaremos con un script que se incluye en el repositorio de Retro-Go SD. Los nombres de los archivos IMG tendrán que coincidir con los de las ROMs en su correspondiente directorio.

Carcasa trasera¶

Al colocar el slot microSD hay que modificar la tapa trasera de la consola puesto que el lector cae sobre unos postes de apoyo de la cruceta. También hay que perforar el lateral para dejar paso a la microSD para poder extraerla e insertarla cuando queramos cambiar los juegos, rescatar savestates o actualizar el firmware. Para realizar la perforación existen unos utillajes diseñados por el usuario facelesstech que ayudan mucho a que la ranura quede limpia. En el vídeo que hay al final de este artículo, puede verse cómo se realiza esta modificación.

Existe una alternativa si no queremos arriesgarnos a estropear definitivamente la tapa original, y es imprimir en 3D el modelo creado por el usuario Aradia y que puede descargarse de aquí.

El color verde que he encontrado más parecido al de la consola Zelda es el 15-Verde de OVERTURE.

Controles¶

Indicamos a continuación las combinaciones de teclas de manejo de Retro-go SD (aunque muchas de ellas funcionan también en Retro-go). Manteniendo pulsado el botón PAUSE/SET mientras se presionan otros botones se realizan las siguientes acciones:

Combinación de teclas	Acción
`PAUSE/SET` + `GAME`	Guardar una captura de pantalla (deshabilitado por defecto en builds con flash de 1MB)
`PAUSE/SET` + `TIME`	Cambiar velocidad de ejecución (1x/1.5x)
`PAUSE/SET` + `UP`	Aumentar brillo
`PAUSE/SET` + `DOWN`	Disminuir brillo
`PAUSE/SET` + `RIGHT`	Aumentar volumen
`PAUSE/SET` + `LEFT`	Disminuir volumen
`PAUSE/SET` + `B`	Cargar state
`PAUSE/SET` + `A`	Guardar state
`PAUSE/SET` + `A`	Autodisparo en botón A
`PAUSE/SET` + `B`	Autodisparo en botón B
`PAUSE/SET` + `POWER`	Apagar sin guardar savestate
`PAUSE/SET` + `POWER`	Después de haber hecho `PAUSE/SET` y seleccionar `Power off`, arrancará el bootloader sin llegar a llamar a Retro-go, lo que nos permitirá ver la versión del bootloader así como información sobre la detección de la microSD y el estado de las memorias flash interna y externa
`PAUSE/SET` + `GAME` + `LEFT`	Desde el OFW, hace que arranque el bootloader sin terminar de cargar retro-go. Sirve para ver la pantalla que muestra la detección de SD, chip flash y código en bank2 de flash interna; también para ver la versión del bootloader.
`GAME` + menú `Reset settings`	Borra los datos de registro en la SD de lo que hay cacheado en la flash; utilizar cuando se cambie la SD de máquina o se cambie el chip flash. Es equivalente a borrar el fichero `flashcachedata.bin` en el directorio `data` de la SD.

Referencias¶

No quiero terminar sin hacer mención al servidor de Discord de stacksmashing y a los siguientes usuarios cuyo trabajo ha hecho posible estas modificaciones:

stacksmashing
kbeckmann
Tim Schuerewegen
BrianPugh
GMMan
tfmoe__
Sylver Bruneau
facelesstech
DasBoss
bxhxx
Benjamin Solberg
orzeus
ducalex
ZimM
Ninoh-FOX
PrimoAngelo
Aradia

En el siguiente video de Macho Nacho se puede ver el todo el proceso de modificación de la consola (el flex del módulo microSD es el modelo que no se sujeta con los tornillos sino con puntos de soldadura sobre la PCB de la G&W):

G&W Zelda hack

Sun, 08 Mar 2026 15:45:00 +0100

A well-known Japanese video game manufacturer began selling a pair of machines at the end of 2022, replicating the appearance of some of the old G&W, based on an STM32H7 microcontroller running a baremetal firmware with NES and GB emulators, three classic games and a clock application inspired by the Zelda franchise. The machine is very interesting because of the virtues of being based on a microcontroller instead of a microprocessor, that is, great battery life (the one from a Switch joycon), instant boot and sleep mode. The storage medium is a small 4MB NOR flash chip (in the case of the Zelda model), enough to host the mentioned emulators and games, but very scarce if you want to take advantage of the machine and its relatively powerful CPU.

The original firmware serves to verify the solvency of the platform to emulate at least the 8-bit machines that originally run, so the device immediately became attractive to the hacker community. Shortly after it went on sale, procedures appeared to unlock and modify the machine so that more emulators and games could be installed.

The first major modification proposed by the community consisted of replacing the flash chip with a 64MB one to have more space for games and emulators. Later, the modification evolved to include a microSD card slot to store games and savestates, as well as to greatly simplify the update process, turning the modified machine into an unparalleled portable emulation machine in aspects such as portability, size, battery life, and boot times.

With either of the two modifications, it is possible to emulate the following machines:

Amstrad CPC6128 (beta)
Atari 2600
Atari 7800
ColecoVision
Gameboy / Gameboy Color
Game & Watch / LCD Games
MSX1/2/2+
Nintendo Entertainment System
PC Engine / TurboGrafx-16
Pokémon Mini
Sega Game Gear
Sega Genesis / Megadrive
Sega Master System
Sega SG-1000
Tamagotchi P1
Watara Supervision

In this article we will describe the steps to perform these two modifications. The modification to add the microSD slot also requires replacing the flash, since every time we load a new game from the microSD it will be written to the flash chip, and the original 4MB one supports few write cycles since it was not intended to be used this way.

The entire process has been performed on a Linux system. In principle, development on Windows and MacOS X systems is also possible, but the steps to install the requirements and the software we will use will necessarily change.

Connection to the SWD port¶

Unlocking the processor and modifying the firmware are done through the SWD port that STM32 microcontrollers usually have to program their internal flash memory and debug developments. This SWD port is located on the PCB unpopulated, that is, without soldered pins or connectors.

To make the connection to this port there are several options:

Solder wires directly.
Insert bare wires or male pin wires, tilting them to force contact.
Use specialized connection probe clips.
Use pogo pin clips (Single row 5pin).
Route the SWDIO and SWCLK pins to the USB-C port.

Hard version¶

Since I started tinkering with the machine before the microSD mod appeared, at the time I routed the SWD port to the USB-C. If you end up doing the microSD mod, the effort is not very worthwhile, since from then on flashing the firmware will be done from the microSD itself. However, for documentation purposes we will describe how the routing would be done.

The USB-C port only has the power pins connected since it is only intended to charge the machine. Therefore, the D+ and D- pins that are free can be used to wire them to the SWDIO and SWCLK pins, which are the only essential ones for the SWD port. We will also need to connect to 5V and GND, but these are already wired in the USB-C port. The routing is done with fine enameled wire like the one used to build coils. Soldering to the two central pins of the USB-C port which correspond to D+ and D- is complicated having a very small pitch, but with patience and flux it can be achieved.

Once the only difficult part of the procedure is solved, that is, soldering the wires to the USB port, these are secured every so often with Kapton tape and directed towards the battery area where the recess on both sides of the housing that surrounds it is used to pass one of the cables. The other is routed through the space between the battery housing and the PCB. This way both cables cannot touch each other, although in theory being varnished there should be no problem, this separate path is adopted as an additional precaution.

Once the wires reach the vicinity of the SWD port, the two test pads that can be seen in the photo are used to solder them.

The correspondence between D+ and D- on the USB-C port with SWDIO and SWCLK of the SWD port can be done in any way as long as we are clear on where each one is to later make the USB-SWD adapter we will need. In this assembly the following correspondence has been chosen:

D+ ↔ SWDIO
D- ↔ SWCLK

Warning

The idea at first was to adopt the correspondence used in this other guide, but due to a mistake made at the beginning, it ended up being done exactly the other way around. As mentioned earlier, it's really not a problem as long as you know how the connections are made. This warning is only in case someone tries to follow both guides simultaneously, so that this difference is taken into account.

Once the port is routed, we will need to build the adapter to extract the SWDIO and SWCLK signals from the USB-C port. To do this, cut a conventional USB-A cable to have access to the four separate cables it contains and solder female pin connectors to them. The adapter is completed with a USB-A to USB-C adapter that is marked to orient it correctly when we are going to use it, since we have only routed the D+ and D- pins on one of the two sides (the USB-C port is reversible).

The cable colors are usually standardized as follows:

Red: 5V
Black: GND
Green: D+
White: D-

Easy version¶

The recommended way to make the connection to the SWD port (if you don't want to solder, which is the most reliable option) is using specialized connection probe clips. To apply these clips, it is recommended to previously disconnect the console's battery. The battery connector pops off easily by inserting a thin piece of plastic underneath it.

Programming probe¶

We have solved where to connect on the console. Now we need a device capable of communicating with that SWD port of the microcontroller. The options are:

I chose to use a Raspberry Pi Pico. For it to work as an SWD programming probe, the debugprobe firmware must be loaded. In my case I used the picoprobe.uf2 file from this specific release. To flash the Pico, just connect it to the computer via USB while pressing the BOOTSEL button to force the mode in which it mounts as a storage drive and drag the .uf2 file to that drive. After autoflashing, the Pico will automatically restart and begin to function as an SWD programming probe.

Once the Pico is programmed, the only thing left is to make the connections of the cables that we had connected to the SWD port of the Game&Watch. We can use the same type of clips that we applied to the console, although in my case I used similar ones but slightly more robust, since the spacing of the GPIO pins of the Pico is much larger.

The wiring between Game&Watch and Raspberry Pi Pico is:

Pico	GnW	Color
3	3	Black
4	5	White
5	2	Green

Microcontroller unlocking¶

Once the connectivity to the board is solved, the first step in the modification is unlocking the STM32H7 microcontroller so that we can replace the firmware in its internal flash memory as well as write to the external flash memory (with code that we will inject into the microcontroller itself).

This task is performed with the gnwmanager utility suite. This package is registered on PyPI so it can be installed very easily with pip (preferably inside a Python virtual environment).

12	`$ pip install gnwmanager$ gnwmanager install openocd`

Now, after reconnecting the console's battery if we had disconnected it, we will execute the following command:

1	`(gnwmanager) $ gnwmanager unlock`

The process will pause on a couple of occasions giving instructions through the terminal that we must follow. A typical output would be:

 1 2 3 4 5 6 7 8 910111213141516171819202122

(gnwmanager) [edu@thinkpad ~]$ gnwmanager unlockIf interrupted, resume unlocking with: gnwmanager unlock --backup-dir=backups-2025-10-27-19-28-14Detected ZELDA game and watch.Backing up itcm to "backups-2025-10-27-19-28-14/itcm_backup_zelda.bin"... complete!Backing up external flash to "backups-2025-10-27-19-28-14/flash_backup_zelda.bin"... complete!Flashing payload to external flash... complete!Payload successfully flashed. Perform the following steps:1. Fully remove power, then re-apply power.2. Press the power button to turn on the device; the screen should turn blue.Press the "enter" key when the screen is blue: Backing up internal flash to "backups-2025-10-27-19-28-14/internal_flash_backup_zelda.bin"... complete!Unlocking device... complete!Restoring firmware... complete!Unlocking complete!Pressing the power button should launch the original firmware.

The files internal_flash_backup_zelda.bin, flash_backup_zelda.bin and itcm_backup_zelda.bin will appear in a backups-DATE-TIME directory that should be saved.

If we turn on the console at this point, we won't notice any change, meaning it will run the original firmware, but now the chip will be unprotected and we can flash another firmware to it.

Modification 1: retro-go¶

Flash replacement¶

At this time we start modifying the console seriously. As mentioned at the beginning, the microcontroller's external storage chip is a flash memory of only 4MB (Zelda model). Not only is it small for loading many games, but it has few write cycles, so replacing games frequently, or caching them when making the modification to add the microSD, can wear it out quickly. The usual modification is to desolder the original 4MB flash chip and replace it with a 64MB one, specifically the MX25U51245GZ4I00 model.

To remove the original flash chip, it is highly recommended to extract the console's motherboard, disconnecting the two data ribbon cables from the screen, desoldering the speaker, and removing all screws. Once we have the board on the workbench, we protect the surroundings of the chip with kapton tape and extract it by applying flux and hot air with a heat gun.

Next, we clean the footprint of the chip we just removed with desoldering braid. Also, although it must be done with great care, it helps to scratch (with the tip of tweezers, for example) the solder mask of the PCB to expand outwards the solderable surface of the chip's solder footprint.

The new flash chip has a surface mount QFN-8 format that is not easy to solder. It is recommended to apply flux and pre-tin the pads of said chip on the bottom. I also recommend putting a strip of kapton tape on the bottom so that it does not rest directly on the PCB, which would hinder the flow of solder through the pads.

You must pay close attention to the dot on the chip's package that marks pin number 1, which corresponds to the one with an indicator triangle on the PCB as can be seen in the second photo of the following.

Flashing retro-go¶

Once the chip is installed, it's time to flash the firmware. For this modification, I choose not to set up dual boot, that is, not to install the patched original firmware alongside retro-go, to have all the flash memory space dedicated to games. To do this we start by downloading its repository:

123	`cd ~/gitgit clone --recursive https://github.com/sylverb/game-and-watch-retro-go -b filesystem_wipcd game-and-watch-retro-go`

Once the code is downloaded, it's time to install the ROMs in the directories corresponding to the different supported machines that we will find in ~/git/game-and-watch-retro-go/roms/. For example, to install the NES ROMs, we copy the ROMs to ~/git/game-and-watch-retro-go/roms/nes/. If we want cover art for the games, we will place the images in jpg or png format in the same directories and with the same file names of the corresponding ROMs. For example, for the zelda.nes ROM, we will place the cover at ~/git/game-and-watch-retro-go/roms/nes/zelda.jpg.

We have to keep in mind that all ROMs and their covers must fit in the 64 MB flash chip we installed in the console. Most ROMs compress, so as a starting rule, we will use the criteria of choosing ROMs for a total size of roughly double (128MB).

Now it's time to build the firmware (if we are not going to use covers to take advantage of the space of their files to be able to put more ROMs, do not include the COVERFLOW and JPG_QUALITY environment variables in the build and flash commands):

12345678

make docker_buildmake docker(docker) gnwmanager install openocd(docker) export GNW_TARGET=zelda(docker) export ADAPTER=cmsis-dap(docker) make clean(docker) COVERFLOW=1 JPG_QUALITY=90 EXTFLASH_SIZE_MB=64 make -j$(nproc)

When building finishes, we will be informed of the resulting binary size that will be flashed to the chip. For example:

1234	`External flash usage Capacity: 61050880 Bytes ( 58.223 MB) Usage: 54335345 Bytes ( 51.818 MB) Free: 6715535 Bytes ( 6.404 MB)`

With that information in sight we can iterate the process adding or removing ROMs until obtaining a binary of about 55MB, since something must be anticipated for the game savestates.

Once we are satisfied with the space usage, we will flash the firmware reconnecting the programming probe discussed in the Programming probe section.

1	`(docker) COVERFLOW=1 JPG_QUALITY=90 EXTFLASH_SIZE_MB=64 make flash`

A typical output would be:

 1 2 3 4 5 6 7 8 91011121314

docker@53335bdd9199:/opt/workdir$ COVERFLOW=1 JPG_QUALITY=90 EXTFLASH_SIZE_MB=64 make flash_gnwmanagerEntering 'LCD-Game-Emulator'Entering 'blueMSX-go'Entering 'caprice32-go'Entering 'fceumm-go'Entering 'gwenesis'Entering 'potator'Entering 'prosystem-go'Entering 'retro-go-stm32'Entering 'smw'Entering 'tamalib'Entering 'zelda3'[ BASH ] Checking for updated roms100%|█████████████████████████████████████████████████████████████████| 208/208 [04:20<00:00, 1.25s/it]

It is important that we keep the build/gw_retro_go.elf file because we will need it to extract the savestates in the future.

Backup retro-go savestates¶

If later we want to extract the game savestates, to be able to reinstall them after flashing a new firmware, first we will need to place the gw_retro_go.elf file we obtained in the previous step in the build directory. Then we can restart the docker environment and run the backup script:

cd ~/git/game-and-watch-retro-gomake docker(docker) export GNW_TARGET=zelda(docker) export ADAPTER=cmsis-dap(docker) ./scripts/saves_backup.sh build/gw_retro_go.elf

The savestates will appear in the ~/git/game-and-watch-retro-go/save_states subdirectory. Once we have built and flashed a new firmware, we can restore them by running the restoration script:

1	`(docker) ./scripts/saves_restore.sh`

Restoration is done intelligently, that is, if we have savestates of a game that is not in the new firmware, that savestate will not be installed on the console, to avoid wasting flash memory space.

Modification 2: retro-go-sd¶

microSD slot module installation¶

As with the modification for normal retro-go, to use retro-go-sd you must start by making a hardware modification to the console. This time it is more complicated, especially the final phase of soldering the module directly onto the microcontroller's pins, which have a very small pitch.

The module consists of the microSD card reader itself and 4 components. All this soldered onto a flex-type PCB. The complete list of components is:

1 microSD card reader
1 100kΩ 0603 resistor or 0805
2 1μF 0603 capacitors or 0805
1 RT9193-28GB voltage regulator. There are people who have reported problems with this model bought on Aliexpress and recommend the "MIC5504-2.8YM5-TR" as a replacement.
1 flex PCB: Here the version by PrimoAngelo is used. The original one usually referenced in most guides is the one by Tim Schuerewegen / hundshamer.

We will begin by soldering the components onto the flex PCB.

The next step as we said at the beginning will be the difficult step of installing the module in the console. We remove the four screws that fall on its surface and present it in a way that we get the pads of the flex to align with the pins of the microcontroller while these end up at their feet, that is, like this.

Once it is aligned to our liking, we will proceed to fix it in its position by driving in the four screws. Now is when we will have to arm ourselves with patience and high-quality flux to manage to solder the pads of the flex and simultaneously avoid bridges between them. It will be necessary to check the continuity of the solders as well as the non-existence of bridges between adjacent pins. If we finally succeed, all that remains is to add a solder point between the pad marked with +4V and the capacitor terminal next to it.

Bootloader flashing¶

The next step will be to flash the bootloader along with the console's patched original firmware to allow dual boot (this time it is worthwhile as we have practically unlimited space for ROMs on the microSD). From the directory where the console backup files are located and with a Python environment that has gnwmanager installed, we will execute the following command:

1	`(gnwmanager) $ gnwmanager flash-patch zelda internal_flash_backup_zelda.bin flash_backup_zelda.bin --bootloader`

A typical output would be:

(gnwmanager) $ gnwmanager flash-patch zelda internal_flash_backup_zelda.bin flash_backup_zelda.bin --bootloader100%|███████████████████████████████████████████████████████████████████| 16/16 [00:58<00:00, 3.66s/it]

If we turn on the console at that moment, after removing the programming probe, we will see that the (patched) original firmware starts. After pressing GAME + LEFT, the bootloader will execute and, as Retro-Go SD is not yet installed in the internal flash of the STM32 at that moment, we will be shown the following warning:

Retro-Go SD installation¶

All that remains is to install the Retro-Go SD firmware. To do this, we will copy the retro-go_update.bin file that we will download from the latest release published by Sylverb in the Retro-Go SD repository to the root directory of the microSD. When booting for the first time, we will see on screen how the retro-go files and emulator cores are copied to the microSD itself.

At the same time, the following directory structure will be created on the microSD:

 1 2 3 4 5 6 7 8 9101112131415161718192021222324252627

retro-go/├── CONFIG├── bios/│ ├── coleco/│ ├── msx/│ ├── nes/├── cores/│ ├── mappers/│ ├── a2600.bin│ ├── a2600_defprops.bin│ ├── a7800.bin│ └── ...├── data/│ ├── a2600/│ ├── a7800/│ ├── amstrad/│ └── ...├── fonts/│ ├── cp1251_greybeard.bin│ ├── cp1251_sans_serif.bin│ ├── cp1251_sans_serif_bold.bin│ └── ...└── roms/ ├── a2600/ ├── a7800/ ├── amstrad/ └── ...

All that remains is to copy the ROMs we want to emulate to the corresponding directories. If we want cover art for the games, we will need to create the covers subdirectory with the same subdirectories as the roms directory and place the images there. These must be in a special IMG format that we will generate with a script included in the Retro-Go SD repository. The IMG file names must match those of the ROMs in their corresponding directory.

Back case¶

When installing the microSD slot, you need to modify the back cover of the console because the reader falls over some support posts on the d-pad. You also need to drill a hole in the side to allow access to the microSD so you can extract and insert it when you want to change games, rescue savestates, or update the firmware. To perform the drilling, there are some tools designed by the user facelesstech that help keep the slot clean. You can see how this modification is performed in the video at the end of this article.

There is an alternative if we don't want to risk permanently damaging the original cover, and that is to 3D print the model created by the user Aradia, which can be downloaded here.

The green color I found most similar to the Zelda console is the 15-Green from OVERTURE.

Controls¶

Below we indicate the key combinations for controlling Retro-go SD (although many of them also work in Retro-go). Holding down the PAUSE/SET button while pressing other buttons performs the following actions:

Key combination	Action
`PAUSE/SET` + `GAME`	Save a screenshot (disabled by default in builds with 1MB flash)
`PAUSE/SET` + `TIME`	Change execution speed (1x/1.5x)
`PAUSE/SET` + `UP`	Increase brightness
`PAUSE/SET` + `DOWN`	Decrease brightness
`PAUSE/SET` + `RIGHT`	Increase volume
`PAUSE/SET` + `LEFT`	Decrease volume
`PAUSE/SET` + `B`	Load state
`PAUSE/SET` + `A`	Save state
`PAUSE/SET` + `A`	Autofire on button A
`PAUSE/SET` + `B`	Autofire on button B
`PAUSE/SET` + `POWER`	Poweroff without savestate
`PAUSE/SET` + `POWER`	After having done `PAUSE/SET` and selected `Power off`, the bootloader will start without calling Retro-go, allowing us to see the bootloader version as well as information about the microSD detection and the state of the internal and external flash memories
`PAUSE/SET` + `GAME` + `LEFT`	From the OFW, it causes the bootloader to start without fully loading retro-go. It is used to see the screen that shows the SD detection, flash chip, and code in bank2 of the internal flash; it is also used to see the bootloader version.
`GAME` + menu `Reset settings`	Clears the registration data in the SD of what is cached in the flash; use when changing the SD of the machine or when changing the flash chip. It is equivalent to deleting the file `flashcachedata.bin` in the `data` directory of the SD.

References¶

I would not like to finish without mentioning the stacksmashing Discord server and the following users whose work has made these modifications possible:

stacksmashing
kbeckmann
Tim Schuerewegen
BrianPugh
GMMan
tfmoe__
Sylver Bruneau
facelesstech
DasBoss
bxhxx
Benjamin Solberg
orzeus
ducalex
ZimM
Ninoh-FOX
PrimoAngelo
Aradia

In the following Macho Nacho video you can see the whole console modification process (the flex of the microSD module is the model that is not held by screws but with solder points on the G&W PCB):

Instalación Arch Linux en Lenovo ThinkPad T480

Sat, 28 Jun 2025 22:30:00 +0200

Tras cruzarme por casualidad con varios vídeos contando las excelencias del Lenovo ThinkPad T480 y de estar ligeramente disgustado con el portátil que adquirí el verano pasado como equipo principal, decidí comprar uno de segunda mano. En concreto el modelo que compré es el T480 con un procesador Intel Core i5-8250U, 16GB de RAM y disco SSD de 1TB. Costó 252€ puesto en casa al día siguiente, y fue adquirido en un vendendor especializado en reacondicionar equipos del que también vi algún vídeo por lo que esperaba que el equipo estuviera en buen estado. Así fue. El equipo llegó con un aspecto impecable, como nuevo, con sus dos baterías funcionales (la interna y la externa). El ThinkPad T480, en su momento tenía muchas opciones de configuración a la hora de adquirirlo. Por este motivo, al comprarlo en una de estas empresas de reacondicionamiento, es posible que el equipo tenga características distintas. Esta es la hoja de especificaciones del equipo donde pueden verse todas las opciones de hardware: PSREF Lenovo ThinkPad T480.

El Lenovo ThinkPad T480 es un portátil de 14" con un teclado excelente, una pantalla IPS FullHD (1920x1080) y una buena conectividad (2 puertos USB-C uno de ellos Thunderbolt, 2 puertos USB-A 3.0, HDMI, Ethernet, lector de tarjetas SD y jack de auriculares/micrófono). Internamente es muy modificable, ya que tiene la RAM en dos sockets SODIMM, el disco SSD en un socket SATA que se puede convertir en M.2, un par de puertos PCIe donde se puede conectar más almacenamiento intento SSD o cosas como un modem 5G y la batería interna es también sustituible fácilmente. Además, la compatibilidad con Linux está asegurada, ya que Lenovo proporciona drivers para Linux y la comunidad ha desarrollado drivers para el resto de componentes.

Lo que sigue es el procedimiento completo que he utilizado para instalar Arch Linux en él.

Reparticionado del disco¶

El equipo trae Windows 11 Pro instalado ocupando todo el disco. El plan es mantenerlo y hacer sitio para instalar Arch Linux junto a él. El tamaño de 1TB del disco SSD del equipo es perfecto para poder alojar dos sistemas operativos sin problemas.

El primer paso es encoger la partición de Windows. Para poder hacerlo, BitLocker debe estar desactivado. En la instalación de Windows 11 que trae el equipo, BitLocker estaba ya desactivado. La partición la podemos encoger con el propio Windows en marcha, desde el Administrador de discos (buscándolo en el menú Inicio o pulsando Win+X). Una vez en el Administrador de discos, pulsamos con el botón derecho del ratón sobre la partición C: y seleccionamos la opción Reducir volumen.... En mi caso, reduje el volumen en 750GB, quedando la partición de Windows con un tamaño de unos 220GB.

En las instalaciones de Windows, hay una patición pequeña al final del disco que es la partición de recuperación. Al encoger la partición principal, el espacio libre queda antes de esta partición y por tanto, al crear las particiones para Linux más adelante, éstas tendrán un número superior a la partición de recuperación, pero se encontrarán antes. Esto en sistemas de archivos GPT no es un problema.

Instalación base¶

Para el proceso de instalación del sistema base me decanté por el camino convencional siguiendo las instrucciones de la guía de instalación en el wiki de Arch. Dicha instalación utiliza una ISO de un sistema Arch que podremos arrancar desde una unidad extraíble USB con el que instalaremos los paquetes mínimos para tener un sistema arrancable y muy básico.

Antes de comenzar, comentar que por las características tan dinámicas de la distribución Arch Linux, es muy posible que esta guía quede desactualizada en algún momento. Por lo que recomiendo consultar la guía oficial en caso de encontrar que algo no sale como se supone.

A continuación vemos paso a paso el proceso de instalación:

Descargar la ISO de Arch Linux. En concreto en mi caso utilicé ésta versión.
Instalar la ISO en un pendrive. Puede utilizarse un programa como Balena Etcher o el comando dd de Linux si se sabe manejar (donde /dev/sdX es el dispositivo del pendrive; puede comprobarse con el comando lsblk):
1
sudo dd bs=4M if=archlinux-2025.06.01-x86_64.iso of=/dev/sdX conv=fsync oflag=direct status=progress
Arrancar el portátil con el pendrive insertado. Pulsar Enter cuando ofrece interrumpir el proceso normal de arranque y acto seguido F12. Esto hace que el ordenador arranque en el Boot Menu.
Seleccionar la opción para arrancar desde el dispositivo extraíble que aparecerá en el menú como USB HDD: Mass Storage Device.
Una vez que termine de arrancar el sistema live de instalación de Arch, ejecutar los siguiente comandos en orden. En caso de conectar a la red por cable Ethernet, se puede evitar la sesión con iwctl (en la cual sustituiremos <SSID> por nuestro SSID e introduciremos la contraseña cuando se nos pida):
12345678
# loadkeys es# iwctl[iwd]# station wlan0 scan[iwd]# station wlan0 get-networks[iwd]# station wlan0 connect <SSID>[iwd]# exit# timedatectl# fdisk /dev/sda
En el programa fdisk crear las siguientes particiones (en mi caso):
- sda5: 8GB, tipo Linux swap, con el identificador 19.
- sda6: Espacio restante (724,4GB), tipo Linux filesystem, con el identificador 20.

Salir de fdisk escribiendo w y pulsando Enter. Continuar con los siguientes comandos (sustituir <USER> por el nombre de usuario que se quiera crear):

 1 2 3 4 5 6 7 8 91011121314151617181920212223242526

# mkfs.ext4 /dev/sda6# mkswap /dev/sda5# mount /dev/sda6 /mnt# mount --mkdir /dev/sda1 /mnt/boot/efi# swapon /dev/sda5# pacstrap -K /mnt base base-devel linux linux-firmware sudo vi ntfs-3g networkmanager intel-ucode grub efibootmgr os-prober# genfstab -U /mnt >> /mnt/etc/fstab# arch-chroot /mnt# ln -sf /usr/share/zoneinfo/Europe/Madrid /etc/localtime# hwclock --systohc# vi /etc/locale.gen # Descomentar 'en_US.UTF-8 UTF-8' y 'es_ES.UTF-8 UTF-8'# locale-gen# echo "LANG=es_ES.UTF-8" > /etc/locale.conf# echo "KEYMAP=es" > /etc/vconsole.conf# echo "thinkpad" > /etc/hostname# echo -e "\n127.0.0.1 localhost\n::1 localhost\n127.0.1.1 thinkpad.localdomain thinkpad" >> /etc/hosts# passwd# useradd -m -G wheel,audio,video,storage -s /bin/bash <USER># passwd <USER># visudo # Descomentar '%wheel ALL=(ALL) ALL'# systemctl enable NetworkManager# vi /etc/default/grub # Descomentar 'GRUB_DISABLE_OS_PROBER=false'# os-prober# grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=GRUB# grub-mkconfig -o /boot/grub/grub.cfg# su - <USER>

Instalación entorno gráfico¶

Continuamos donde nos habíamos quedado, es decir en la sesión chroot desde el sistema live de instalación de Arch Linux. Lo haremos ya con el usuario normal (no root) por lo que a partir de ahora haremos uso con frecuencia de sudo.

Ahora vamos a instalar el entorno gráfico, en mi caso XFCE4. En caso de elegir otro, aquí hay una lista de entornos gráficos soportados oficialmente por Arch Linux y las instrucciones correspondientes.

$ sudo pacman -Syy$ sudo pacman -S xfce4 xfce4-goodies xorg xdg-user-dirs pavucontrol gvfs gvfs-smb thunar-archive-plugin unzip unrar lightdm lightdm-gtk-greeter lightdm-gtk-greeter-settings pipewire pipewire-pulse pipewire-alsa wireplumber git cmake$ sudo systemctl enable lightdm

Instalar el gestor de paquetes yay para poder instalar paquetes desde AUR:

123	`$ git clone https://aur.archlinux.org/yay.git$ cd yay$ makepkg -si`

Por último instalar algunos programas y paquetes que nos serán útiles:

$ sudo pacman -S firefox firefox-i18n-es libreoffice-fresh gimp vlc vlc-plugins-all usbutils htop btop openssh man-pages-es xdg-user-dirs-gtk alsa-utils network-manager-applet blueman fwupd gparted terminator vlc gimp shutter audacity openshot ghex net-tools sshuttle gucharmap$ sudo systemctl enable --now sshd

Cerramos la sesión chroot, desmontamos las particiones y reiniciamos el sistema:
1234
$ exit# exit# umount -R /mnt# reboot

Applet NetworkManager y Bluetooth¶

Para que el applet de NetworkManager funcione correctamente, debemos instalar el paquete network-manager-applet y añadirlo al autostart de XFCE4. Vamos a hacer algo parecido con el Bluetooth. Para ello, una vez iniciado el entorno gráfico, ejecutar:

123	`$ sudo pacman -S network-manager-applet blueman$ sudo systemctl start bluetooth$ sudo systemctl enable --now bluetooth`

Ahora debemos añadir los applets al autostart de XFCE4. Para ello, ir a Configuración > Sesión y arranque > Aplicaciones de inicio y pulsar en Añadir. En el campo Nombre escribir NetworkManager Applet, en Comando escribir nm-applet y en Comentario podemos dejarlo vacío o poner algo como Applet de NetworkManager. Hacemos lo mismo para el Bluetooth, añadiendo un nuevo applet con el nombre Bluetooth, el comando blueman-applet y un comentario opcional.

Instalación pamac¶

Para facilitar la instalación de paquetes desde la interfaz gráfica, vamos a instalar pamac:

1	`$ yay -S pamac-aur`

Una vez instalado, abrirlo (buscando Añadir/Quitar software en el cajón de aplicaciones) y activar el soporte AUR en Preferencias > Terceros > Activar soporte de AUR.

Conclusión¶

Y esto sería todo. Ahora tenemos un sistema dualboot Arch Linux / Windows en el ThinkPad T480.

Enlaces de interés¶

Guía de instalación de Arch Linux
Instalación y configuración de Arch Linux en un portátil Lenovo ThinPad T480
Hoja de especificaciones del Lenovo ThinPad T480
Actualización de firmwares con fwupd
Howdy for Linux: Howdy proporciona autenticación estilo Windows Hello™ para Linux. Usa los emisores IR y la cámara integrados junto con reconocimiento facial para verificar tu identidad.
Install Libreboot on Lenovo ThinkPad T480 and/or T480s
Problema en el firmware Thunderbolt:
- Critical Intel Thunderbolt Software and Firmware Updates - ThinkPad
- Sustitución EPROM

Arch Linux Installation on Lenovo ThinkPad T480

Sat, 28 Jun 2025 22:30:00 +0200

After stumbling upon several videos praising the Lenovo ThinkPad T480 and feeling slightly dissatisfied with the laptop I bought last summer as my main device, I decided to buy a second-hand one. Specifically, I bought the T480 model with an Intel Core i5-8250U processor, 16GB RAM, and a 1TB SSD. It cost €252 delivered the next day, and I purchased it from a specialized refurbisher whose videos I had also seen, so I expected the machine to be in good condition. And it was. The laptop arrived in impeccable condition, like new, with both its batteries functional (internal and external). The ThinkPad T480 originally had many configuration options available. For this reason, when buying it from a refurbisher, it may come with different hardware features. Here is the full spec sheet where all hardware options can be seen: PSREF Lenovo ThinkPad T480.

The Lenovo ThinkPad T480 is a 14" laptop with an excellent keyboard, an IPS FullHD screen (1920x1080), and good connectivity (2 USB-C ports, one of them Thunderbolt, 2 USB-A 3.0 ports, HDMI, Ethernet, SD card reader, and audio/mic jack). Internally it's very customizable, as it has two SODIMM RAM slots, an SSD in a SATA slot that can be converted to M.2, a couple of PCIe ports for additional SSD storage or a 5G modem, and the internal battery is also easily replaceable. Moreover, Linux compatibility is excellent, as Lenovo provides Linux drivers and the community has developed drivers for the rest of the components.

What follows is the full procedure I used to install Arch Linux on it.

Disk repartitioning¶

The laptop comes with Windows 11 Pro installed occupying the entire disk. The plan is to keep it and make room to install Arch Linux alongside. The 1TB SSD is perfect to accommodate two operating systems without issues.

The first step is to shrink the Windows partition. To do so, BitLocker must be disabled. In the Windows 11 installation that came with the machine, BitLocker was already disabled. We can shrink the partition using Windows itself, through the Disk Management tool (search in Start menu or press Win+X). Once there, right-click the C: partition and select Shrink Volume.... In my case, I shrank it by 750GB, leaving around 220GB for Windows.

Windows installations have a small recovery partition at the end of the disk. When shrinking the main partition, the free space appears before this recovery partition. Thus, when creating Linux partitions later, their numbering will be higher than the recovery partition but will physically be located before it. This is not a problem when using GPT partitioning schemes.

Base installation¶

For the base system installation, I chose the conventional route following the installation guide from the Arch wiki. This installation uses an ISO of an Arch live system that we boot from a removable USB drive and use to install the minimal packages for a bootable, very basic system.

Before we begin, it's worth noting that due to the dynamic nature of Arch Linux, this guide may become outdated. I recommend checking the official guide if something doesn't go as expected.

Here is the step-by-step installation process:

Download the Arch Linux ISO. I used this version.

Flash the ISO to a USB stick using Balena Etcher or the dd command in Linux (if you know how to use it):

1	`sudo dd bs=4M if=archlinux-2025.06.01-x86_64.iso of=/dev/sdX conv=fsync oflag=direct status=progress`

Boot the laptop with the USB stick inserted. Press Enter when prompted to interrupt normal boot, then press F12 to enter the Boot Menu.
Select the option to boot from the removable device, listed as USB HDD: Mass Storage Device.
Once the Arch live system boots, run the following commands in order. If using a wired Ethernet connection, you can skip the iwctl session (replace <SSID> with your network name and enter the password when prompted):
12345678
# loadkeys es# iwctl[iwd]# station wlan0 scan[iwd]# station wlan0 get-networks[iwd]# station wlan0 connect <SSID>[iwd]# exit# timedatectl# fdisk /dev/sda
In fdisk, create the following partitions:
- sda5: 8GB, type Linux swap, ID 19.
- sda6: Remaining space (724.4GB), type Linux filesystem, ID 20.

Exit fdisk by typing w and pressing Enter. Continue with the following commands (replace <USER> with your desired username):

 1 2 3 4 5 6 7 8 91011121314151617181920212223242526

# mkfs.ext4 /dev/sda6# mkswap /dev/sda5# mount /dev/sda6 /mnt# mount --mkdir /dev/sda1 /mnt/boot/efi# swapon /dev/sda5# pacstrap -K /mnt base base-devel linux linux-firmware sudo vi ntfs-3g networkmanager intel-ucode grub efibootmgr os-prober# genfstab -U /mnt >> /mnt/etc/fstab# arch-chroot /mnt# ln -sf /usr/share/zoneinfo/Europe/Madrid /etc/localtime# hwclock --systohc# vi /etc/locale.gen # Uncomment 'en_US.UTF-8 UTF-8' and 'es_ES.UTF-8 UTF-8'# locale-gen# echo "LANG=es_ES.UTF-8" > /etc/locale.conf# echo "KEYMAP=es" > /etc/vconsole.conf# echo "thinkpad" > /etc/hostname# echo -e "\n127.0.0.1 localhost\n::1 localhost\n127.0.1.1 thinkpad.localdomain thinkpad" >> /etc/hosts# passwd# useradd -m -G wheel,audio,video,storage -s /bin/bash <USER># passwd <USER># visudo # Uncomment '%wheel ALL=(ALL) ALL'# systemctl enable NetworkManager# vi /etc/default/grub # Uncomment 'GRUB_DISABLE_OS_PROBER=false'# os-prober# grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=GRUB# grub-mkconfig -o /boot/grub/grub.cfg# su - <USER>

Graphical environment installation¶

We continue from where we left off, that is, in the chroot session from the Arch Linux live installer. From now on we'll use a regular user (not root), so we'll often use sudo.

Now install the graphical environment — I chose XFCE4. If you prefer another one, here is a list of officially supported desktop environments and instructions.

$ sudo pacman -Syy$ sudo pacman -S xfce4 xfce4-goodies xorg xdg-user-dirs pavucontrol gvfs gvfs-smb thunar-archive-plugin unzip unrar lightdm lightdm-gtk-greeter lightdm-gtk-greeter-settings pipewire pipewire-pulse pipewire-alsa wireplumber git cmake$ sudo systemctl enable lightdm

Install the yay package manager to install packages from AUR:

123	`$ git clone https://aur.archlinux.org/yay.git$ cd yay$ makepkg -si`

Finally, install some useful applications and packages:

$ sudo pacman -S firefox firefox-i18n-es libreoffice-fresh gimp vlc vlc-plugins-all usbutils htop btop openssh man-pages-es xdg-user-dirs-gtk alsa-utils network-manager-applet blueman fwupd gparted terminator vlc gimp shutter audacity openshot ghex net-tools sshuttle gucharmap$ sudo systemctl enable --now sshd

Exit the chroot session, unmount the partitions, and reboot:
1234
$ exit# exit# umount -R /mnt# reboot

NetworkManager and Bluetooth Applets¶

To make the NetworkManager applet work properly, we need to install the network-manager-applet package and add it to XFCE4 autostart. We’ll do something similar for Bluetooth. Once in the graphical environment, run:

123	`$ sudo pacman -S network-manager-applet blueman$ sudo systemctl start bluetooth$ sudo systemctl enable --now bluetooth`

Now add both applets to XFCE4 autostart. Go to Settings > Session and Startup > Application Autostart and click Add. In Name, enter NetworkManager Applet, in Command, enter nm-applet, and you can leave Comment empty or write something like NetworkManager applet. Do the same for Bluetooth: name Bluetooth, command blueman-applet, optional comment.

Installing pamac¶

To make graphical package management easier, install pamac:

1	`$ yay -S pamac-aur`

Once installed, open it (search for Add/Remove Software in the application menu) and enable AUR support under Preferences > Third Party > Enable AUR support.

Conclusion¶

And that’s it. Now we have a dual boot Arch Linux / Windows system on the ThinkPad T480.

Links of interest¶

Arch Linux Installation Guide
Installation and configuration of Arch Linux on a Lenovo T480 laptop
Lenovo ThinkPad T480 Specification Sheet
Firmware updates with fwupd
Howdy for Linux: Howdy provides Windows Hello™ style authentication for Linux. Use your built-in IR emitters and camera in combination with facial recognition to prove who you are.
Install Libreboot on Lenovo ThinkPad T480 and/or T480s
Thunderbolt firmware problem:
- Critical Intel Thunderbolt Software and Firmware Updates - ThinkPad
- EPROM replacement

ZX Mechtrum

Mon, 09 Sep 2024 12:00:00 +0200

Hace tiempo que me apetecía montar un kit de ZX Spectrum Harlequin 128. Es el Spectrum perfecto (128KB, soporte de todos los modelos/ROMs de las distintas versiones producidas por Sinclair y Amstrad, y con componentes que se pueden adquirir a día de hoy, incluida la ULA que está reemplazada por lógica discreta). Pero para la caja, la opción de adquirir una de las carcasas réplica del 48K original (gomas), no me entusiasmaba.

Hace unos meses conocí el proyecto ZX Mechtrum de Lee Smith, una caja para placas de formato 48KB con un teclado mecánico, y me pareció el complemento perfecto para el Harlequin. De hecho, en el vídeo del canal More Fun Making It gracias al que supe de su existencia, su creador comenta que tiene el proyecto inmediato de instalar un Harlequin 128 en una de estas cajas.

Como ya existen varios vídeos y guías tanto del kit Harlequin como de la caja ZX Mechtrum, no voy a detallar el proceso de montaje, pero sí describirlo en general y comentar algunas particularidades y problemas que he encontrado.

Mechtrum¶

Como el kit Harlequin 128 es distribuido por Byte Delight, por lo que su disponibilidad es bastante estable, el punto más crítico del plan era adquirir el Mechtrum de Lee Smith, ya que la venta de productos no es su principal actividad. De hecho pude conseguir la última unidad de una tirada que hizo a finales de 2023. En el momento de escribir esto (septiembre 2024) vuelve a estar a la venta, pero no es de esperar que se mantenga siempre así. El caso es que pude adquirir una unidad que llegó ya montada. Mi unidad venía con 3 faceplates, una para el 48K, otra para el Sifzif 512 y otra para el Harlequin 128.

Harlequin 128¶

El Harlequin 128, es un diseño de Don Superfo y puede adquirirse la PCB a través de los enlaces que hay en el repositorio base del proyecto. En el repositorio se encuentra también la BOM (Bill Of Materials) para las distintas versiones con todos los componentes necesarios. Pero con diferencia la opción más sencilla es adquirir uno de los kits que distribuye Ben Versteeg, de Byte Delight. El kit viene con una PCB de la versión issue 2D y todos los componentes necesarios para montarlo, convenientemente clasificados en bolsitas junto a un manual con el que es casi imposible perderse. También hay épocas en las que no está disponible en su tienda, pero es cuestión de estar atento o suscribirse a las notificaciones de disponibilidad. En mi caso tuve que esperar un par de meses a que volviera a estar disponible.

El único problema que tuve durante su montaje fue que según el manual el array de resistencias R61 es opcional si no se va a instalar la interfaz de joystick. Pero esas resistencias, además de dar servicio al puerto de joystick, hacen de pullup para los microinterruptores de selección del banco de ROM, por lo que sin instalarlas, la selección de bancos de ROM superiores al 0 no era estable. Tras instalar el array R61, todo funcionó correctamente.

Resultado¶

El resultado es un sueño hecho realidad, un Spectrum 128K con teclado mecánico y componentes fiables. Además de una belleza. 🤩

ZX Mechtrum

Mon, 09 Sep 2024 12:00:00 +0200

For a while, I’ve wanted to assemble a ZX Spectrum Harlequin 128 kit. It’s the perfect Spectrum (128KB, supports all models/ROMs from the various versions produced by Sinclair and Amstrad, and with components that can still be acquired today, including the ULA, which has been replaced by discrete logic). However, the option of purchasing a replica case of the original 48K (rubber keys) didn’t really excite me.

A few months ago, I came across Lee Smith’s ZX Mechtrum project, a case for 48KB-format boards with a mechanical keyboard, and it seemed like the perfect complement for the Harlequin. In fact, in the video from the More Fun Making It channel, through which I learned of its existence, its creator mentions that he plans to install a Harlequin 128 in one of these cases soon.

Since there are already several videos and guides for both the Harlequin kit and the ZX Mechtrum case, I won’t detail the assembly process but will instead describe it generally and mention some peculiarities and problems I encountered.

Mechtrum¶

Since the Harlequin 128 kit is distributed by Byte Delight, its availability is quite stable, so the most critical point of the plan was acquiring the Mechtrum from Lee Smith, as selling products is not his main activity. In fact, I managed to get the last unit from a batch he made in late 2023. As of writing this (September 2024), it’s back on sale, but it’s not expected to remain available for long. In any case, I was able to acquire a unit that arrived pre-assembled. My unit came with 3 faceplates, one for the 48K, another for the Sifzif 512, and one for the Harlequin 128.

Harlequin 128¶

The Harlequin 128 is a design by Don Superfo, and the PCB can be purchased through the links provided in the project’s base repository. The repository also contains the BOM (Bill Of Materials) for the different versions with all the necessary components. However, by far the easiest option is to purchase one of the kits distributed by Ben Versteeg from Byte Delight. The kit comes with an issue 2D version PCB and all the necessary components to assemble it, conveniently sorted into bags along with a manual that makes it almost impossible to get lost. There are times when it’s not available in his store, but it’s just a matter of staying alert or subscribing to availability notifications. In my case, I had to wait a couple of months for it to become available again.

The only problem I encountered during assembly was that, according to the manual, the R61 resistor array is optional if you’re not going to install the joystick interface. However, these resistors, in addition to serving the joystick port, also act as pullups for the ROM bank selection microswitches, so without them, selecting ROM banks higher than 0 was unstable. After installing the R61 array, everything worked correctly.

Resultado¶

The result is a dream come true: a 128K Spectrum with a mechanical keyboard and reliable components. And it’s a beauty. 🤩

Instalación Arch Linux en Steam Deck

Wed, 04 Sep 2024 15:30:00 +0200

Pérdida de dual boot al actualizar SteamOS

En la actualización de SteamOS a la rama 3.6 (en concreto la primera versión estable de esa rama fue la 3.6.19) se perdió la configuración del dualboot por lo que la máquina sólo arrancaba en SteamOS. La solución fue volver a seguir los pasos de Instalación gestor dualboot a partir del paso 4.

En julio de 2024 durante unas semanas, el modelo de 512GB de la Steam Deck LCD pudo adquirirse por debajo de los 400€. Un precio muy atractivo para una máquina decente con procesador AMD de arquitectura x86 (AMD64), 16GB de RAM, disco SSD tipo NVMe de la capacidad mencionada antes, pantalla táctil y controles de juego integrados. Es decir un PC consolizado, pero un PC al fin y al cabo. Pero sobre todo lo que hace para mi especialmente atractiva la máquina es su soporte Linux completo, lo que la convierte en una plataforma ideal para cacharrear con distribuciones Linux o utilizarlo como PC portátil secundario. Todo esto naturalmente además de su uso convencional para jugar y emular videojuegos.

SteamOS, el sistema operativo que trae de serie, está basado en Arch Linux, y en su modo escritorio, puede utilizarse prácticamente como un Arch Linux normal. La principal restricción es que está construido en modo inmutable y a pesar de que este tipo de configuración de sistema tiene sus virtudes y se entiende perfectamente que Valve lo haya escogido para su máquina, todavía prefiero un sistema normal (mutable), por lo que me decidí por instalar un Arch normal y aprender a instalar de paso esta distribución. Según el wiki de Arch, el hardware del modelo LCD de la Steam Deck está soportado al 100% en Arch.

Lo que sigue es el procedimiento completo que he utilizado.

Teclado/ratón¶

Aunque gran parte de las operaciones pueden hacerse utilizando la pantalla táctil y los trackpads de la Steam Deck, es muy recomendable conectar un teclado y ratón a la consola para facilitar la instalación, sobre todo durante la sesión de terminal con la que instalaremos el sistema base. La Steam Deck sólo posee un puerto USB-C, por lo que lo más práctico es utilizar un dock. También puede ser suficiente (sobre todo si ejecutamos los sistemas live desde una microSD) con un dongle de teclado/ratón inalámbricos conectados con un adaptador USB<->USB-C, aunque en ese caso conviene asegurarse de que la Steam Deck tiene la batería completamente cargada.

En mi caso utilicé un dock DA310z de Dell.

Reparticionado del disco¶

El disco SSD de la Steam Deck que adquirí es de 512GB y de tipo NVMe. Es el tamaño mínimo si queremos instalar otro sistema junto a SteamOS.

Antes de empezar con la instalación debemos hacer hueco para la misma encogiendo la partición principal (la número 8). Para ello podemos utilizar prácticamente cualquier distribución live Linux que arranquemos desde una unidad extraíble (USB o microSD) ya que todas ellas llevan algún programa para gestionar particiones. En mi caso utilicé una ISO del programa gparted.

El procedimiento completo puede verse a continuación:

Descargar la ISO de gparted. En concreto en mi caso utilicé ésta versión.
Instalar la ISO en un pendrive o mejor aún en una microSD (ya que la Steam Deck posee una ranura para éstas). Puede utilizarse un programa como Balena Etcher o el comando dd de Linux si se sabe manejar.
Arrancar la Steam Deck con el pendrive o la microSD insertada manteniendo pulsado el botón de bajar el volumen hasta que se escuchen los tonos de encendido. Esto hace que la consola arranque en el menú Boot Manager.
Seleccionar la opción de arrancar desde el dispositivo extraíble que aparecerá en el menú como EFI USB Device (USB) o EFI SD/MMC Card (XX XXXX XXXX) según si utilizamos un pendrive o una microSD respectivamente.
Aparece una pantalla de configuración en la que hacemos las siguientes selecciones:
- Policy for handling keymaps => Don't touch keymap
- Which language do you prefer? => 25
- Which mode do you prefer? => 0
Tras aceptar la última opción anterior, arrancará el programa gparted en modo gráfico (con la pantalla girada, eso sí). Haremos cambios hasta dejar las particiones como se ve en la foto. Básicamente lo que haremos será encoger la partición #8 unos 100GB, crear la #9 de 4GB para swap y la #10 con el espacio restante para el sistema raíz de Arch:

Destacar a la vista de las particiones que utiliza SteamOS que hace uso de un sistema de particiones A/B, habitual en Android, por el cual la mayoría de las particiones del sistema (excepto la de usuario) están duplicadas. Dicho sistema está pensado para facilitar las actualizaciones, o más bien para volver atrás en caso de problemas durante las mismas.

Instalación base¶

Para el proceso de instalación del sistema base me decanté por el camino convencional siguiendo las instrucciones de la guía de instalación en el wiki de Arch. Dicha instalación utiliza una ISO de un sistema Arch que podremos arrancar desde una unidad extraíble (USB o microSD) con el que instalaremos los paquetes básicos para tener un sistema arrancable y muy básico.

Antes de comenzar, comentar que por las características tan dinámicas de la distribución Arch Linux, es muy posible que esta guía quede desactualizada en poco tiempo. Por lo que recomiendo consultar la guía oficial en caso de encontrar que algo no sale como se supone.

A continuación vemos paso a paso el proceso de instalación:

Descargar la ISO de Arch Linux. En concreto en mi caso utilicé ésta versión.
Instalar la ISO en un pendrive o mejor aún en una microSD para utilizar la ranura que posee la Steam Deck. Puede utilizarse un programa como Balena Etcher o el comando dd de Linux si se sabe manejar.
Arrancar la Steam Deck con el pendrive o la microSD insertada manteniendo pulsado el botón de bajar el volumen hasta que se escuchen los tonos de encendido. Esto hace que la consola arranque en el menú Boot Manager.
Seleccionar la opción de arrancar desde el dispositivo extraíble que aparecerá en el menú como EFI USB Device (USB) o EFI SD/MMC Card (XX XXXX XXXX) según si utilizamos un pendrive o una microSD respectivamente.

Una vez que termine de arrancar el sistema live de instalación de Arch, ejecutar los siguiente comandos en orden (en la sesión con iwctl sustituiremos <SSID> por el nuestro e introduciremos la contraseña cuando se nos pida; también sustituiremos el identificador de usuario <USER> por el que queramos utilizar):

 1 2 3 4 5 6 7 8 910111213141516171819202122232425262728293031323334

# loadkeys es# iwctl[iwd]# station wlan0 scan[iwd]# station wlan0 get-networks[iwd]# station wlan0 connect <SSID>[iwd]# exit# mkfs.ext4 /dev/nvme0n1p10# mkswap /dev/nvme0n1p9# mount /dev/nvme0n1p10 /mnt# mount --mkdir /dev/nvme0n1p1 /mnt/boot/efi# swapon /dev/nvme0n1p9# pacstrap -K /mnt base base-devel linux linux-firmware sudo vi ntfs-3g networkmanager amd-ucode grub efibootmgr git cmake qt5-wayland# genfstab -U /mnt >> /mnt/etc/fstab# arch-chroot /mnt# ln -sf /usr/share/zoneinfo/Europe/Madrid /etc/localtime# hwclock --systohc# vi /etc/locale.gen # descomentar 'en_US.UTF-8 UTF-8' y 'es_ES.UTF-8 UTF-8'# locale-gen# echo "LANG=es_ES.UTF-8" > /etc/locale.conf# echo "KEYMAP=es" > /etc/vconsole.conf# echo "deck" > /etc/hostname# echo -e "\n127.0.0.1 localhost\n::1 localhost\n127.0.1.1 deck" >> /etc/hosts# passwd# grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=Arch# grub-mkconfig -o /boot/grub/grub.cfg# systemctl enable NetworkManager# useradd -m -G wheel,audio,video,storage <USER># passwd <USER># chmod u+w /etc/sudoers# vi /etc/sudoers # Descomentar '%wheel ALL=(ALL) ALL'# chmod u-w /etc/sudoers# pacman -Syy# pacman -S xorg-server xf86-video-amdgpu maliit-keyboard qt5-wayland# su - <USER>

El password que elegiremos cuando ejecutemos el comando passwd <USER> debe ser numérico si queremos utilizar Plasma Mobile, ya que la pantalla de desbloqueo sólo nos permite introducir un PIN.

Instalación entorno gráfico¶

Ahora vamos a instalar los entornos gráficos. Lo digo en plural porque vamos a instalar dos, Plasma y Plasma Mobile. Hago esto porque dependiendo de si vamos a utilizar la Steam Deck con Arch en modo escritorio (con teclado/ratón y posiblemente pantalla) o portátil (sin teclado/ratón), nos convendrá más un sistema u otro, dado que Plasma Mobile presenta un interfaz diseñado para ser manejado con una pantalla táctil (estilo tablet).

En realidad no es necesario instalar los dos escritorios, por eso se han separado sus pasos de instalación. Podemos instalar uno, el otro o ambos.

Plasma¶

1	`$ sudo pacman -S plasma-meta`

Durante la instalación del paquete anterior se nos harán una serie de preguntas. A la tercera pregunta responder 2) noto-fonts. En el resto ofrecer la respuesta predeterminada (pulsando retorno).

Plasma Mobile¶

Plasma Mobile no se encuentra todavía en los repositorios oficiales. Tenemos que utilizar AUR:

Empezamos instalando algunas dependencias:

1	`$ sudo pacman -S plasma-workspace kcontacts kirigami2 kpeople libphonenumber`

Instalamos los paquetes de AUR plasma-nano, plasma-settings y plasma-mobile en este orden:

 1 2 3 4 5 6 7 8 9101112

$ cd ~$ git clone https://aur.archlinux.org/plasma-nano.git$ cd plasma-nano$ makepkg -si$ cd ~$ git clone https://aur.archlinux.org/plasma-settings.git$ cd plasma-settings$ makepkg -si$ cd ~$ git clone https://aur.archlinux.org/plasma-mobile.git$ cd plasma-mobile$ makepkg -si

Fin de instalación entorno gráfico¶

Instalamos el gestor de sesiones SDDM y algunas aplicaciones que nos harán falta para terminar la instalación desde el modo gráfico:
123
$ sudo pacman -S sddm konsole dolphin kwrite partitionmanager power-profiles-daemon$ sudo systemctl enable sddm$ exit
Cerramos la sesión chroot, desmontamos las particiones y reiniciamos el sistema:
123
# exit# umount -R /mnt# reboot

Configuración básica¶

Tras reiniciar deberíamos ver el gestor de sesiones SDDM, inicialmente con la pantalla girada y sin posibilidad de utilizar el teclado en pantalla, por lo que todavía continuaremos utilizando el teclado y ratón externos.

Una vez que hayamos iniciado sesión en Plasma o Plasma Mobile, lo primero que tenemos que hacer es configurar la conexión a internet. Para ello hacemos click sobre el icono correspondiente en la bandeja del sistema abajo a la derecha en Plasma o arriba a la derecha en Plasma Mobile.

Una vez que tengamos conexión, abrimos la aplicación Konsole y ejecutamos los siguientes comandos para instalar el paquete de aplicaciones básico de KDE, el navegador Firefox y el servidor SSH:

123	`$ sudo pacman -S firefox kde-applications-meta openssh usbutils lshw man-db htop spectacle$ sudo systemctl start sshd$ sudo systemctl enable sshd`

Finalmente hacemos las siguientes configuraciones:

Preferencias > Preferencias del sistema > Entrada y salida > Pantalla y monitor > Escalar: Configurar la escala de la pantalla a 110%.
Preferencias > Preferencias del sistema > Entrada y salida > Teclado > Distribuciones > Configurar distribuciones > Añadir: Añadir la distribución de teclado español.
Preferencias > Preferencias del sistema > Entrada y salida > Teclado > Teclado virtual: Seleccionar Maliit.
Preferencias > Preferencias del sistema > Idioma y hora > Fecha y hora > Zona horaria: Seleccionar Madrid.
Preferencias > Preferencias del sistema > Aspecto y estilo > Texto y tipos de letra > Tipos de letra. Ajustar estos valores:
- General: Noto Sans 11pt
- Anchura fija: Hack 10pt
- Pequeña: Noto Sans 9pt
- Barra de herramientas: Noto Sans 11pt
- Menú: Noto Sans 11pt
- Título de la ventana: Noto Sans 10pt
Botón derecho (L2) sobre la barra de tareas y seleccionar Mostrar configuración del panel. En Preferencias del panel > Altura del panel subir la altura a 54px.
Botón derecho (L2) sobre el icono que sirve para mostrar los iconos ocultos en la bandeja del sistema y seleccionar Configurar Bandeja del sistema. En General seleccionar estos valores:
- Tamaño de los iconos del panel: Escalar a la altura del panel
- Espacio entre los iconos del panel: Normal
Botón derecho (L2) sobre el icono que sirve para mostrar los iconos ocultos en la bandeja del sistema y seleccionar Mostrar configuración del panel. Veremos un minireloj que antes no se veía sobre el que pulsaremos con el botón derecho (L2). Seleccionamos Mostrar alternativas y de los elementos gráficos alternativos que aparecen escogemos Reloj digital.

Configuración de SDDM¶

Finalmente vamos a mejorar la configuración del gestor de sesiones SDDM para que permita el teclado en pantalla, tenga mejor aspecto y muestre la pantalla en la orientación correcta:

Crear fichero /etc/sddm.conf.d/10-wayland.conf con el siguiente contenido:

[General]DisplayServer=waylandGreeterEnvironment=QT_WAYLAND_SHELL_INTEGRATION=layer-shell[Wayland]CompositorCommand=kwin_wayland --drm --no-lockscreen --no-global-shortcuts --locale1 --inputmethod maliit-keyboard

Abrir Preferencias > Pantalla de inicio de sesión (SDDM), seleccionar Brisa como theme y pulsar el botón Aplicar las preferencias de Plasma... arriba a la derecha.

Configuración sonido¶

Tal y como comenta el wiki de Arch, el volumen por defecto en la Steam Deck es muy bajo. Para solucionarlo hay que instalar el paquete alsa-utils y ejecutar el comando alsamixer para ajustar el volumen de algunos de los canales.

12	`$ sudo pacman -S alsa-utils$ alsamixer`

Para acceder a los mismos, una vez en alsamixer, hay que pulsar F6 para poder seleccionar el dispositivo de audio acp5x ya que por defecto aparecen seleccionado el dispositivo 0 que es el asociado a la salida HDMI del chip gráfico:

Una vez seleccionado el dispositivo correcto, veremos todos sus canales que son muy numerosos. Localizaremos los que menciona el wiki para ajustarlos a los siguientes valores:

Canal	Valor
Analog PCM	85%
Digital	86%
Digital PCM	85%
Left Analog PCM	85%
Left Digital PCM	85%
Right Analog PCM	85%
Right Digital PCM	85%

Instalación pamac¶

Para facilitar la instalación de paquetes desde la interfaz gráfica, vamos a instalar pamac:

1	`$ yay -S pamac-aur`

Una vez instalado lo abrimos (buscando Añadir/Quitar software en el cajón de aplicaciones) y activamos el soporte AUR en Preferencias > Terceros > Activar soporte de AUR.

Instalación gestor dualboot¶

El sistema Arch ya está listo y podemos arrancarlo encendiendo la consola en modo Boot Manager (manteniendo pulsada la tecla de bajar volumen) y seleccionando la opción Arch. Pero para facilitar el arranque de SteamOS, vamos a instalar un gestor de arranque dualboot llamado rEFInd.

Arrancar SteamOS (con Volume- + Power).

Desde una terminal en modo escritorio ejecutar:

1	`cd $HOME && rm -rf $HOME/SteamDeck_rEFInd/ && git clone https://github.com/jlobue10/SteamDeck_rEFInd && cd SteamDeck_rEFInd && chmod +x install-GUI.sh && ./install-GUI.sh`

Descargar o crear un icono de Arch Linux de 128x128px.
Abrir el lanzador del escritorio que encontraremos en el escritorio.
Configurar de la siguiente forma (seleccionar en el campo Boot Option #2 Icon el icono descargado o creado anteriormente):
Pulsar botón Create Config.
Editar el fichero que encontraremos en ~/.local/SteamDeck_rEFInd/GUI/refind.conf y modificar la última entrada de la siguiente forma:
12345
menuentry "Arch" { icon /EFI/refind/os_icon2.png loader /EFI/Arch/grubx64.efi graphics on}
Pulsar el botón Install rEFInd.
Pulsar el botón Install Config

La ruta /EFI/Arch/grubx64.efi del paso 6 puede cambiar si en el comando grub-install ejecutado durante la instalación del sistema base se eligió otro identificador que no fuera Arch. En ese caso habría que adaptar la ruta.

Conclusión¶

Y esto sería todo. Ahora tenemos un sistema Arch Linux en nuestra Steam Deck con un gestor de arranque dualboot que nos permite arrancar también SteamOS. A partir de aquí tendremos una máquina con una naturaleza doble, una (SteamOS) para jugar y otra (Arch) para ser utilizada como un PC (Plasma) o tabletPC (Plasma Mobile).

Para elegir el entorno gráfico Plasma normal o el Plasma Mobile, utilizaremos el menú desplegable que aparece abajo a la izquierda en el gestor de inicios de sesión SDDM.

Algunos enlaces de interés consultados durante la elaboración de esta guía:

Installing Arch Linux on Steam Deck

Wed, 04 Sep 2024 15:30:00 +0200

Loss of dual boot after updating SteamOS

In the update of SteamOS to the 3.6 branch (specifically, the first stable version of that branch was 3.6.19), the dual-boot configuration was lost, so the machine would only boot into SteamOS. The solution was to follow the steps in Dual Boot manager installation starting from step 4.

In July 2024, the 512GB LCD model of the Steam Deck was available for under €400 for a few weeks. This price was very appealing for a decent machine with an AMD processor based on x86 (AMD64) architecture, 16GB of RAM, an NVMe SSD of the mentioned capacity, a touchscreen, and integrated gaming controls. Essentially, it's a handheld PC, but still a PC. What makes this machine especially attractive to me is its full Linux support, making it an ideal platform for tinkering with Linux distributions or using it as a secondary portable PC. Of course, this is in addition to its conventional use for gaming and emulating video games.

SteamOS, the default operating system, is based on Arch Linux, and in desktop mode, it can be used almost like a regular Arch Linux system. The main restriction is that it's built in immutable mode. While this type of system configuration has its virtues and it's understandable why Valve chose it for their machine, I still prefer a normal (mutable) system. So, I decided to install a regular Arch Linux and learn how to install this distribution. According to the Arch wiki, the hardware of the Steam Deck LCD model is 100% supported by Arch.

The following is the complete procedure I used.

Keyboard/Mouse¶

Although most operations can be performed using the Steam Deck's touchscreen and trackpads, it's highly recommended to connect a keyboard and mouse to the console to facilitate the installation, especially during the terminal session where we'll install the base system. The Steam Deck only has one USB-C port, so the most practical solution is to use a dock. It may also suffice (especially if we run live systems from a microSD) to use a wireless keyboard/mouse dongle connected with a USB<->USB-C adapter, though in that case, it's advisable to ensure the Steam Deck is fully charged.

In my case, I used a Dell DA310z dock.

Disk repartitioning¶

The Steam Deck's SSD I purchased is 512GB and of the NVMe type. This is the minimum size if we want to install another system alongside SteamOS.

Before starting the installation, we need to make space by shrinking the main partition (number 8). For this, we can use almost any live Linux distribution that we boot from a removable drive (USB or microSD) since all of them come with some partition management program. I used a gparted ISO.

The complete procedure can be seen below:

Download the gparted ISO. Specifically, I used this version.
Install the ISO on a USB drive or, even better, on a microSD (since the Steam Deck has a slot for these). You can use a program like Balena Etcher or the dd command in Linux if you know how to use it.
Boot the Steam Deck with the USB drive or microSD inserted by holding down the volume- button until you hear the power-up tones. This causes the console to boot into the Boot Manager menu.
Select the option to boot from the removable device, which will appear in the menu as EFI USB Device (USB) or EFI SD/MMC Card (XX XXXX XXXX) depending on whether you used a USB drive or a microSD respectively.
A configuration screen appears where we make the following selections:
- Policy for handling keymaps => Don't touch keymap
- Which language do you prefer? => 25
- Which mode do you prefer? => 0
After accepting the last option, the gparted program will start in graphical mode (with the screen rotated, though). We will make changes until the partitions look like the screenshot. Essentially, we'll shrink partition #8 by about 100GB, create #9 with 4GB for swap, and #10 with the remaining space for the Arch root system:

Note, when looking at the partitions used by SteamOS, that it uses an A/B partition system, common in Android, where most of the system partitions (except the user space one) are duplicated. This system is designed to facilitate updates, or rather to roll back in case of problems during them.

Base installation¶

For the base system installation, I opted for the conventional method following the instructions in the installation guide on the Arch wiki. This installation uses an Arch system ISO that we can boot from a removable drive (USB or microSD) to install the basic packages needed for a bootable and very basic system.

Before starting, note that due to the dynamic nature of the Arch Linux distribution, it's very likely that this guide will become outdated soon. Therefore, I recommend checking the official guide if something doesn't go as expected.

Below is the step-by-step installation process:

Download the Arch Linux ISO. Specifically, I used this version.
Install the ISO on a USB drive or, even better, on a microSD to use the slot on the Steam Deck. You can use a program like Balena Etcher or the dd command in Linux if you know how to use it.
Boot the Steam Deck with the USB drive or microSD inserted by holding down the volume- button until you hear the power-up tones. This causes the console to boot into the Boot Manager menu.
Select the option to boot from the removable device, which will appear in the menu as EFI USB Device (USB) or EFI SD/MMC Card (XX XXXX XXXX) depending on whether you used a USB drive or a microSD respectively.

Once the Arch live installation system finishes booting, run the following commands in order (in the iwctl session, replace <SSID> with your own and enter the password when prompted; also replace the user identifier <USER> with the one you want to use):

 1 2 3 4 5 6 7 8 910111213141516171819202122232425262728293031323334

# loadkeys en# iwctl[iwd]# station wlan0 scan[iwd]# station wlan0 get-networks[iwd]# station wlan0 connect <SSID>[iwd]# exit# mkfs.ext4 /dev/nvme0n1p10# mkswap /dev/nvme0n1p9# mount /dev/nvme0n1p10 /mnt# mount --mkdir /dev/nvme0n1p1 /mnt/boot/efi# swapon /dev/nvme0n1p9# pacstrap -K /mnt base base-devel linux linux-firmware sudo vi ntfs-3g networkmanager amd-ucode grub efibootmgr git cmake qt5-wayland# genfstab -U /mnt >> /mnt/etc/fstab# arch-chroot /mnt# ln -sf /usr/share/zoneinfo/Europe/Madrid /etc/localtime# hwclock --systohc# vi /etc/locale.gen # uncomment 'en_US.UTF-8 UTF-8'# locale-gen# echo "LANG=en_US.UTF-8" > /etc/locale.conf# echo "KEYMAP=en" > /etc/vconsole.conf# echo "deck" > /etc/hostname# echo -e "\n127.0.0.1 localhost\n::1 localhost\n127.0.1.1 deck" >> /etc/hosts# passwd# grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=Arch# grub-mkconfig -o /boot/grub/grub.cfg# systemctl enable NetworkManager# useradd -m -G wheel,audio,video,storage <USER># passwd <USER># chmod u+w /etc/sudoers# vi /etc/sudoers # Uncomment '%wheel ALL=(ALL) ALL'# chmod u-w /etc/sudoers# pacman -Syy# pacman -S xorg-server xf86-video-amdgpu maliit-keyboard qt5-wayland# su - <USER>

The password you choose when running the passwd <USER> command should be numeric if you want to use Plasma Mobile, as the unlock screen only allows you to enter a PIN.

Graphical environment installation¶

Continuing from where we left off, that is, in the chroot session from the Arch Linux live installation system. We will now do this as a normal user (not root), so from now on, we will frequently use sudo.

Now we are going to install the graphical environments. I say this in plural because we will install two: Plasma and Plasma Mobile. I do this because, depending on whether we will use the Steam Deck with Arch in desktop mode (with keyboard/mouse and possibly a screen) or portable mode (without keyboard/mouse), one system or the other will be more convenient, as Plasma Mobile has an interface designed to be operated with a touchscreen (tablet-style).

Really, it's not necessary to install both desktops, so their installation steps are separated. You can install one, the other, or both.

Plasma¶

1	`$ sudo pacman -S plasma-meta`

During the installation of the above package, you will be asked several questions. On the third question, answer 2) noto-fonts. For the rest, provide the default answer (by pressing enter).

Plasma Mobile¶

Plasma Mobile is not yet available in the official repositories. We have to use AUR:

Start by installing some dependencies:

1	`$ sudo pacman -S plasma-workspace kcontacts kirigami2 kpeople libphonenumber`

Install the AUR packages plasma-nano, plasma-settings, and plasma-mobile in this order:

 1 2 3 4 5 6 7 8 9101112

$ cd ~$ git clone https://aur.archlinux.org/plasma-nano.git$ cd plasma-nano$ makepkg -si$ cd ~$ git clone https://aur.archlinux.org/plasma-settings.git$ cd plasma-settings$ makepkg -si$ cd ~$ git clone https://aur.archlinux.org/plasma-mobile.git$ cd plasma-mobile$ makepkg -si

End of graphical environment installation¶

Install the SDDM session manager and some applications, which we'll need to finish the installation from the graphical mode:

123	`$ sudo pacman -S sddm konsole dolphin kwrite partitionmanager power-profiles-daemon$ sudo systemctl enable sddm$ exit`

Close the chroot session, unmount the partitions, and reboot the system:
123
# exit# umount -R /mnt# reboot

Basic configuration¶

After rebooting, you should see the SDDM session manager, initially with the screen rotated and without the ability to use the on-screen keyboard, so we'll still be using the external keyboard and mouse.

Once we have logged into Plasma or Plasma Mobile, the first thing we need to do is configure the internet connection. To do this, click on the corresponding icon in the system tray at the bottom right in Plasma or at the top right in Plasma Mobile.

Once connected, open the Konsole application and run the following commands to install the basic KDE application package, Firefox browser and the SSH server:

123	`$ sudo pacman -S firefox kde-applications-meta openssh usbutils lshw man-db htop spectacle$ sudo systemctl start sshd$ sudo systemctl enable sshd`

Finally, we make the following configurations:

Preferences > System Preferences > Input & Output > Display & Monitor > Scale: Set the screen scale to 110%.
Preferences > System Preferences > Input & Output > Keyboard > Layouts > Configure Layouts > Add: Add the English keyboard layout.
Preferences > System Preferences > Input & Output > Keyboard > Virtual Keyboard: Select Maliit.
Preferences > System Preferences > Language & Time > Date & Time > Time Zone: Select your city.
Preferences > System Preferences > Appearance & Style > Text & Fonts > Fonts. Set this values:
- General: Noto Sans 11pt
- Fixed width: Hack 10pt
- Small: Noto Sans 9pt
- Toolbar: Noto Sans 11pt
- Menu: Noto Sans 11pt
- Window title: Noto Sans 10pt
Right-click (L2) on the taskbar and select Show panel settings. In Panel Preferences > Panel Height increase the height to 54px.
Right-click (L2) on the icon used to show hidden icons in the system tray and select Configure System Tray. In General select these values:
- Panel icon size: Scale to panel height
- Spacing between panel icons: Normal
Right-click (L2) on the icon used to show hidden icons in the system tray and select Show panel settings. You will see a small clock that was not visible before, right-click (L2) on it. Select Show alternatives and from the alternative graphics that appear, choose Digital clock.

SDDM configuration¶

Finally, we'll improve the SDDM session manager configuration to enable the on-screen keyboard, enhance the appearance, and display the screen in the correct orientation:

Create the file /etc/sddm.conf.d/10-wayland.conf with the following content:

[General]DisplayServer=waylandGreeterEnvironment=QT_WAYLAND_SHELL_INTEGRATION=layer-shell[Wayland]CompositorCommand=kwin_wayland --drm --no-lockscreen --no-global-shortcuts --locale1 --inputmethod maliit-keyboard

Open Preferences > Login Screen (SDDM), select Breeze as the theme, and click the Apply Plasma settings... button in the top right corner.

Sound configuration¶

As the Arch wiki mentions, the default volume on the Steam Deck is very low. To fix this, you need to install the alsa-utils package and run the alsamixer command to adjust the volume of some of the channels.

12	`$ sudo pacman -S alsa-utils$ alsamixer`

To access them, once in alsamixer, press F6 to select the acp5x audio device, as by default the selected device is 0, which is associated with the HDMI output of the graphics chip:

Once the correct device is selected, you will see all its channels, which are quite numerous. Locate the ones mentioned in the wiki and adjust them to the following values:

Channel	Value
Analog PCM	85%
Digital	86%
Digital PCM	85%
Left Analog PCM	85%
Left Digital PCM	85%
Right Analog PCM	85%
Right Digital PCM	85%

Pamac Installation¶

To facilitate package installation from the graphical interface, we are going to install pamac:

1	`$ yay -S pamac-aur`

Once installed, open it (by searching for Add/Remove Software in the application drawer) and enable AUR support in Preferences > Third Party > Enable AUR support.

Dual Boot manager installation¶

The Arch system is now ready and can be booted by starting the console in Boot Manager mode (holding down the volume- key) and selecting the Arch option. But to make it easier to boot SteamOS, we'll install a dual boot manager called rEFInd.

Boot SteamOS (with Volume- + Power).

From a terminal in desktop mode, run:

1	`cd $HOME && rm -rf $HOME/SteamDeck_rEFInd/ && git clone https://github.com/jlobue10/SteamDeck_rEFInd && cd SteamDeck_rEFInd && chmod +x install-GUI.sh && ./install-GUI.sh`

Download or create an Arch Linux icon of 128x128px.
Open the desktop launcher found on the desktop.
Configure it as follows (select the icon downloaded or created earlier in the Boot Option #2 Icon field):
Click the Create Config button.
Edit the file found at ~/.local/SteamDeck_rEFInd/GUI/refind.conf and modify the last entry as follows:
12345
menuentry "Arch" { icon /EFI/refind/os_icon2.png loader /EFI/Arch/grubx64.efi graphics on}
Click the Install rEFInd button.
Click the Install Config button.

The path /EFI/Arch/grubx64.efi in step 6 may change if you chose a different identifier than Arch during the grub-install command executed during the base system installation. In that case, you'll need to adapt the path.

Conclusion¶

And that's it. Now we have an Arch Linux system on our Steam Deck with a dual boot manager that allows us to boot into SteamOS as well. From here, we have a machine with a dual nature, one (SteamOS) for gaming and another (Arch) to be used as a PC (Plasma) or tablet PC (Plasma Mobile).

To choose between the normal Plasma or Plasma Mobile graphical environment, use the dropdown menu that appears at the bottom left in the SDDM login manager.

Some interesting links consulted during the creation of this guide: