Procesos

La pestaña Procesos (P) ejecuta el proyecto desde Joppa: sus servidores de desarrollo (scripts dev de package.json, targets de Nx, servidor PHP) y su infraestructura (servicios Docker Compose). Cada proceso tiene su estado, su puerto y sus logs.

Analizar el proyecto

La primera vez, haz clic en Analizar el proyecto, en la parte superior de la página del proyecto (junto a Abrir) o en la pestaña. Mientras no se haga el análisis, Joppa no inicia nada: los dominios siguen sin conexión hasta que inicies el servidor. Joppa lee package.json, los workspaces y el archivo Docker Compose, y luego muestra Lo que Joppa entendió del proyecto. Nada arranca antes de que confirmes.

Columna	Contenido
En «Iniciar todo»	Desmarca un proceso para que no arranque con los demás; se puede seguir iniciando por separado
Proceso	Su nombre: web, api, postgres
Comando	bun run dev, o el servicio de Compose
Puerto	Editable
De dónde viene el puerto	script, config, código, .env, compose o por defecto
Listo cuando	Para un servidor de desarrollo con puerto: la ruta HTTP que Joppa pide para saber que está listo (/ por defecto), o tcp

La línea «espera a …» indica las dependencias: un servidor de desarrollo espera a que estén listos los contenedores de Compose de los que depende.

+ acción, bajo el comando de un servidor de desarrollo, le añade acciones.

Cómo se encuentra el puerto

En este orden:

1. una variable con valor por defecto en el script (${PORT:-3000}): Joppa la rellena;
2. --port, -p o PORT= en el script;
3. port: en la configuración del framework (vite.config, astro.config), también en una sola línea (server: { port: 5400 }), u options.port de un target de Nx;
4. PORT en el .env;
5. el puerto por defecto del framework: Vite y VitePress 5173, Astro 4321, Next.js, Nuxt, Create React App y Docusaurus 3000, Angular 4200, Wrangler 8787, Vue CLI 8080, Gatsby 8000, Storybook 6006, Expo 8081.

Para otro servidor Node, Joppa busca el puerto en el código (.listen(3000), process.env.PORT ?? 3000).

El gestor de paquetes sale del lockfile; si no, del campo packageManager; si no, npm.

El script de cada paquete

Joppa toma el script dev del paquete; si no lo hay, develop, serve, o un start que inicia un servidor de desarrollo (react-scripts start, ng serve, expo start…). Un start de producción (node dist/server.js) se ignora.

El servidor PHP

Proyecto	Indicio	Comando
Laravel	archivo artisan	php artisan serve --host=127.0.0.1 --port=${SERVER_PORT:-8000}
Symfony, otro PHP	public/index.php y composer.json	php -S 127.0.0.1:${PORT:-8000} -t public

El puerto sale de SERVER_PORT (Laravel) o de PORT en el .env; si no, 8000. El php es el de la versión fijada.

Los workers de Laravel

Junto a php artisan serve, Joppa propone los procesos en segundo plano que usa la aplicación, leídos de composer.json, el .env y el código:

Proceso	Cuándo	Comando	Marcado
queue	QUEUE_CONNECTION no es sync (Laravel 11 y posteriores: database por defecto)	php artisan queue:work, o el de composer run dev (queue:listen --tries=1 en los kits de inicio, que vuelve a leer el código en cada job)	sí; se propone desmarcado con sync
horizon	laravel/horizon está instalado	php artisan horizon, en lugar de queue cuando la cola pasa por Redis	si QUEUE_CONNECTION=redis
scheduler	siempre	php artisan schedule:work	si la aplicación programa una tarea (Schedule:: en routes/console.php, $schedule-> en el Kernel)
reverb	laravel/reverb está instalado	php artisan reverb:start --host=127.0.0.1 --port=${REVERB_SERVER_PORT:-8080}	si BROADCAST_CONNECTION=reverb
pail	laravel/pail está instalado	php artisan pail --timeout=0	no: Joppa ya muestra los logs

Son procesos sin puerto, salvo Reverb: su puerto sale de REVERB_SERVER_PORT en el .env; si no, 8080, y Joppa fija la variable para que un worktree lo cambie. Un proceso desmarcado sigue en la lista y se inicia a mano.

Los monorepos

Joppa encuentra los paquetes allí donde el repositorio los declara:

Archivo	Forma
package.json	workspaces (npm, yarn, bun), como lista o { "packages": [...] }
pnpm-workspace.yaml	packages:
lerna.json	packages (por defecto packages/*)
nx.json	cada project.json del repositorio, sus targets serve / dev y los que deducen los plugins de Nx (@nx/vite/plugin, @nx/next/plugin)

Se entienden los patrones apps/*, packages/** (a cualquier profundidad) y las exclusiones !packages/legacy; node_modules, dist y las carpetas ocultas se ignoran. Un target de Nx se inicia con nx run <proyecto>:<target>.

El script dev de la raíz indica qué tarea iniciar en cada paquete y en cuáles:

Script raíz	Tarea	Paquetes
turbo dev, turbo run dev, turbo watch dev	dev	todos los que la tienen
turbo run start:dev --filter=web...	start:dev	web
nx run-many -t serve -p shop admin	serve	shop, admin
nx serve shop, nx run shop:serve	serve	shop
pnpm -r --parallel dev, pnpm --filter ./apps/* dev	dev	todos / los de apps/
bun run --filter '@acme/*' dev	dev	los del scope @acme
npm run dev -w apps/web -w apps/api	dev	web, api

Un filtro designa un paquete por su nombre, su carpeta o un patrón (apps/*, @acme/*); se entienden ..., ^, {…} y las exclusiones !docs de Turborepo. Un paquete que no está en el dev raíz queda desmarcado, salvo si un dominio apunta a él.

Cuando el script dev de la raíz inicia varias apps a la vez, Joppa propone:

• Iniciarlos por separado · un estado y unos logs por app (recomendado);
• Tal cual: el comando raíz, en una sola terminal.

Guardar: en tu máquina o para el equipo

• Guardar conserva la configuración en Joppa, en esta máquina.
• Marca Escribir joppa.toml en el repositorio para el equipo para compartirla: se escribe en un archivo joppa.toml en la raíz del proyecto, para hacer commit. Cuando este archivo existe, es el que manda. Consulta la referencia de joppa.toml. Para compartir también los dominios, los servicios, la base de datos y las versiones, usa el enlace Compartir la configuración en joppa.toml bajo la lista de procesos.

Guardar e iniciar lo arranca todo enseguida.

Iniciar y detener

• ▶ Iniciar todo / ■ Detener todo en la parte superior de la página del proyecto, o desde la paleta ⌘ K («Iniciar todo: miproyecto»). En cuanto un proceso está en marcha, el botón pasa a ■ Detener todo.
• Cada proceso se inicia, se detiene o se reinicia por separado, en la pestaña o desde la paleta.

Los procesos se agrupan en Aplicaciones (scripts «dev») e Infraestructura (Docker Compose, iniciado con docker compose up -d --wait: Joppa espera los healthchecks). La cabecera indica el orden de inicio y cuántos están en marcha. Cada grupo tiene su propio botón ▶ Iniciar todo / ■ Detener todo, que solo actúa sobre sus procesos: iniciar la infraestructura sin las aplicaciones, por ejemplo. Como el del proyecto, deja fuera los procesos desmarcados de «Iniciar todo».

Estado	Significado
detenido	—
deteniendo	Se pidió detenerlo, el proceso aún no ha salido
en espera	Espera a un proceso del que depende
iniciando	Iniciado, aún no responde (ver Cuándo está listo un proceso)
en marcha	Iniciado (proceso sin puerto)
en línea	Responde a una petición HTTP en su puerto
error	Se detuvo con un error
iniciado fuera de Joppa	El puerto ya lo sirve un proceso que Joppa no inició
sin Docker	Servicio de Compose, pero no hay ningún runtime en marcha
en reposo	Detenido por Joppa por falta de peticiones: la próxima lo despierta (ver Reposo sin peticiones)

El contador ▶ 6/7 junto al proyecto, en la barra lateral y en su tarjeta de la página Proyectos, indica cuántos procesos de « Iniciar todo » están en marcha; la barra de estado de la parte inferior de la ventana suma todos los proyectos (6/7 procesos). El color del ▶: verde cuando todo funciona, naranja cuando algunos están detenidos, arrancando o iniciados fuera de Joppa, rojo solo cuando alguno ha fallado. Pasa el ratón por el contador para ver el detalle. Una z azul sustituye al ▶ cuando los servidores de desarrollo del proyecto están en reposo.

Si otro programa ocupa el puerto, Joppa te lo dice y propone Liberar el puerto.

La detención envía SIGTERM y luego SIGKILL pasados 6 segundos, a todo lo que inició el script. Un servidor de desarrollo que sigue en marcha cuando termina el script que lo inició sigue bajo Joppa: conserva su registro, su estado y su botón de detener.

Desde la terminal: joppa procs, joppa start|stop|restart <proyecto> [proceso] y joppa logs <proyecto> [proceso] (ver El comando joppa). Un asistente como Claude Code o Cursor hace lo mismo con las herramientas list_processes, start_process, restart_process, process_logs y run_process_action del servidor MCP.

Iniciar al abrir Joppa

El interruptor Iniciar al abrir Joppa hace un «Iniciar todo» del proyecto cada vez que se abre Joppa. Es una preferencia de tu máquina: nunca se escribe en joppa.toml.

Si un joppa.toml llega con git pull con comandos modificados, Joppa no los ejecuta por su cuenta: una notificación indica que el proyecto no se ha iniciado. Revisa los comandos y pulsa Iniciar todo: el inicio al abrir Joppa vuelve a funcionar como siempre.

Reiniciar tras un fallo

El ajuste Reiniciar tras un fallo elige cuántas veces reinicia Joppa un servidor de desarrollo que falla: nunca, 1, 2, 3 (por defecto), 5 o 10 veces.

• La espera se duplica entre dos reinicios: 1 s, 2 s, 4 s, 8 s… hasta 30 s.
• El contador vuelve a cero tras 60 segundos de funcionamiento estable.
• Más allá, Joppa se rinde y lo indica: «volvió a fallar tras 3 reinicios: Joppa se rinde.»
• Una detención que pidas tú cancela un reinicio pendiente.

Este ajuste solo afecta a los servidores de desarrollo (no a los contenedores de Compose) y es propio de tu máquina.

Reparar un proceso con error

Cuando un proceso se detiene definitivamente (Joppa ha abandonado tras sus reinicios, o el reinicio está desactivado), aparece un aviso rojo en la parte superior de la página del proyecto, sea cual sea la pestaña abierta: el proceso, por qué se detuvo y las últimas líneas que escribió.

• Reparar lo vuelve a iniciar, con los que necesita, sin tocar los demás procesos.
• Abrir el terminal muestra todo su registro.
• Ignorar oculta el aviso hasta el siguiente fallo.

Cuándo está listo un proceso

Un servidor de desarrollo con puerto está en línea cuando responde a una petición HTTP, no solo cuando su puerto acepta conexiones: Joppa pide GET / en su puerto, y cualquier respuesta cuenta, incluso un 404 o un 500. El terminal anota el momento: «listo en 1.2 s (GET / → 200)». Los procesos que lo esperan («espera a …», dependsOn) solo arrancan después.

La columna Listo cuando del análisis (el campo probe de joppa.toml) cambia lo que Joppa pide:

Valor	Listo cuando
(vacío)	GET / recibe una respuesta
/health, /up…	Esa ruta recibe una respuesta
tcp	El puerto acepta conexiones

Si el puerto acepta conexiones pero no llega ninguna respuesta HTTP durante 30 segundos, o responde con otro protocolo, Joppa lo considera listo de todos modos. Una vez listo, Joppa no vuelve a preguntar: solo comprueba que el puerto sigue respondiendo. Los servicios de Docker Compose están listos cuando su healthcheck pasa, o cuando su puerto responde si no tienen.

Reposo sin peticiones

Con muchos worktrees abiertos, cada uno con sus servidores de desarrollo, la memoria se agota rápido. Joppa pone en reposo los servidores de desarrollo de un proyecto que nadie usa: tras 15 minutos sin peticiones a sus dominios, los detiene y los marca en reposo.

La siguiente petición a uno de sus dominios los despierta:

1. el proxy retiene la petición;
2. Joppa vuelve a iniciar los servidores de desarrollo en reposo, con los que necesitan;
3. en cuanto el servidor del dominio está listo, la petición le llega.

Una página que tendría que esperar más de 3 segundos muestra «Despertando web…», que se recarga sola cada segundo hasta que el servidor responde. Las demás peticiones (fetch, archivos, WebSocket del HMR) esperan hasta 90 segundos. El HMR de Vite se reconecta solo tras despertar.

El interruptor Poner en reposo tras … sin peticiones de la pestaña Procesos ajusta el tiempo (de 5 min a 2 h) o desactiva el reposo, proyecto por proyecto. Está activado por defecto para los entornos de worktrees y desactivado para los demás proyectos. Es una preferencia de tu máquina, nunca se escribe en joppa.toml.

• Solo los servidores de desarrollo entran en reposo: los contenedores de Docker Compose y los servicios de Joppa siguen en marcha.
• Joppa no pone en reposo un proyecto mientras uno de sus procesos arranca, se reinicia o ejecuta una acción, ni un proyecto cuyos dominios no llevan a ningún servidor de desarrollo (ninguna petición podría despertarlo), ni con el proxy detenido.
• Una pestaña abierta sin actividad no impide el reposo: al volver a ella, el cliente HMR se reconecta y despierta el servidor.
• ▶ también despierta un proceso en reposo; ■ Detener todo lo saca del reposo: una petición ya no lo inicia.

El estado en reposo aparece en la pestaña, en la columna de estado de los dominios, en el terminal y en el contador del proyecto (una z azul, y «4 en reposo» en la barra de estado). La herramienta MCP list_processes lo devuelve como asleep.

Acciones

Una acción es un comando puntual asociado a un proceso: migrate → php artisan migrate, seed → php artisan db:seed, test → bun test. Se lanza con un clic, junto al nombre del proceso en la pestaña Procesos o en la barra del terminal abierto en ese proceso. Su salida va al terminal del proceso, entre «▶ migrate $ php artisan migrate» y «migrate: terminado» (o «migrate: error (código 1)»).

• Se ejecuta en la carpeta del proceso, con sus variables de entorno, esté el proceso en marcha o no.
• Un segundo clic mientras se ejecuta la detiene.
• Una misma acción solo se ejecuta una vez a la vez.

Las acciones se declaran en el análisis (Revisar el análisis): + acción bajo el comando de un servidor de desarrollo, y luego un nombre y un comando. Joppa sugiere migrate, seed y test para Laravel, test y lint para un proyecto JavaScript. Se escriben en joppa.toml cuando el proyecto tiene uno. Un asistente las lanza con la herramienta run_process_action del servidor MCP.

La terminal integrada

⌘ J abre la terminal en la parte inferior de la ventana, desde cualquier pantalla. Plegada, muestra un cuadrado de estado por proceso; abierta, una pestaña Todos y luego una pestaña por proceso.

• ⌕ filtrar: muestra solo las líneas que contienen un texto.
• ● seguir: se queda pegada a las últimas líneas.
• Borrar, Ampliar / Reducir.
• Redimensionar: arrastra el borde superior (o ↑ / ↓ con el teclado); un doble clic restablece la altura por defecto. Joppa recuerda la última altura.

Joppa conserva las últimas 5000 líneas de cada proceso. En caso de error, la terminal propone la acción útil: Liberar el puerto o Reiniciar.