Zeltro › Ejecuta varios proyectos en local sin conflictos de puertos
Una docena de proyectos en local sin conflictos de puertos
Cada proyecto quiere el puerto 3000, cada archivo compose quiere el 3306, y nada puede hablar con nada. Este es el planteamiento que elimina el problema en lugar de gestionarlo: servicios compartidos y una dirección asignada a cada proyecto, para que nunca tengas que elegir una.
El problema llega más o menos con el quinto proyecto. Cada framework quiere el puerto
3000 o el 8000. Cada docker-compose.yaml que clonas quiere ocupar el 3306 o el 5432.
Empiezas a apuntar qué proyecto está en qué puerto, y luego necesitas que dos proyectos
hablen entre sí y descubres host.docker.internal.
Todo eso se puede gestionar. Pero también se puede evitar: no memorizando una lista de puertos mejor, sino no eligiendo nunca ninguno.
El planteamiento#
Cada proyecto recibe su propia dirección en una red privada de Docker, asignada al crear el proyecto. Nunca la eliges, y dos proyectos no pueden chocar:
LOCAL http://10.247.177.168 # from this machine
LAN http://192.168.1.6:168 # from anything else on the network
zeltro status muestra las dos para cada proyecto. La dirección local es la IP del
propio contenedor, así que no lleva ningún puerto; la dirección de red local es la IP de
este equipo más el puerto publicado del proyecto, para llegar a él desde tu teléfono u
otro portátil.
Por debajo, todos los proyectos del equipo comparten un mismo conjunto de servicios:
| Servicio | Contenedor | Accesible desde un proyecto como |
|---|---|---|
| MariaDB | zeltro-mariadb |
zeltro-mariadb:3306 |
| Postgres | zeltro-postgres |
zeltro-postgres:5432 |
| Redis | zeltro-redis |
zeltro-redis:6379 |
| MongoDB | zeltro-mongo |
zeltro-mongo:27017 |
| Memcached | zeltro-memcached |
zeltro-memcached:11211 |
Diez proyectos, uno de cada. Siete contenedores de Postgres duplicados que consumen unos 700 MB pasan a ser uno que consume unos 100.
Qué resuelve#
La ruleta de puertosNada que recordar, nada que asignar, ningún choque cuando dos proyectos usan el 3000 por defecto. La asignación es problema de Zeltro, no tuyo.
Trabajo entre proyectosTodos los proyectos están en la misma red de Docker y se puede llegar a ellos por nombre, así que fetch('http://client-api/') desde dentro de otro proyecto funciona sin configurar nada de red. Que una app de Laravel lea la base de datos de un proyecto de Django es una cadena de conexión, no un ejercicio.
Repositorios clonados que te dan guerraUn archivo compose original que ocupa 5432:5432 o 80:80 se reconecta a los servicios compartidos durante la configuración, y el original se conserva como docker-compose.upstream.yaml.
La carga del equipoUn proceso de base de datos por motor en lugar de uno por proyecto, que es la diferencia entre un portátil que aguanta todo tu trabajo y uno que no.
Cómo se hace#
zeltro new laravel barber-shop # scaffold, wire up, start
zeltro setup existing-project # adapt a project you already have
zeltro up barber-shop # start it
zeltro status # what is running, and its two addresses
Las direcciones se asignan y se muestran por ti. No se escribe nada en /etc/hosts, y
Zeltro nunca pide sudo para gestionar un proyecto.
Servicios compartidos significa versiones compartidas: una sola versión mayor de Postgres para todo. La mayoría de los proyectos ni lo notan. Si dos necesitan de verdad versiones mayores distintas, ese es el único caso en el que las herramientas por proyecto como DDEV o Lando siguen ganando, y es la concesión que este diseño hace a propósito.
Por qué esto importa más con un agente de IA#
Un agente que trabaja en una carpeta no tiene ni idea de qué más hay en el equipo. Si lo
dejas solo, elegirá un puerto, añadirá un contenedor de base de datos al archivo compose
y chocará en silencio con algo que tenías en marcha. Un entorno fijo (direcciones
asignadas, servicios conocidos, un AGENTS.md escrito) es lo que evita que eso pase, y
es buena parte del motivo por el que Zeltro está organizado así.
Como los proyectos comparten una red, sus agentes también pueden coordinarse. Cuando un proyecto cambia su API, su agente puede avisar a los agentes de los proyectos que dependen de él.
Preguntas
¿Tengo que elegir un puerto para algo?
No. A cada proyecto se le asigna una IP de contenedor y un puerto publicado al crearlo.
zeltro status muestra la dirección local y la dirección de red local de cada uno.
¿Qué diferencia hay entre las dos direcciones?
La local es la IP del propio contenedor en la red de Docker, sin puerto, porque no hay nada más en esa dirección. La de red local es la IP de tu equipo más el puerto publicado del proyecto, que es por donde tiene que pasar cualquier otro dispositivo.
En macOS y Windows, Docker mantiene los contenedores dentro de una máquina virtual y la
IP del contenedor no es accesible desde el equipo, así que la dirección local es
http://localhost:<port>. Zeltro lo detecta y muestra la dirección que de verdad
funciona.
¿Los proyectos pueden encontrarse por nombre?
Sí, desde dentro de los contenedores. Todos los proyectos se unen a la misma red de Docker, y el DNS integrado de Docker resuelve en ella los nombres de proyectos y servicios. Eso es lo que hace sencillas las llamadas entre proyectos y las bases de datos compartidas.
Tu navegador no está en esa red, por eso usa la dirección de arriba en lugar de un nombre.
¿Y si dos proyectos necesitan versiones distintas de Postgres?
No pueden tenerlas: una única instancia compartida es la concesión. Si es un requisito ineludible, usa herramientas por proyecto para esos proyectos, o deja el caso aparte en su propia infraestructura.
¿Funciona con un proyecto que tiene su propio docker-compose.yaml?
Sí. Los servicios de base de datos incluidos se eliminan y la app se redirige a los
compartidos, con las credenciales escritas en .env. El archivo original se conserva
como docker-compose.upstream.yaml.
¿Y las bases de datos en sí? ¿Los proyectos ven los datos de los demás?
Comparten el servidor, no la base de datos. Cada proyecto tiene su propia base de datos y sus propias credenciales. El acceso entre proyectos es posible a propósito, y eso es lo que facilita montar algo parecido a microservicios, pero nada se comparte por accidente.
Prueba Zeltro en tu propio equipo
Gratis para uso personal y sin cuenta. Crea con la IA que ya pagas y quédate con la app, sus datos y su código en tu propio equipo.
Instalar Zeltro Por qué traer tu propia clave
¿Prefieres no configurarlo tú? Lo hago yo por ti.
Revisado el 2026-08-22. Los otros productos cambian a menudo: si algo aquí está desactualizado, avísanos y lo corregimos.