DEV Community: Juan Torchia

The /actuator/env Sanitizer Doesn't Know Your Naming Conventions

Juan Torchia — Fri, 11 Sep 2026 12:00:20 +0000

I recently wrote about allowlisting actuator endpoints: what to expose and what not to. One question stayed open and kept nagging at me: if you decide to leave /actuator/env enabled — because you need it for debugging in staging, because infra is asking for it — what actually guarantees you won't show a secret in plain text the first time someone hits it with curl?

Short answer: nothing, if you blindly trust the default sanitizer.

The problem with actuator env show values

Spring Boot ships with a sanitizer that automatically masks certain values before showing them in /actuator/env. It works by property name: if the key contains password, secret, key, token or credentials, the value comes out as ******. It's a reasonable defense for the generic case.

The problem is exactly that: it's generic. It covers the words some Spring developer imagined you'd use. It doesn't cover the ones your team actually uses.

Think about how environment variables get named in a real project: DB_PASS instead of DB_PASSWORD, API_AUTH instead of API_TOKEN, WEBHOOK_SIGNING, PARTNER_SHARED_VALUE, INTERNAL_CIPHER. None of those contain the keywords the sanitizer looks for. All of them end up in the /actuator/env JSON response without a single asterisk.

My tesis here: the default sanitizer covers the obvious names, but that's not where the real leaks happen. The real leaks happen through the naming convention someone improvised in a sprint under deadline pressure, and nobody circled back to add it to the pattern list. I've seen this exact gap in code review — a variable named PARTNER_SHARED_VALUE sitting in a staging config, fully visible, because nobody thought a shared-secret-style value needed the word "secret" in it to deserve masking.

What the official source says — and what it doesn't

The official Spring Boot Actuator documentation confirms the behavior: the /env endpoint applies sanitization to values before exposing them, and that behavior is configurable through the SanitizingFunction interface, which replaced the keyword-based Sanitizer mechanism in more recent versions of the framework.

What the docs don't say — because it's not their job to say it — is what specific names you're going to use in your project. That's on you to audit. The docs give you the extension mechanism; the catalog of what to sanitize is the responsibility of whoever configures the project, not the framework.

That gap between "mechanism available" and "correct configuration for this case" is exactly where most exposure incidents on default, unreviewed configurations slip through.

Where people get it wrong

The common recipe I see repeated on forums and in inherited configs is: "turn on management.endpoint.env.show-values=when-authorized and you're covered." That solves who can see the values, not what values show up unmasked to whoever has authorization. They're two different problems, and they get treated as one all the time.

The hidden cost shows up when the endpoint stays accessible to an internal role — a monitoring service, an ops dashboard — and that role ends up seeing credentials nobody thought to mask because the variable name didn't match the default pattern.

Typical counterexample: a project that uses Vault or AWS Secrets Manager for production, but leaves variables named something like THIRD_PARTY_SHARED_SECRET_VALUE in application-staging.yml. The default sanitizer doesn't reliably catch SHARED_SECRET_VALUE as a unit if the matching logic is stricter than a plain substring check for "secret" — and in a lot of custom configs it ends up not covering variants with underscores or mixed case if someone overwrote the sanitizer without reviewing the inherited regex.

Here's how to extend the sanitizer with your own pattern, using SanitizingFunction:

// Custom sanitizer configuration for /actuator/env
@Bean
public SanitizingFunction customSanitizingFunction() {
    // Pattern covering the team's own naming conventions
    Pattern patronCustom = Pattern.compile(
        "(?i).*(pass|auth|signing|shared|cipher).*"
    );
    return data -> {
        String nombre = data.getSanitizableData().getKey();
        if (patronCustom.matcher(nombre).matches()) {
            return data.withValue("******");
        }
        // if it doesn't match, let the default sanitizer keep the chain going
        return data;
    };
}

This bean gets added to the existing chain of sanitizers; it doesn't replace it. Spring Boot runs every registered SanitizingFunction in order and applies masking if any of them decides it's warranted.

flowchart LR
  A[Request a /actuator/env] --> B{Sanitizer default}
  B -->|nombre matchea password/secret/token| C[Enmascarado con ******]
  B -->|no matchea| D{SanitizingFunction custom}
  D -->|nombre matchea patron propio| C
  D -->|no matchea nada| E[Valor expuesto en texto plano]

That last path, the one on the right, is the one you have to actively close. It doesn't close itself.

Decision matrix for /actuator/env

Situation	What to check first	What to do
Endpoint exposed only on localhost/debug	Confirm there's no tunneling or proxy exposing it outward	Default sanitizer may be enough, but audit variable names anyway
Endpoint accessible in staging with monitoring roles	What custom variables the team uses, not just Spring's	Add a `SanitizingFunction` with your own pattern before enabling access
Variables with unconventional names (`DB_PASS`, `API_AUTH`)	List every key in `application.yml` and `.env` for each environment	Extend the regex pattern, don't trust the default list
Integrations with external providers (webhooks, partners)	Names the partner defines, not the ones you define	Custom sanitizer by provider prefix or suffix
Deciding whether to disable the whole endpoint	Whether anyone on the team regularly audits property names	Disabling it is safer than an unmaintained sanitizer

That last row is the one I most want to point out: if nobody's periodically reviewing which property names show up in the code, a poorly maintained custom sanitizer gives a false sense of security — arguably worse than no sanitizer at all, because it looks like coverage. The allowlist criterion I laid out in the previous post is preferable to a sanitizer nobody updates.

Common mistakes and gotchas

Confusing authorization with sanitization. show-values=when-authorized controls access, not content. They're independent settings that both need reviewing.
Copying the regex from a previous project without adapting it. Naming conventions change between teams and even between projects within the same team.
Not testing the sanitizer against a negative case. Common gap: nobody writes a test that verifies a "weird"-named variable actually comes out masked.
Thinking this is only a production problem. Staging and shared dev environments also expose /actuator/env, and that's often exactly where real third-party credentials live for integration testing.
Assuming a Spring Boot version bump updates your pattern list for you. It doesn't. The framework maintains its own default keywords; your team's naming conventions are always your own responsibility, version after version.

FAQ

Does Spring Boot's sanitizer mask all sensitive values by default?
No. It masks values whose property name contains specific words like password, secret, key, token or credentials. Any naming convention different from that stays uncovered unless explicitly configured.

What's the difference between Sanitizer and SanitizingFunction?
SanitizingFunction is the recommended interface in recent Spring Boot versions for extending sanitization behavior programmatically, replacing the earlier approach based solely on a fixed keyword list.

Can I have multiple SanitizingFunction instances registered at once?
Yes. Spring Boot runs them in a chain; if any of them decides to mask a value, that value stays masked in the final response.

Is disabling /actuator/env safer than sanitizing it?
Depends on the use case. If the team has no process to keep the custom sanitizer updated, disabling the endpoint or restricting it with a strict allowlist reduces risk with less ongoing maintenance.

Does show-values=when-authorized solve the exposed-secrets problem?
Not by itself. It controls who can see the values, not what values show up unmasked to those authorized users. They're two separate settings that need to be combined.

How do I test that my custom sanitizer works before deploying?
With a unit test that invokes the SanitizingFunction bean directly against real property names from the project, including cases with underscores, mixed case, and external provider prefixes.

Where I land

Spring Boot's default sanitizer isn't a placebo: it covers the generic case reasonably well, per what the official reference itself documents. What I can't claim without production evidence is exactly how much it reduces risk in any specific project — that depends entirely on how far that project's naming conventions drift from the default list.

What I can say with technical confidence: if nobody's audited the project's custom property names against the sanitizer's pattern list, there's an unclosed gap sitting there. That's not a remote possibility, it's a direct consequence of how the mechanism works — a name-matching filter only catches the names it was told to look for.

My practical recommendation follows the same logic I used to think through endpoint allowlisting in the previous post about actuator: treat sanitization as a living list that gets reviewed every time a new integration gets added, not as a configuration you set once and forget. Today's regex won't cover the variable name someone's going to invent next sprint. The uncomfortable question worth asking your team right now: when was the last time anyone actually opened application.yml and checked every key against the sanitizer, instead of assuming Spring already handled it?

If you're into how I think about architecture decisions with this same "what does the tool cover versus what do I have to cover" lens, I've got related posts on JWT vs stateful sessions and on what the path to Java Champion actually means that touch the same tension from other angles.

Original source:

Spring Boot Actuator Docs: https://docs.spring.io/spring-boot/reference/actuator/endpoints.html

This article was originally published on juanchi.dev

El sanitizer de /actuator/env no conoce tus convenciones

Juan Torchia — Fri, 11 Sep 2026 12:00:15 +0000

Hace poco escribí sobre allowlist en actuator endpoints: qué exponer y qué no. Quedó una pregunta abierta que me siguió picando: si decidís dejar /actuator/env habilitado —porque lo necesitás para debug en staging, porque el equipo de infra lo pide— ¿qué te asegura que no vas a mostrar un secreto en texto plano la primera vez que alguien le pegue un curl?

La respuesta corta es: nada, si confiás ciegamente en el sanitizer default.

El problema con actuator env show values

Spring Boot trae un sanitizer que enmascara automáticamente ciertos valores antes de mostrarlos en /actuator/env. Funciona por nombre de propiedad: si la clave contiene password, secret, key, token o credentials, el valor sale como ******. Es una defensa razonable para el caso genérico.

El problema es justamente eso: es genérica. Cubre las palabras que un desarrollador de Spring imaginó que ibas a usar. No cubre las que tu equipo realmente usa.

Pensá en cómo se nombran las variables de entorno en un proyecto real: DB_PASS en vez de DB_PASSWORD, API_AUTH en vez de API_TOKEN, WEBHOOK_SIGNING, PARTNER_SHARED_VALUE, INTERNAL_CIPHER. Ninguna de esas contiene las palabras clave que el sanitizer busca. Todas terminan en la respuesta JSON de /actuator/env sin ningún asterisco.

Mi tesis es esta: el sanitizer default no falla porque esté mal escrito, falla porque asume que todo el mundo nombra igual. Y en la práctica cada equipo tiene su propio dialecto de variables de entorno. Las fugas reales casi nunca pasan por password mal escrito — pasan por la convención custom que alguien inventó en un sprint y que nadie agregó a la lista de patrones.

Qué dice la fuente oficial y qué no dice

La documentación oficial de Spring Boot Actuator confirma el comportamiento: el endpoint /env aplica sanitización sobre los valores antes de exponerlos, y ese comportamiento es configurable mediante la interfaz SanitizingFunction, que reemplazó al mecanismo de Sanitizer basado en keywords en versiones más recientes del framework.

Lo que la doc no dice —porque no es su trabajo decirlo— es qué nombres específicos vas a usar en tu proyecto. Eso lo tenés que auditar vos. La doc te da el mecanismo de extensión; el catálogo de qué sanitizar es responsabilidad de quien configura el proyecto, no del framework.

Esa diferencia entre "mecanismo disponible" y "configuración correcta para este caso puntual" es exactamente donde se cuelan la mayoría de los incidentes de exposición que se reportan en configuraciones default sin revisión.

Dónde se equivoca la gente

La receta común que veo repetida en foros y en configuraciones heredadas es: "activá management.endpoint.env.show-values=when-authorized y ya estás cubierto". Eso resuelve quién puede ver los valores, no qué valores se muestran sin máscara a quien tiene autorización. Son dos problemas distintos y se los trata como uno solo todo el tiempo.

El costo oculto aparece cuando el endpoint queda accesible para un rol interno —un servicio de monitoreo, un dashboard de operaciones— y ese rol termina viendo credenciales que nadie pensó en enmascarar porque el nombre de la variable no calzaba con el patrón default.

Caso tipico que uso para explicar esto: un proyecto que usa Vault o AWS Secrets Manager para producción, pero en application-staging.yml deja variables con nombres tipo THIRD_PARTY_SHARED_SECRET_VALUE. El sanitizer default no necesariamente matchea SHARED_SECRET_VALUE como unidad reconocible si el patrón de búsqueda es más rígido que una simple substring de "secret" — y en configuraciones custom heredadas, es común que las variantes con guiones bajos o mayúsculas mixtas queden afuera si alguien sobreescribió el regex sin revisarlo a fondo.

Acá va la forma de extender el sanitizer con un patrón propio, usando SanitizingFunction:

// Configuracion custom del sanitizer para /actuator/env
@Bean
public SanitizingFunction customSanitizingFunction() {
    // Patron que cubre convenciones propias del equipo
    Pattern patronCustom = Pattern.compile(
        "(?i).*(pass|auth|signing|shared|cipher).*"
    );
    return data -> {
        String nombre = data.getSanitizableData().getKey();
        if (patronCustom.matcher(nombre).matches()) {
            return data.withValue("******");
        }
        // si no matchea, dejamos que el sanitizer default siga la cadena
        return data;
    };
}

Este bean se agrega a la cadena existente de sanitizers; no la reemplaza. Spring Boot ejecuta todos los SanitizingFunction registrados en orden y aplica el enmascarado si alguno de ellos decide que corresponde.

flowchart LR
  A[Request a /actuator/env] --> B{Sanitizer default}
  B -->|nombre matchea password/secret/token| C[Enmascarado con ******]
  B -->|no matchea| D{SanitizingFunction custom}
  D -->|nombre matchea patron propio| C
  D -->|no matchea nada| E[Valor expuesto en texto plano]

Ese último camino, el de la derecha, es el que hay que cerrar activamente. No se cierra solo.

Matriz de decisión para /actuator/env

Situación	Qué mirar primero	Qué hacer
Endpoint expuesto solo en localhost/debug	Confirmar que no hay tunneling ni proxy hacia afuera	Sanitizer default puede alcanzar, pero auditá nombres de variables igual
Endpoint accesible en staging con roles de monitoreo	Qué variables custom usa tu equipo, no solo las de Spring	Agregar `SanitizingFunction` con el patrón propio antes de habilitar acceso
Variables con nombres no convencionales (`DB_PASS`, `API_AUTH`)	Listar todas las claves de `application.yml` y `.env` de cada ambiente	Extender el patrón regex, no confiar en la lista default
Integraciones con proveedores externos (webhooks, partners)	Nombres que el partner define, no los que definís vos	Sanitizer custom por prefijo o sufijo del proveedor
Necesitás decidir si deshabilitar el endpoint entero	Si nadie en el equipo audita nombres de propiedades regularmente	Deshabilitarlo es más seguro que un sanitizer sin mantenimiento

La última fila es la que más me interesa señalar: si no hay alguien revisando periódicamente qué nombres de propiedad aparecen en el código, un sanitizer custom mal mantenido da una falsa sensación de seguridad — peor que no tener nada, porque genera confianza donde no debería haberla. Prefiero el criterio de allowlist que ya planteé en el post anterior antes que un sanitizer que nadie actualiza.

Errores comunes y gotchas

Confundir autorización con sanitización. show-values=when-authorized controla acceso, no contenido. Son configuraciones independientes que hay que revisar las dos.
Copiar el regex de un proyecto anterior sin adaptarlo. Las convenciones de nombres cambian entre equipos y entre proyectos dentro del mismo equipo.
No testear el sanitizer con un caso negativo. Falta común: nadie escribe un test que verifique que una variable con nombre "raro" efectivamente sale enmascarada.
Pensar que el problema es solo de producción. Staging y entornos de desarrollo compartidos también exponen /actuator/env, y ahí suelen vivir credenciales reales de servicios de terceros para pruebas de integración.
Asumir que el framework te cubre las espaldas para siempre. Spring Boot mantiene actualizados sus propios keywords default con cada release; la lista de convenciones custom de tu equipo no forma parte de esa actualización — ese mantenimiento es tuyo, siempre.

FAQ

¿El sanitizer de Spring Boot enmascara todos los valores sensibles por default?
No. Enmascara valores cuyo nombre de propiedad contiene palabras específicas como password, secret, key, token o credentials. Cualquier convención de nombres distinta a esa queda sin cubrir salvo que se configure explícitamente.

¿Qué diferencia hay entre Sanitizer y SanitizingFunction?
SanitizingFunction es la interfaz recomendada en versiones recientes de Spring Boot para extender el comportamiento de sanitización de forma programática, reemplazando el enfoque anterior basado únicamente en una lista de keywords fija.

¿Puedo tener varios SanitizingFunction registrados a la vez?
Sí. Spring Boot los ejecuta en cadena; si cualquiera de ellos decide enmascarar un valor, ese valor queda enmascarado en la respuesta final.

¿Deshabilitar /actuator/env es más seguro que sanitizarlo?
Depende del caso de uso. Si tu equipo no tiene proceso para mantener actualizado el sanitizer custom, deshabilitar el endpoint o restringirlo con una allowlist estricta reduce el riesgo con menos mantenimiento continuo.

¿show-values=when-authorized resuelve el problema de los secretos expuestos?
No por sí solo. Controla quién puede ver los valores, no qué valores se muestran sin máscara a esos usuarios autorizados. Son dos configuraciones distintas que hay que combinar.

¿Cómo pruebo que mi sanitizer custom funciona antes de deployar?
Con un test unitario que invoque el bean SanitizingFunction directamente contra nombres de propiedad reales de tu proyecto, incluyendo casos con guiones bajos, mayúsculas mixtas y prefijos de proveedores externos.

Mi postura

El sanitizer default de Spring Boot no es un placebo: cubre el caso genérico razonablemente bien, según lo que documenta la propia referencia oficial. Lo que no puedo sostener sin evidencia productiva es cuánto exactamente reduce el riesgo en un proyecto específico — eso depende enteramente de qué tan alejadas estén las convenciones de nombres de ese proyecto respecto de la lista default.

Lo que sí puedo afirmar con criterio técnico: si nadie auditó los nombres de propiedad custom del proyecto contra la lista de patrones del sanitizer, hay una brecha sin cerrar. No es una posibilidad remota, es una consecuencia directa de cómo funciona el mecanismo.

Mi recomendación práctica es la misma lógica que usé para pensar allowlist de endpoints en el post anterior sobre actuator: tratá la sanitización como una lista viva que se revisa cada vez que se agrega una integración nueva, no como una configuración que se pone una vez y se olvida. El regex de hoy no cubre el nombre de variable que alguien va a inventar en el próximo sprint.

Lo incómodo de todo esto es que no hay checklist que te salve si nadie mira. Podés tener el SanitizingFunction más prolijo del mundo y seguir filtrando un secreto porque el pasante que armó la integración con el partner nuevo usó PARTNER_KEY_RAW y a nadie se le ocurrió actualizar el regex esa semana. La pregunta que me hago antes de habilitar cualquier endpoint de actuator no es "¿tiene sanitizer?" sino "¿quién es responsable de actualizar esta lista cuando cambie algo?". Si no hay respuesta clara, prefiero apagarlo.

Si te interesa cómo pienso decisiones de arquitectura con este mismo criterio de "qué cubre la herramienta versus qué tengo que cubrir yo", tengo posts relacionados sobre JWT vs sesiones con estado y sobre qué significa el camino a Java Champion que tocan la misma tensión desde otros ángulos.

Fuente original:

Spring Boot Actuator Docs: https://docs.spring.io/spring-boot/reference/actuator/endpoints.html

Este artículo fue publicado originalmente en juanchi.dev

depends_on Isn't Enough: service_healthy in Compose

Juan Torchia — Wed, 09 Sep 2026 14:30:19 +0000

I lost probably forty minutes on this one the first time, and I still see it happen to other people. You spin up docker-compose up with a backend and a Postgres database. The backend has depends_on: [db]. Everything starts, the backend throws ECONNREFUSED two seconds in, the Postgres container is sitting there alive and well, and you start googling the error convinced it's a networking issue between services. It isn't. depends_on on its own did exactly what it promises: it waited for the db container to exist and be running. It never promised that Postgres inside it would be accepting connections.

I wrote about this same misunderstanding recently from another angle — the gap between what a healthcheck tells Docker and what it tells an orchestrator like Kubernetes. This post goes one level deeper: into the docker-compose.yml that anyone edits daily, no cluster, no readiness probes involved.

Docker Compose healthcheck: what it solves and what it doesn't

My thesis is simple: depends_on without condition is an illusion of order. It gives you container startup sequencing, not service availability sequencing. Only with condition: service_healthy do you get something verifiable — Compose won't start the second service until the first one's healthcheck reports healthy.

The source is the official Compose specification. It makes clear that healthcheck defines a command Docker runs periodically inside the container, and that depends_on accepts an object with condition instead of just a list of service names. The valid conditions are service_started, service_healthy, and service_completed_successfully. Without an explicit condition, the default is service_started — which is exactly the behavior that breaks expectations: container up, not necessarily the process inside responding.

Where people get it wrong

The common recipe I see in repos and tutorials — and, if I'm honest, the one I copy-pasted myself before it bit me — is this:

services:
  db:
    image: postgres:16
  api:
    build: .
    depends_on:
      - db

It compiles, it starts, it "works" in the demo because Postgres usually boots fast on a laptop with an SSD. The hidden cost shows up in CI, on a slower machine, or when someone adds an entrypoint.sh to the Postgres image that runs migrations before accepting connections. That's when the margin that "worked by luck" disappears and api fails its first connection. It's not dramatic, it's just annoying: a flaky pipeline that passes eight times out of ten and makes you doubt your own code before you doubt the compose file.

The counter-example that fixes this:

services:
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5
  api:
    build: .
    depends_on:
      db:
        condition: service_healthy

Now api doesn't start until pg_isready returns success multiple times per interval and retries. That's the difference between "the container exists" and "the container is ready," and it's exactly the same concept as the readiness probe Kubernetes formalizes with readinessProbe — but solved here at the local Compose level, no cluster needed.

flowchart LR
  A[db starts] --> B{db healthcheck}
  B -->|starting/unhealthy| B
  B -->|healthy| C[api starts]
  C --> D{api healthcheck}
  D -->|healthy| E[stack ready]

Decision matrix: when to condition and when not to

Not every service needs this rigidity, and slapping healthcheck on everything is its own kind of cargo cult. Here's the check I actually run before adding one:

Situation	What to do	Why
Stateful service (DB, cache, broker) that another service connects to on boot	`healthcheck` + `condition: service_healthy`	Early connection failure is predictable and cheap to avoid
Stateless service that only exposes HTTP and tolerates client-side retries	Simple `depends_on` or none	The cost of waiting can be higher than the cost of retrying in the app
One-shot migration job that runs and terminates	`condition: service_completed_successfully`	What matters isn't "healthy," it's that it finished successfully
CI environment with shared resources and slow startups	`healthcheck` with generous `retries`	A short timeout in CI produces false negatives you won't see locally
Microservice that already handles reconnection with backoff in its own code	Simple `depends_on`, let the app retry	Duplicating wait logic in Compose and in the code is redundant

What you CAN'T conclude from this

The Compose documentation doesn't tell you how long a healthcheck with specific interval, timeout, and retries values takes to converge in real production, because that depends on the image, the host, and the load — there's no universal number that fits every case. It also doesn't solve the problem of "service healthy but still can't handle real traffic" under load, which is different from "started up fine cold." And depends_on with condition, while it orders startup, isn't a continuous retry mechanism throughout the container's lifetime: if db goes down after api already started healthy, Compose doesn't go back to blocking anything. For that you need reconnection logic in the app's code, not in the docker-compose.yml.

Nor is it a substitute for Kubernetes's readinessProbe and livenessProbe if the final destination is a cluster: Compose solves the problem in local development or a staging docker-compose up, but the production orchestration guarantee lives at another level, with other tools and other restart semantics. What I don't buy is treating a green docker-compose up as proof that the same stack will behave in production — it proves ordering, nothing about load.

FAQ

Is depends_on without condition good for anything?
It's good for startup order and for making Compose stop containers in reverse order when you bring the stack down. It doesn't guarantee that the dependent service is ready to receive traffic.

What happens if the healthcheck never reaches healthy?
The service depending on it with condition: service_healthy never starts, and Compose reports it as a dependency failure. That's preferable to a silent startup that fails at runtime.

Does service_healthy work with any image?
Only if the image defines a healthcheck — either baked into the Dockerfile or declared in the docker-compose.yml. Without a defined healthcheck, Compose has no way to evaluate the condition.

Does this replace Kubernetes readiness probes?
No. They're analogous concepts but they live at different layers. Compose's healthcheck is for the world of local or simple self-hosted docker-compose up; readinessProbe is the equivalent piece when the destination is a Kubernetes cluster.

How many retries or what interval should I set?
There's no number that works for every case: it depends on the image and the environment. The sensible move is to start with conservative values, measure in your own CI pipeline or staging environment, and adjust based on what you observe there — not copy a value from a generic example.

Is condition: service_completed_successfully the same as service_healthy?
No. service_completed_successfully waits for the container to exit with a zero exit code, useful for one-shot migration jobs. service_healthy waits for a healthcheck that keeps running while the container is alive.

Bottom line

If a project's docker-compose.yml has depends_on as a plain list against a stateful service, there's a design flaw waiting for the worst possible moment to show up — probably in CI, with tighter resources than your dev laptop. The fix isn't complex: a well-defined healthcheck and condition: service_healthy. What I do ask is that you don't confuse this with a guarantee of continuous availability, nor with the equivalent of a production Kubernetes readiness probe. It's a guarantee of ordered startup in a local or simple staging environment, and that's how I treat it: useful, verifiable against the official source, and with limits worth knowing before you assume more than it delivers. The uncomfortable question worth asking your own repo today: does your compose file order containers, or does it order services actually being ready?

If the stack is already using TanStack Query against Server Actions, it's worth checking how cache invalidation is handled in that post about setQueryData. And if the next step is Next.js with layered caching, the difference between revalidatePath and revalidateTag is covered in this other analysis.

Original source: Docker Compose Spec — healthcheck

This article was originally published on juanchi.dev

depends_on no basta: el service_healthy en Compose

Juan Torchia — Wed, 09 Sep 2026 14:30:14 +0000

Levantás un docker-compose up con un backend y una base Postgres. El backend tiene depends_on: [db]. Arranca todo, el backend tira ECONNREFUSED a los dos segundos, el contenedor de Postgres sigue vivo, y googleás el error pensando que es un problema de red entre servicios. No lo es. Me pasó armando un stack chico para probar una migración: el contenedor de db estaba "up" en el docker ps, pero Postgres todavía estaba corriendo su inicialización interna y no aceptaba conexiones. depends_on sin más hizo exactamente lo que promete: esperó a que el contenedor de db existiera y estuviera corriendo. Nunca prometió que Postgres adentro estuviera aceptando conexiones.

Ese malentendido es viejo y lo escribí hace poco desde otro ángulo — la diferencia entre lo que un healthcheck le dice a Docker y lo que le dice a un orquestador como Kubernetes. Este post baja un nivel más: al docker-compose.yml que cualquiera edita a diario, sin cluster, sin readiness probes de Kubernetes de por medio.

Docker Compose healthcheck: qué resuelve y qué no

Mi tesis es simple: depends_on sin condition es una ilusión de orden. Te da secuencia de arranque de contenedores, no secuencia de disponibilidad de servicio. Con condition: service_healthy recién ahí tenés algo verificable — Compose no arranca el segundo servicio hasta que el healthcheck del primero reporte healthy.

Lo incómodo es que esta confusión no es un error de configuración raro: es el comportamiento default de Compose, y por eso aparece en tantos repos que "andan bien" hasta que dejan de andar.

La fuente es la especificación oficial de Compose. Ahí queda claro que healthcheck define un comando que Docker ejecuta periódicamente dentro del contenedor, y que depends_on acepta un objeto con condition en vez de solo una lista de nombres de servicios. Las condiciones válidas son service_started, service_healthy y service_completed_successfully. Sin condition explícita, el default es service_started, que es exactamente el comportamiento que rompe expectativas: contenedor arriba, no necesariamente el proceso adentro respondiendo.

Dónde se equivoca la gente

La receta común que veo en repos y en tutoriales es esta:

services:
  db:
    image: postgres:16
  api:
    build: .
    depends_on:
      - db

Compila, arranca, "funciona" en la demo porque Postgres suele levantar rápido en una laptop con SSD. El costo oculto aparece en CI, en una máquina más lenta, o cuando alguien le agrega un entrypoint.sh a la imagen de Postgres que corre migraciones antes de aceptar conexiones. Ahí el margen que "funcionaba por suerte" desaparece y el api falla la primera conexión.

El contraejemplo que corrige esto:

services:
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 5
  api:
    build: .
    depends_on:
      db:
        condition: service_healthy

Ahora api no arranca hasta que pg_isready devuelva éxito varias veces según interval y retries. Es la diferencia entre "el contenedor existe" y "el contenedor está listo", y es exactamente el mismo concepto de readiness probe que Kubernetes formaliza con readinessProbe — pero acá resuelto a nivel de Compose local, sin necesidad de un cluster.

flowchart LR
  A[db arranca] --> B{healthcheck de db}
  B -->|starting/unhealthy| B
  B -->|healthy| C[api arranca]
  C --> D{healthcheck de api}
  D -->|healthy| E[stack listo]

Matriz de decisión: cuándo condicionar y cuándo no

No todo servicio necesita esta rigidez. Antes de agregar healthcheck y condition: service_healthy en cada línea, conviene mirar esto:

Situación	Qué hacer	Por qué
Servicio con estado (DB, cache, broker) al que otro se conecta al boot	`healthcheck` + `condition: service_healthy`	El fallo de conexión temprana es predecible y barato de evitar
Servicio sin estado que solo expone HTTP y tolera reintentos en el cliente	`depends_on` simple o ninguno	El costo de esperar puede ser mayor que el de reintentar en la app
Job de migración que corre una vez y termina	`condition: service_completed_successfully`	No es "healthy" lo que importa, es que terminó bien
Entorno de CI con recursos compartidos y arranques lentos	`healthcheck` con `retries` generosos	Un timeout corto en CI genera falsos negativos que no ves en local
Microservicio que ya maneja reconexión con backoff en su propio código	`depends_on` simple, dejar que la app reintente	Duplicar la lógica de espera en Compose y en el código es redundante

Qué NO se puede concluir de esto

La documentación de Compose no dice cuánto tarda en converger un healthcheck con valores específicos de interval, timeout y retries en producción real, porque eso depende de la imagen, del host y de la carga — no hay un número universal que valga para todos los casos. Tampoco resuelve el problema de "servicio healthy pero todavía no puede atender tráfico real" bajo carga, que es distinto de "arrancó bien en frío". Y depends_on con condition, aunque ordena el arranque, no es un mecanismo de reintento continuo durante la vida del contenedor: si db se cae después de que api ya arrancó healthy, Compose no vuelve a bloquear nada. Para eso hace falta la lógica de reconexión en el código de la app, no en el docker-compose.yml.

Tampoco es un sustituto de readinessProbe y livenessProbe de Kubernetes si el destino final es un cluster: Compose resuelve el problema en desarrollo local o en un docker-compose up de staging, pero la garantía de orquestación productiva vive en otro nivel, con otras herramientas y otras semánticas de reinicio.

FAQ

¿depends_on sin condition sirve para algo?
Sirve para el orden de arranque y para que Compose pare los contenedores en el orden inverso al bajar el stack. No sirve para garantizar que el servicio dependido esté listo para recibir tráfico.

¿Qué pasa si el healthcheck nunca llega a healthy?
El servicio que depende de él con condition: service_healthy no arranca, y Compose lo reporta como fallo de dependencia. Prefiero eso mil veces a un arranque silencioso que falla en runtime y te hace perder media hora googleando un ECONNREFUSED.

¿service_healthy funciona con cualquier imagen?
Solo si la imagen define un healthcheck — propio en el Dockerfile o declarado en el docker-compose.yml. Sin healthcheck definido, Compose no tiene manera de evaluar la condición.

¿Esto reemplaza los readiness probes de Kubernetes?
No. Son conceptos análogos pero viven en capas distintas. healthcheck de Compose es para el mundo de docker-compose up local o self-hosted simple; readinessProbe es la pieza equivalente cuando el destino es un cluster de Kubernetes.

¿Cuántos retries o qué interval conviene poner?
No hay un número que sirva para todos los casos: depende de la imagen y el entorno. Lo prudente es arrancar con valores conservadores, medir en el propio pipeline de CI o entorno de staging, y ajustar según lo que se observe ahí — no copiar un valor de un ejemplo genérico.

¿condition: service_completed_successfully es lo mismo que service_healthy?
No. service_completed_successfully espera a que el contenedor termine con código de salida cero, útil para jobs de migración one-shot. service_healthy espera a un healthcheck que sigue corriendo mientras el contenedor vive.

Postura final

Si tu docker-compose.yml tiene depends_on como lista simple contra un servicio con estado, hay una falla de diseño esperando el momento menos oportuno para aparecer — probablemente en CI, con recursos más ajustados que en tu laptop. La corrección no es compleja: un healthcheck bien definido y condition: service_healthy. Lo que sí pido es que no lo confundas con una garantía de disponibilidad continua ni con el equivalente de un readiness probe de Kubernetes en producción. Es una garantía de arranque ordenado en un entorno local o de staging simple, y como tal hay que tratarla: útil, verificable contra la fuente oficial, y con límites que conviene conocer antes de asumir más de lo que da. Mi límite personal: si el proyecto ya tiene un cluster de verdad, dejo de pelear con Compose y muevo la garantía de readiness a donde corresponde.

Si el stack ya usa TanStack Query contra Server Actions, vale la pena revisar cómo se maneja la invalidación de cache en ese post sobre setQueryData. Y si el próximo paso es Next.js con cache en capas, la diferencia entre revalidatePath y revalidateTag está detallada en este otro análisis.

Fuente original: Docker Compose Spec — healthcheck

Este artículo fue publicado originalmente en juanchi.dev

Claude API Key Security: Why .env Is Not Optional

Juan Torchia — Wed, 09 Sep 2026 12:00:19 +0000

You open a route.ts file in a Next.js project, you need to test a Claude API call fast, and the temptation is to write const apiKey = "sk-ant-api03-..." right at the top. "I'll pull it out later," you think. The problem is that "later" almost never arrives before the first git commit, and once that key is in the history, removing it from the current file didn't remove it from anywhere.

My take is simple and has no nuance: never hardcode an API key, not even "just to test." Logs and git history don't forgive. This isn't a style rule, it's a decision with measurable consequences the exact moment someone clones that repo, or when an error log ends up in a monitoring tool you don't control.

The Real Problem: Where That "Just for Testing" Key Actually Ends Up

When you're working with Cline connected to OpenRouter, or directly to the Anthropic API, the typical flow is: you generate the key in the provider's dashboard, you need it somewhere in the code so the HTTP client can use it, and that's the fork in the road. One path leads to a config file that git ignores. The other leads to a string literal that git happily versions.

The difference between those two paths doesn't show up on day one. It shows up when:

someone runs git log -p and finds the key in a commit from three months ago, even though you already deleted it from the current file
an unhandled error in the HTTP client logs the full Authorization header to the console or to some logging service
the repo goes public, or someone clones it to collaborate and now has access to billing that isn't theirs

None of these scenarios require anyone to "hack" anything. They just require the key to have sat in plain text somewhere you don't control, once it left your machine.

What Anthropic's Official Docs Say (and What They Don't)

Anthropic's getting-started documentation is clear on one point: the API key is passed as the x-api-key header on every request, and it explicitly recommends not exposing it in client-side code or public repositories. That's the limit of what the docs guarantee: they tell you the auth mechanism and warn you about the obvious risk.

What the docs don't tell you — because it's not their job — is how to structure your project so that key never accidentally makes it into a commit. That's a project architecture decision, not something an API flag solves for you. That's where your own judgment kicks in, not a literal reading of the docs.

The Recipe People Use, and Why It Fails

The pattern I keep seeing repeated in personal projects and tutorial examples is this: create a .env file at the root, drop the key in there, and trust that "it's probably in Next.js's default .gitignore." Sometimes it is. Sometimes the project started from an old create-next-app scaffold, or someone renamed the file to .env.production without checking whether that variant is also ignored.

The hidden cost isn't the .env itself. It's the false sense of security that comes from having "a separate file" without verifying that git is actually ignoring it. A classic counterexample: someone copies .env to .env.backup to have a quick reference, and that differently-suffixed file doesn't match any pattern in the .gitignore. The key sits there, versioned, with a filename that doesn't even look suspicious in a quick diff.

Another common mistake, more subtle: passing the key as a prop into a client-side React component. If the component runs in the browser, any variable prefixed with NEXT_PUBLIC_ ends up in the JavaScript bundle the browser downloads. That's not a Next.js bug, that's documented behavior: those variables are public by design. Putting a Claude key there is as literal an exposure as pasting it into the code.

# .env.local (never versioned, Next.js ignores it by default)
ANTHROPIC_API_KEY=sk-ant-api03-xxxxx
OPENROUTER_API_KEY=sk-or-v1-xxxxx

# read server-side, never with the NEXT_PUBLIC_ prefix

// route.ts - server-side, the key never reaches the browser
const apiKey = process.env.ANTHROPIC_API_KEY;
if (!apiKey) {
  throw new Error("Falta ANTHROPIC_API_KEY en las variables de entorno");
}

Checklist Before Touching Any LLM Provider's API Key

This is the matrix I use as sound judgment, not as an absolute guarantee of anything:

Situation	What to check first	Risk if ignored
New Next.js project	Confirm `.gitignore` explicitly includes `.env*.local`	Key versioned from the first commit
Variable used in a client component	Verify it does NOT have the `NEXT_PUBLIC_` prefix	Key visible in the browser bundle
Repo that's going public or shared	Run `git log --all -p \	grep "sk-"` before publishing
Server error logs	Check the HTTP client isn't logging full headers	`Authorization` or `x-api-key` in plain text in the log
Cline or another agent with multiple providers	Confirm each key lives in its own separate variable, not a shared string	Rotating one key breaks all providers at once
Compromised key (suspected or confirmed)	Revoke it in the provider's dashboard before investigating the cause	Window of misuse while you're still debugging

The rotation point deserves a clarification: revoke first, investigate after. Not the other way around. The gap between "I suspect it leaked" and "I disabled it" is time you don't control.

What You Can't Conclude From This

This guide doesn't replace an automated secret scan in CI, and it's not a security audit. Tools like git-secrets or pre-commit hooks that detect key patterns add a layer the human eye doesn't cover on every commit. I also don't have public evidence of specific Claude or DeepSeek key leak incidents to cite here: what exists is the documented header-based auth mechanism, and the known behavior of Next.js with NEXT_PUBLIC_ variables. The rest is architectural judgment, not measured data.

If your project already has a case of a key exposed in production, this isn't enough: at that point the move is revoke, rotate, and audit access with the provider's own tools, not read a blog post.

flowchart LR
  A[Necesito una API key] --> B{¿Va a un componente cliente?}
  B -->|sí| C[No la pongas ahí. Usá un endpoint server-side]
  B -->|no| D[.env.local + process.env]
  D --> E{¿El repo se va a compartir?}
  E -->|sí| F[Revisá git log por patrones sk-]
  E -->|no| G[Confirmá .gitignore antes del primer commit]

I touched this same principle — separating what runs server-side from what reaches the client — from a different angle when I wrote about cache and revalidation in Next.js: the server/client boundary isn't just a performance question, it's also the boundary between what secrets exist and what secrets don't.

FAQ

Can I use the same Claude API key in development and production?
Technically yes, but it's not advisable. If the dev key leaks in a repo or a debug log, the blast radius includes production. Using separate keys per environment limits that radius.

Is it enough to put the key in .env without the .local suffix?
Depends on the exact .gitignore configuration of the project. Next.js's default ignores .env*.local, but a plain .env without that suffix might not be covered. Check the file, don't assume.

What's the difference between handling Anthropic's key vs. OpenRouter's?
The mechanism changes (different headers, different key formats), but the handling principle is identical: never in versioned code, never in public client variables, always in server-side environment variables.

Does Cline expose the keys I use with OpenRouter or Anthropic?
Cline reads them from the extension's local config or from system environment variables, it doesn't write them into the project's code. The risk shows up when the user manually copies that key into a repo file "to have it handy."

Is it worth rotating the key periodically even without any suspicion of a leak?
It's a sound practice in any credential system, though there's no universal frequency rule. What is concrete: if there's a suspected leak, rotation isn't periodic, it's immediate.

Is an .env.example file with no real values safe to version?
Yes, as long as it only contains variable names without real values (ANTHROPIC_API_KEY=). It's a common practice to document what variables a project needs without exposing anything.

My Stance

There's no legitimate shortcut here. The "just for testing" excuse is the same excuse used for leaving a console.log that ends up in production, except here the cost isn't an annoying log line: it's a key with access to an LLM provider's billing. If you're building a project with multiple providers — something I touched on when I wrote about monitoring AI agent traffic with Sniffnet — the discipline of keeping separate environment variables per provider isn't paranoia, it's the only way rotating one key doesn't mean breaking the other three integrations that depend on the same .env.

The next concrete step, before you write another line of code that calls an LLM API: open your project's .gitignore and confirm it actually ignores the environment files you're using. Don't assume it.

Original source:

Anthropic API Docs: https://docs.anthropic.com/en/api/getting-started

This article was originally published on juanchi.dev

Claude API key seguridad: por qué el .env no es opcional

Juan Torchia — Wed, 09 Sep 2026 12:00:15 +0000

Abrís un archivo route.ts en un proyecto Next.js, necesitás probar rápido una llamada a la API de Claude, y la tentación es escribir directamente const apiKey = "sk-ant-api03-..." arriba de todo. "Después la saco", pensás. El problema es que "después" casi nunca llega antes del primer git commit, y una vez que esa key entra al historial, sacarla del archivo actual no la sacó de ningún lado.

Mi tesis es simple y no tiene matices: nunca hardcodees una API key, ni "solo para probar". Los logs y el historial de git no perdonan. No es una regla de estilo, es una decisión que tiene consecuencias medibles en el momento exacto en que alguien clona ese repo o cuando un log de error termina en una herramienta de monitoreo que no controlás.

El problema real: dónde termina esa key que "es solo para probar"

Cuando trabajás con Cline conectado a OpenRouter o directo a la API de Anthropic, el flujo típico es: generás la key en el dashboard del proveedor, la necesitás en algún lado del código para que el cliente HTTP la use, y ahí está la bifurcación. Un camino lleva a un archivo de configuración que git ignora. El otro lleva a un string literal que git sí versiona.

La diferencia entre esos dos caminos no se nota el primer día. Se nota cuando:

alguien hace git log -p y encuentra la key en un commit de hace tres meses, aunque ya la borraste del archivo actual
un error no manejado en el cliente HTTP loguea el header Authorization completo en la consola o en un servicio de logging
el repo pasa a ser público, o alguien lo clona para colaborar y ahora tiene acceso a facturación ajena

Ninguno de estos escenarios requiere que alguien "hackee" nada. Requiere que la key haya estado en texto plano en un lugar que no controlás una vez que sale de tu máquina.

Qué dice la documentación oficial de Anthropic (y qué no dice)

La documentación de Anthropic sobre getting started es clara en un punto: la API key se pasa como header x-api-key en cada request, y se recomienda explícitamente no exponerla en código del lado del cliente ni en repositorios públicos. Ese es el límite de lo que la doc garantiza: te dice el mecanismo de autenticación y te avisa del riesgo obvio.

Lo que la documentación no dice —porque no es su trabajo— es cómo estructurar el proyecto para que esa key nunca llegue a un commit por accidente. Eso es una decisión de arquitectura del proyecto, no algo que resuelva un flag de la API. Ahí es donde entra el criterio propio, no la lectura literal de la doc.

La receta que la gente usa y por qué falla

El patrón que veo repetirse en proyectos personales y en ejemplos de tutoriales es este: crear un archivo .env en la raíz, poner ahí la key, y confiar en que "seguro está en el .gitignore default de Next.js". A veces sí. A veces el proyecto arrancó con un create-next-app viejo, o alguien renombró el archivo a .env.production sin revisar si esa variante también está ignorada.

El costo oculto no es el .env en sí. Es la falsa sensación de seguridad que da tener "un archivo separado" sin verificar que git efectivamente lo esté ignorando. Un contraejemplo típico: alguien copia .env a .env.backup para tener una referencia rápida, y ese archivo con sufijo distinto no matchea ningún patrón del .gitignore. La key queda ahí, versionada, con nombre de archivo que ni siquiera aparece sospechoso en un diff rápido.

Otro error común, más sutil: pasar la key como prop en un componente cliente de React. Si el componente corre en el browser, cualquier variable que empiece con NEXT_PUBLIC_ termina en el bundle de JavaScript que se descarga el navegador. Eso no es un bug de Next.js, es el comportamiento documentado: esas variables son públicas por diseño. Poner ahí una key de Claude es exponerla tan literalmente como pegarla en el código.

# .env.local (nunca se versiona, Next.js lo ignora por default)
ANTHROPIC_API_KEY=sk-ant-api03-xxxxx
OPENROUTER_API_KEY=sk-or-v1-xxxxx

# se lee del lado del servidor, nunca con prefijo NEXT_PUBLIC_

// route.ts - server-side, la key nunca llega al browser
const apiKey = process.env.ANTHROPIC_API_KEY;
if (!apiKey) {
  throw new Error("Falta ANTHROPIC_API_KEY en las variables de entorno");
}

Checklist antes de tocar cualquier API key de un proveedor LLM

Esta es la matriz que uso como criterio prudente, no como garantía absoluta de nada:

Situación	Qué mirar primero	Riesgo si se ignora
Proyecto nuevo con Next.js	Confirmar que `.gitignore` incluye `.env*.local` explícitamente	Key versionada desde el primer commit
Variable usada en componente cliente	Verificar que NO tenga prefijo `NEXT_PUBLIC_`	Key visible en el bundle del navegador
Repo que va a ser público o compartido	Correr `git log --all -p \	grep "sk-"` antes de publicar
Logs de error en servidor	Revisar que el cliente HTTP no logue headers completos	`Authorization` o `x-api-key` en texto plano en el log
Cline u otro agente con múltiples providers	Confirmar que cada key vive en su variable separada, no en un string compartido	Rotar una key rompe todos los proveedores a la vez
Key comprometida (sospecha o confirmación)	Revocarla en el dashboard del proveedor antes de investigar la causa	Ventana de uso indebido mientras se debuggea

El punto de rotación merece una aclaración: revocar primero, investigar después. No al revés. La ventana entre "sospecho que se filtró" y "la desactivé" es tiempo de uso que no controlás.

Qué NO se puede concluir de esto

Esta guía no reemplaza un escaneo de secretos automatizado en CI, y no es una auditoría de seguridad. Herramientas como git-secrets o los hooks de pre-commit que detectan patrones de keys agregan una capa que el ojo humano no cubre en cada commit. Tampoco tengo evidencia pública de incidentes específicos de filtración de keys de Claude o DeepSeek para citar acá: lo que hay es el mecanismo documentado de autenticación por header, y el comportamiento conocido de Next.js con las variables NEXT_PUBLIC_. El resto es criterio de arquitectura, no dato medido.

Si el proyecto ya tiene un caso de key expuesta en producción, esto no alcanza: ahí el paso es revocar, rotar y auditar accesos con las herramientas del proveedor, no leer un post.

flowchart LR
  A[Necesito una API key] --> B{¿Va a un componente cliente?}
  B -->|sí| C[No la pongas ahí. Usá un endpoint server-side]
  B -->|no| D[.env.local + process.env]
  D --> E{¿El repo se va a compartir?}
  E -->|sí| F[Revisá git log por patrones sk-]
  E -->|no| G[Confirmá .gitignore antes del primer commit]

Este mismo criterio de separar lo que corre en servidor de lo que llega al cliente lo toqué desde otro ángulo cuando escribí sobre cache y revalidación en Next.js: la frontera server/client no es solo una cuestión de performance, también es la frontera de qué secretos existen y cuáles no.

FAQ

¿Puedo usar la misma API key de Claude en desarrollo y producción?
Técnicamente sí, pero no es recomendable. Si la key de desarrollo se filtra en un repo o en un log de debug, el radio de daño incluye producción. Usar keys separadas por ambiente limita ese radio.

¿Alcanza con poner la key en .env sin el sufijo .local?
Depende de la configuración exacta del .gitignore del proyecto. El default de Next.js ignora .env*.local, pero un .env plano sin ese sufijo puede no estar cubierto. Conviene verificar el archivo, no asumir.

¿Qué diferencia hay entre manejar la key de Anthropic y la de OpenRouter?
El mecanismo cambia (headers distintos, formatos de key distintos), pero el criterio de manejo es idéntico: nunca en código versionado, nunca en variables públicas del cliente, siempre en variables de entorno server-side.

¿Cline expone las keys que uso con OpenRouter o Anthropic?
Cline las lee desde la configuración local de la extensión o desde variables de entorno del sistema, no las escribe en el código del proyecto. El riesgo aparece si el usuario copia esa key manualmente a un archivo del repo para "tenerla a mano".

¿Sirve rotar la key periódicamente aunque no haya sospecha de filtración?
Es una práctica prudente en cualquier sistema de credenciales, aunque no hay una regla universal de frecuencia. Lo que sí es concreto: si hay sospecha de filtración, la rotación no es periódica, es inmediata.

¿Un archivo .env.example sin valores reales es seguro de versionar?
Sí, siempre que contenga solo los nombres de las variables sin valores reales (ANTHROPIC_API_KEY=). Es una práctica común para documentar qué variables necesita el proyecto sin exponer nada.

Mi postura

No hay atajo legítimo para esto. La excusa de "solo para probar" es la misma excusa que se usa para dejar un console.log que después queda en producción, salvo que acá el costo no es un log molesto: es una key con acceso a facturación de un proveedor de LLM. Si estás armando un proyecto con múltiples providers —algo que toqué cuando hablé de monitorear el tráfico de agentes IA con Sniffnet— la disciplina de variables de entorno separadas por proveedor no es paranoia, es la única forma de que rotar una key no signifique romper las otras tres integraciones que dependen del mismo .env.

El próximo paso concreto, antes de escribir la próxima línea de código que llame a una API de LLM: abrí el .gitignore de tu proyecto y confirmá que efectivamente ignora los archivos de entorno que estás usando. No lo asumas.

Fuente original:

Anthropic API Docs: https://docs.anthropic.com/en/api/getting-started

Este artículo fue publicado originalmente en juanchi.dev

The gap between your Server Action and your UI has a name: setQueryData

Juan Torchia — Tue, 08 Sep 2026 14:30:19 +0000

I wrote a while back about revalidatePath vs revalidateTag in Next.js cache and left a loose thread there on purpose: when a Server Action runs and invalidates the server cache, the client UI — if you're running TanStack Query alongside it — doesn't hear about any of it until the next fetch. There's a window, short but real, where the user is staring at old data while the server already has the new one. That window is today's problem, and it's the piece I skipped last time.

My thesis: revalidateTag and setQueryData aren't competing for the same job, and treating them as interchangeable is where most of this pain comes from. revalidateTag fixes the server's memory of the data. setQueryData fixes what the browser is showing right now. If you only reach for one of them because it's the one that shows up first in the docs you read, you'll ship a UI that's correct eventually and annoying in the meantime.

The concrete problem: two caches that don't talk to each other

Combine Server Actions with TanStack Query on the client and you've got two cache systems running in parallel with zero automatic coupling:

Next.js's cache (fetch cache, Data Cache, Router Cache) — managed by revalidatePath or revalidateTag.
TanStack Query's cache on the client — lives in browser memory, with its own queryKey and its own staleTime.

A Server Action can invalidate the first and leave the second completely untouched. The server already has the updated row, but the component reading it with useQuery keeps showing whatever the last fetch brought back until something triggers a refetch — a window focus, an interval, a navigation. That "until something triggers" is a disguised double fetch: first the Server Action does its job, then — late, on its own schedule — the client query catches up.

What the official docs say (and what they leave out)

TanStack Query's Optimistic Updates guide lays out two paths for updating the UI before the server confirms: use useMutation's onMutate to write directly to the cache with setQueryData, or manage UI state variables without touching the cache at all. The docs are clear on something a lot of people skip anyway: if you write in onMutate, you have to save the previous snapshot with getQueryData and return it in the context so you can roll back on onError. That's not a nice-to-have, it's the contract.

What the docs don't say — because it's not their scope — is how any of this plays with Next.js Server Actions. TanStack Query assumes the mutation is an API call you control from the client through mutationFn. A Server Action isn't that: it's a function that runs on the server and gets invoked as if it were local. The bridge between those two worlds is something you build by hand, and nobody hands you a diagram for it.

// mutation hook that wraps a Server Action
const queryClient = useQueryClient()

const { mutate } = useMutation({
  mutationFn: updateProfile, // Server Action
  onMutate: async (newProfile) => {
    await queryClient.cancelQueries({ queryKey: ['profile'] })
    const previous = queryClient.getQueryData(['profile'])
    queryClient.setQueryData(['profile'], newProfile) // optimistic update
    return { previous }
  },
  onError: (_err, _vars, context) => {
    queryClient.setQueryData(['profile'], context?.previous) // rollback
  },
  onSettled: () => {
    queryClient.invalidateQueries({ queryKey: ['profile'] })
  },
})

The onSettled with invalidateQueries is the safety net: no matter what happens, it ends up syncing with whatever the server actually returns. The setQueryData in onMutate is the part that buys you the feeling of instantaneousness — nothing more, nothing less.

Where people get it wrong

The recipe I keep seeing repeated — in forums, in example repos, in Next.js's own App Router scaffolding — is trusting everything to revalidateTag inside the Server Action and assuming "since the server already revalidated, the client will just find out on its own." That works fine if the component showing the data does a direct fetch inside a Server Component and the user navigates or refreshes. It stops working the moment that same data also lives in a TanStack query inside a Client Component, because revalidateTag has zero notion that there's a queryClient sitting in the browser waiting for news.

The hidden cost is the feeling of lag: the user clicks "save," watches the spinner disappear, and the value on screen takes one or two seconds — or until the next window focus — to catch up. It's not a bug that breaks anything. It's a perception friction, and it's exactly the kind of thing users describe as "sometimes it takes a while to save" without being able to point at why.

The counterexample worth keeping around: if the data you're updating is not read afterward with useQuery on the client — say, a Server Action that just fires a side effect and the page re-renders server-side on the next navigation — then setQueryData doesn't add anything. There, revalidatePath or revalidateTag alone are enough, and dragging TanStack Query into it is complexity with no payoff.

sequenceDiagram
  participant U as User
  participant C as Client (TanStack Query)
  participant S as Server Action
  U->>C: Click save
  C->>C: setQueryData (optimistic)
  C->>S: invoke Server Action
  S->>S: revalidateTag / DB mutation
  S-->>C: response (success or error)
  alt error
    C->>C: rollback with previous snapshot
  else success
    C->>C: invalidateQueries (onSettled)
  end

Decision checklist

Situation	What to check first	Decision
Data is read with `useQuery` in a Client Component and the user needs immediate feedback	Is there a real risk of the mutation failing often?	`setQueryData` in `onMutate` + rollback in `onError`
Data is only shown in Server Components and the page re-renders on the next navigation	Is there any `useQuery` reading that same `queryKey`?	`revalidateTag`/`revalidatePath` alone, no TanStack
The mutation touches data other users also see (collaborative)	Could optimism show a state that never existed for the server?	Prefer `invalidateQueries` without optimism, accept the delay
The form is high-frequency (autosave, likes, counters)	Is a visible rollback's cost acceptable?	`setQueryData` is nearly mandatory so it doesn't feel stuck
You're debugging why "sometimes it doesn't update"	Is `onSettled` with `invalidateQueries` missing?	Always add it, it's the safety net

This isn't a table of universal truths, it's a starting point for deciding with judgment based on how critical it is that the optimistic data actually match reality.

Limits of this

I don't have my own perceived-latency metrics or an A/B experiment comparing "with setQueryData" against "without it" on a real production case, and I'm not going to fake having one. What I can back up is what the official docs describe as the pattern's contract: snapshot, update, conditional rollback, final invalidation. If you need to quantify the real impact on user experience, that requires interaction logging or testing with actual users, not a blog post.

It's not a free pattern either. Every optimistic setQueryData is a promise your code makes to the UI about how the state is going to end up, and if that promise fails often — because the Server Action rejects the mutation on business validation, not a network hiccup — the rollback becomes visible and annoying. In mutations with a high rejection rate, optimism generates more visual noise than it saves. That's the trade-off I'm not willing to pretend doesn't exist just to make the pattern sound universally good.

When to use it and when not

My take after sitting with this: use setQueryData when the data lives on the client via useQuery and perceived latency matters more than momentary accuracy. Don't use it when the data is shared between users or when a visible rollback would be worse than a small delay. And always, no exceptions, close the loop with invalidateQueries in onSettled — optimism without a safety net is just a bug waiting for the wrong moment to show up.

If you've read about how Cline puts limits on autonomous mode you'll recognize the same logic here: automating without control is a promise that gets paid for eventually, one way or another. The next practical step, if you're using this pattern, is instrumenting how many times the rollback actually fires in development — not production yet, just to get a real number on the mutation's failure rate before deciding whether optimism earns its place in that specific case.

FAQ

Does setQueryData replace revalidateTag?
No. They solve different things: revalidateTag invalidates the server's cache (Next.js), setQueryData updates the client's cache (TanStack Query). In a flow with both systems, you probably need both.

What happens if I don't roll back in onError?
The client's cache ends up holding data that never existed on the server. The next refetch self-corrects it, but in the meantime the user is looking at false information.

Can I use this with React's useOptimistic instead of TanStack Query?
Yes, they're different tools for similar needs. useOptimistic lives in the component and has no notion of a cache shared across queries; setQueryData does, because it operates on the global queryClient.

Does this add latency or reduce it?
It doesn't change the mutation's real latency. It changes the perceived latency: the UI reacts before the server confirms.

Does it work for data coming from a Server Component without useQuery?
No. If there's no TanStack Query query reading that queryKey on the client, setQueryData has nothing to update.

Do I still need to invalidate if the optimism already showed the correct data?
Yes. The invalidateQueries in onSettled isn't redundant: it's what guarantees that if the server returned something different from what you assumed, the client corrects itself.

Original source: https://tanstack.com/query/latest/docs/framework/react/guides/optimistic-updates
The Server Action resolves, the toast says "saved," and the UI still shows the old data for a beat. That beat is the gap setQueryData closes without waiting for the full server roundtrip — and it's not the same fix as revalidateTag, even though people keep treating it that way.
TanStack Query + Server Actions: invalidation without
setQueryData invalidation pattern after Server Actions in Next.js: when to use it over revalidateTag, a checklist, and the limits per TanStack Query docs.

This article was originally published on juanchi.dev

setQueryData después de una Server Action: el patrón que cierra el gap

Juan Torchia — Tue, 08 Sep 2026 14:30:14 +0000

Escribí hace poco sobre revalidatePath vs revalidateTag en el cache de Next.js y me quedó una fricción que no resolví ahí: cuando la Server Action se ejecuta y el cache del server queda invalidado, la UI del cliente — si usás TanStack Query en paralelo — no se entera de nada hasta el próximo fetch. Hay un instante, corto pero real, donde el usuario ve el dato viejo mientras el server ya tiene el nuevo. Ese instante es el problema de hoy.

Mi tesis es simple: cuando necesitás que la UI reaccione en el momento — no en el próximo render, no después de que Next revalide su propio cache — invalidar manualmente con queryClient.setQueryData después de la Server Action gana contra confiar solo en revalidateTag. No porque revalidateTag esté mal. Porque resuelve un problema distinto: el cache del server, no el cache del cliente.

Lo digo así de directo porque es la parte que casi nadie deja explícita cuando combina las dos cosas: revalidateTag y setQueryData no compiten, viven en capas distintas, y confundirlas es lo que genera ese "a veces tarda en guardar" que nadie sabe explicar.

El problema concreto: dos caches que no se hablan

Cuando combinás Server Actions con TanStack Query en el cliente, tenés dos sistemas de cache corriendo en paralelo y sin acoplamiento automático:

El cache de Next.js (fetch cache, Data Cache, Router Cache) — lo maneja revalidatePath o revalidateTag.
El cache de TanStack Query en el cliente — vive en memoria del browser, con sus propias queryKey y su propio staleTime.

Una Server Action puede invalidar perfectamente el primero y dejar el segundo intacto. El resultado: el server ya tiene el dato actualizado, pero el componente que lee con useQuery sigue mostrando lo que trajo el último fetch, hasta que algo dispare un refetch — un focus de ventana, un intervalo, una navegación. Ese "hasta que algo dispare" es el doble fetch disimulado: primero la Server Action, después — tarde — la query del cliente se pone al día.

Qué dice la documentación oficial (y qué no dice)

La guía de Optimistic Updates de TanStack Query plantea dos caminos para actualizar la UI antes de que el server confirme: usar el onMutate de useMutation para escribir directo en el cache con setQueryData, o usar variables de estado UI sin tocar el cache. La doc es clara en algo que muchos se saltan: si escribís en onMutate, tenés que guardar el snapshot anterior con getQueryData y devolverlo en el context para poder hacer rollback en onError. No es opcional, es parte del contrato del patrón.

Lo que la doc no dice — porque no es su tema — es cómo se combina esto con Server Actions de Next.js. TanStack Query asume que la mutación es una llamada a una API que vos controlás desde el cliente con mutationFn. Una Server Action no es eso: es una función que corre en el server y se invoca como si fuera local. El puente entre los dos mundos hay que armarlo a mano, y ahí está el punto ciego que este post trata de cerrar.

// hook de mutación que envuelve una Server Action
const queryClient = useQueryClient()

const { mutate } = useMutation({
  mutationFn: actualizarPerfil, // Server Action
  onMutate: async (nuevoPerfil) => {
    await queryClient.cancelQueries({ queryKey: ['perfil'] })
    const anterior = queryClient.getQueryData(['perfil'])
    queryClient.setQueryData(['perfil'], nuevoPerfil) // update optimista
    return { anterior }
  },
  onError: (_err, _vars, context) => {
    queryClient.setQueryData(['perfil'], context?.anterior) // rollback
  },
  onSettled: () => {
    queryClient.invalidateQueries({ queryKey: ['perfil'] })
  },
})

El onSettled con invalidateQueries es la red de seguridad: pase lo que pase, se termina sincronizando con lo que devuelve el server. El setQueryData en onMutate es la parte que le da a la UI la sensación de instantaneidad.

Dónde se equivoca la gente

La receta común que veo repetida — en foros, en proyectos de ejemplo, en el propio scaffolding de Next.js con App Router — es confiar todo a revalidateTag dentro de la Server Action y asumir que "como el server ya revalidó, el cliente se va a enterar solo". Funciona si el componente que muestra el dato hace fetch directo dentro de un Server Component y el usuario navega o refresca. No funciona igual si ese mismo dato también vive en una query de TanStack en un Client Component, porque revalidateTag no tiene ninguna noción de que existe un queryClient corriendo en el browser.

El costo oculto es la sensación de lag: el usuario hace clic en "guardar", ve el spinner desaparecer, y el valor en pantalla tarda uno o dos segundos — o hasta el próximo focus de la ventana — en reflejar el cambio. No es un bug que rompa nada. Es una fricción de percepción, y esas son las que un usuario reporta como "a veces tarda en guardar" sin poder señalar por qué.

El contraejemplo que vale la pena tener en la cabeza: si el dato que estás actualizando no se lee después con useQuery en el cliente — por ejemplo, una Server Action que solo dispara un efecto y la página se re-renderiza server-side en la siguiente navegación — entonces setQueryData no aporta nada. Ahí revalidatePath o revalidateTag solos alcanzan, y meter TanStack Query es complejidad sin beneficio.

sequenceDiagram
  participant U as Usuario
  participant C as Cliente (TanStack Query)
  participant S as Server Action
  U->>C: Click guardar
  C->>C: setQueryData (optimista)
  C->>S: invoca Server Action
  S->>S: revalidateTag / mutación en DB
  S-->>C: respuesta (éxito o error)
  alt error
    C->>C: rollback con snapshot anterior
  else éxito
    C->>C: invalidateQueries (onSettled)
  end

Checklist de decisión

Situación	Qué mirar primero	Decisión
El dato se lee con `useQuery` en un Client Component y el usuario necesita feedback inmediato	¿Hay riesgo real de que la mutación falle seguido?	`setQueryData` en `onMutate` + rollback en `onError`
El dato solo se muestra en Server Components y la página se re-renderiza en la próxima navegación	¿Hay algún `useQuery` leyendo esa misma `queryKey`?	`revalidateTag`/`revalidatePath` solos, sin TanStack
La mutación toca datos que otros usuarios también ven (colaborativo)	¿El optimismo puede mostrar un estado que nunca existió para el server?	Preferir `invalidateQueries` sin optimismo, aceptar el delay
El formulario es de alta frecuencia (autoguardado, likes, contadores)	¿El costo de un rollback visible es aceptable?	`setQueryData` es casi obligatorio para que no se sienta trabado
Estás debuggeando por qué "a veces no se actualiza"	¿Falta `onSettled` con `invalidateQueries`?	Agregarlo siempre, es la red de seguridad

Esto no es una tabla de verdades universales, es un punto de partida para decidir con criterio según qué tan crítico es que el dato optimista coincida con la realidad.

Límites de esto

No tengo métricas propias de latencia percibida ni un experimento A/B que compare "con setQueryData" contra "sin él" en un caso productivo real — y no voy a inventarlas. Lo que puedo sostener es lo que la documentación oficial describe como contrato del patrón: snapshot, update, rollback condicional, invalidación final. Si necesitás cuantificar el impacto real en la experiencia de usuario, eso requiere logging de interacción o testing con usuarios reales, no algo que se resuelva leyendo un post.

Tampoco es un patrón gratis. Cada setQueryData optimista es una promesa que tu código le hace a la UI sobre cómo va a quedar el estado, y si esa promesa falla seguido — porque la Server Action rechaza la mutación por validación de negocio, no por error de red — el rollback se vuelve visible y molesto. En mutaciones con alta tasa de rechazo, el optimismo genera más ruido visual que el que ahorra. Ese es el trade-off que me parece honesto: optimismo a cambio de un rollback que a veces se ve feo.

Cuándo usarlo y cuándo no

Mi postura después de mirar la doc con este caso en la cabeza: usá setQueryData cuando el dato vive en el cliente vía useQuery y la latencia percibida importa más que la exactitud momentánea. No lo uses cuando el dato es compartido entre usuarios o cuando un rollback visible sería peor que un pequeño delay. Y siempre, sin excepción, cerrá el ciclo con invalidateQueries en onSettled — el optimismo sin red de seguridad es solo un bug esperando el momento equivocado para aparecer.

Si venís de leer sobre cómo Cline pone límites al modo autónomo vas a reconocer la misma lógica acá: automatizar sin control es una promesa que en algún momento se paga. El próximo paso lógico, si trabajás con este patrón, es instrumentar cuántas veces el rollback se dispara en desarrollo — no en producción todavía, solo para entender la tasa de fallo real de la mutación antes de decidir si el optimismo vale la pena en ese caso puntual.

Lo incómodo que dejo sobre la mesa: si tu mutación falla más de una vez cada diez intentos en desarrollo, el optimismo no es una mejora de UX, es una fuente nueva de bugs de percepción. Medí eso antes de copiar el patrón.

FAQ

¿setQueryData reemplaza a revalidateTag?
No. Resuelven cosas distintas: revalidateTag invalida el cache del server (Next.js), setQueryData actualiza el cache del cliente (TanStack Query). En un flujo con ambos sistemas, probablemente necesités los dos.

¿Qué pasa si no hago rollback en onError?
El cache del cliente queda con un dato que nunca existió en el server. La próxima vez que algo dispare un refetch se corrige solo, pero mientras tanto el usuario ve información falsa.

¿Puedo usar esto con useOptimistic de React en vez de TanStack Query?
Sí, son herramientas distintas para necesidades parecidas. useOptimistic vive en el componente y no tiene noción de cache compartido entre queries; setQueryData sí, porque opera sobre el queryClient global.

¿Esto agrega latencia o la reduce?
No cambia la latencia real de la mutación. Cambia la latencia percibida: la UI reacciona antes de que el server confirme.

¿Sirve para datos que vienen de un Server Component sin useQuery?
No. Si no hay una query de TanStack Query leyendo esa queryKey en el cliente, setQueryData no tiene nada para actualizar.

¿Hace falta invalidar igual si el optimismo ya mostró el dato correcto?
Sí. El invalidateQueries en onSettled no es redundante: es lo que garantiza que si el server devolvió algo distinto de lo que asumiste, el cliente se corrige.

Fuente original: https://tanstack.com/query/latest/docs/framework/react/guides/optimistic-updates

Este artículo fue publicado originalmente en juanchi.dev

fp-ts Alternatives in TypeScript: When the Abstraction Is Worth It

Juan Torchia — Tue, 08 Sep 2026 12:00:21 +0000

Last week I wrote about functional programming with TypeScript and what fp-ts teaches you and I landed on a conclusion that left me comfortable but not fully settled: a native union type with a couple of helper functions solves eighty percent of the cases where someone reaches for Either. The comment I got most was some version of "so fp-ts is useless." That's when I realized I'd left the door half-closed, and I want to close it properly here.

My thesis for this post: fp-ts isn't useless, it's just misapplied most of the time. It solves one specific problem — composing errors from multiple independent sources without the code collapsing into nested ifs — and that problem shows up far less often than the number of Either imports I see in random codebases would suggest.

fp-ts alternatives typescript: the question I actually ask

Before I bring fp-ts into a project, I don't think about type safety or elegance. I count. How many independent failure points do I need to combine in a single operation? One or two, a union type covers it and anyone on the team reads the flow in one pass. Five validations that can each fail on their own, where I need every error and not just the first one that blew up — that's where Either and its combinators start paying for the learning cost they demand.

That count is the whole decision for me. It's not a matter of taste or which paradigm you like more. Below three independent failure points, fp-ts is vocabulary without payoff. At three or more, with accumulation as a requirement, a union type forces you to hand-roll the exact machinery fp-ts already built.

What the official source says and doesn't say

The fp-ts GitHub repo presents itself as a library for "typed functional programming in TypeScript," with implementations of structures like Option, Either, TaskEither, and composition utilities like pipe plus the Monad, Applicative, and Functor instances for each of those types.

What the docs don't say — because that's not their job — is when it's worth using in a real project. That's a team decision, not a property of the library. The source gives you the tool and the typed contract; it doesn't tell you whether your problem actually has the shape that needs it. That's exactly where most arguments I've seen online get stuck: people debate syntax when they should be debating whether the problem even qualifies.

Where people get it wrong: the recipe I keep seeing repeated

The common recipe: someone reads about Either, likes the type safety, and installs it as the default for any function that might fail. A parseInt that can return NaN. A database query that might not find a row. A fetch that might throw a 404. All wrapped in Either<Error, T>, with pipe, chain, and fold at every link in the chain.

The hidden cost doesn't show up in the file the person who wrote it opens. It shows up when another team member — someone who doesn't live in the functional paradigm every day — has to read that chain to fix a bug. They have to understand what a Functor is, why chain isn't the same as map, and why the error stays "trapped" until someone unwraps it with fold. That reading cost is real, and type safety doesn't make up for it if the underlying problem was simple to begin with.

The counterexample that does justify the investment looks different: a form with fifteen fields, each with its own validation, where what you need to show the user is the complete list of errors, not just the first one that failed. There, Either combined with Applicative — which lets you accumulate instead of short-circuiting on the first error — solves something a native union type can't solve without hand-reinventing the wheel.

// composed validation pipeline, the case where fp-ts earns its cost
import { pipe } from "fp-ts/function"
import * as E from "fp-ts/Either"

const validarEmail = (email: string): E.Either<string, string> =>
  email.includes("@") ? E.right(email) : E.left("email invalido")

const validarEdad = (edad: number): E.Either<string, number> =>
  edad >= 18 ? E.right(edad) : E.left("edad insuficiente")

// sequenceT or Apply let you accumulate errors from both validations
// instead of short-circuiting as soon as the first one fails

Decision matrix: when yes, when no

This isn't a table of absolute truths. It's the criterion I apply before choosing, and it depends heavily on the team that has to maintain the code afterward.

Use it if: you need to combine three or more independent validations and you need the full set of errors, not just the first.
Use it if: the team already has prior experience with functional programming and the vocabulary isn't an entry barrier.
Avoid it if: the flow has a single failure point that a plain if or a two-to-three-variant union type can handle.
Avoid it if: the project has a short lifespan or the team rotates often — the learning curve doesn't pay off in time.
Check first: how many people on the team are going to touch that file in the coming months. It's the question that weighs heaviest in my actual decision.

I apply this same "the abstraction pays off when the problem has a composite shape" logic elsewhere. When I wrote about revalidatePath vs revalidateTag in Next.js, the point was similar: the finer-grained tool wins when the use case has real granularity, and loses when brute force already does the job.

The limits of this comparison

I don't have an experiment measuring onboarding time between teams that use fp-ts and teams that don't. There's no performance benchmark between Either and a union type — for the typical case, the runtime difference is irrelevant because both are lightweight structures with no real overhead. What I have is a readability criterion based on the shape of the problem, not a productivity measurement, and I'm not going to dress it up as more than that.

I also can't claim fp-ts is "better" or "worse" in absolute terms: that depends on the team, on people turnover, and on how much prior experience the group has with functional programming. If someone wants an answer that doesn't depend on context, they won't find it here — and I'd be suspicious of any post that offers one without data.

FAQ

Is fp-ts still useful in 2025 or has native TypeScript replaced it?
It's still useful for the specific case of composing multiple errors. Native TypeScript with union types covers most simple cases, but it doesn't replace the accumulation combinators fp-ts already has solved.

What's the simplest alternative to fp-ts's Either?
A union type like { ok: true, value: T } | { ok: false, error: E }, combined with your own helper functions for map and chain if you need them. Covers simple validations without the extra vocabulary.

Does fp-ts perform better than handling errors with try/catch?
There's no public evidence of a relevant performance difference between the two approaches for a typical application case. The decision should be based on readability and problem shape, not speed.

Is it worth learning fp-ts if I've never used functional programming?
Depends on the project. If the team doesn't have that foundation and the problem doesn't demand composing multiple errors, the learning curve probably won't pay off in time.

What replaces fp-ts's Option?
A T | null or T | undefined type with the narrowing functions TypeScript already provides. For the "value may or may not exist" case, native language features are almost always enough.

In which projects would you recommend fp-ts from day one?
In form or input-data validation pipelines with multiple independent rules, where you need to show all the errors found and the team already knows the paradigm.

My final take

I'm not going to recommend fp-ts as the default for a new project, and I think most posts that do are optimizing for showing off the type system instead of solving the actual problem in front of them. I'll recommend it when the problem has the shape the library solves better than anything else: composed validation with error accumulation. Outside of that case, a native union type is more readable for whoever opens the file next, and that person is almost never the one who wrote it.

If you're weighing this on a real project, the exercise is concrete: count how many independent failure points the function you're writing has. One or two, stick with native. Three or more with a need to accumulate, that's when you open the door to fp-ts — and accept upfront that the team is going to take a while to get used to it. That trade-off, I think, is honest. Pretending there's no cost isn't.

Original source:

fp-ts GitHub: https://github.com/gcanti/fp-ts

This article was originally published on juanchi.dev

fp-ts alternativas en TypeScript: cuándo vale la abstracción

Juan Torchia — Tue, 08 Sep 2026 12:00:16 +0000

La semana pasada escribí sobre functional programming con TypeScript y lo que fp-ts enseña y llegué a una conclusión que me dejó cómodo pero no del todo tranquilo: un union type nativo con un par de funciones helper resuelve el ochenta por ciento de los casos donde alguien mete Either. El comentario que más recibí fue una variante de "entonces fp-ts no sirve para nada". Y ahí me di cuenta de que había dejado la puerta mal cerrada.

Mi tesis es esta: fp-ts no es una librería de "manejo de errores", es una librería para componer errores que vienen de fuentes distintas, en cantidad, sin que el código se convierta en una pirámide de ifs anidados. Si tu problema no tiene esa forma, la librería te agrega vocabulario sin agregarte claridad, y en ese caso estás pagando un peaje que no corresponde.

fp-ts alternativas typescript: el criterio que uso primero

Antes de meter fp-ts en un proyecto me hago una sola pregunta: ¿cuántos puntos de falla independientes tengo que combinar en una sola operación? Si la respuesta es uno o dos, un union type alcanza y no discuto más. Si la respuesta es "cinco validaciones que pueden fallar cada una por su cuenta y necesito acumular todos los errores, no solo el primero", ahí Either y sus combinadores empiezan a pagar su costo de aprendizaje.

Esa pregunta separa dos mundos. En el primero, alguien lee el código una vez y entiende el flujo. En el segundo, sin una abstracción que componga, terminás con un anidamiento de validaciones que nadie quiere tocar seis meses después — y lo digo porque ese código de "nadie quiere tocar" es el que después te toca a vos arreglar un viernes a las seis.

Qué dice la fuente oficial y qué no dice

El repo de fp-ts en GitHub se presenta como una librería de "typed functional programming in TypeScript", con implementaciones de estructuras como Option, Either, TaskEither y utilidades de composición como pipe y las instancias de Monad, Applicative y Functor para cada uno de esos tipos.

Lo que la documentación no dice — porque no es su trabajo decirlo — es cuándo conviene usarla en un proyecto real. Eso es una decisión de equipo, no una propiedad de la librería. La fuente te da la herramienta y el contrato tipado; no te dice si tu problema la necesita. Esa parte queda para quien diseña el sistema, y ahí es donde la mayoría de las discusiones que veo se quedan trabadas: la gente debate sintaxis cuando debería estar debatiendo si el problema tiene la forma que la herramienta resuelve.

Dónde se equivoca la gente: la receta que veo repetida

La receta común es: alguien lee sobre Either, le gusta la seguridad de tipos, y lo instala como default en cualquier función que pueda fallar. Un parseInt que puede devolver NaN. Una consulta a la base que puede no encontrar una fila. Un fetch que puede tirar 404. Todo envuelto en Either<Error, T>, con pipe, chain y fold en cada punto de la cadena.

El costo oculto no aparece en el archivo que escribe esa persona. Aparece cuando otro miembro del equipo — uno que no vive en el paradigma funcional todos los días — tiene que leer esa cadena para arreglar un bug. Tiene que entender qué es un Functor, por qué chain no es lo mismo que map, y por qué el error queda "atrapado" hasta que alguien lo desenvuelve con fold. Ese costo de lectura es real y no lo compensa la seguridad de tipos si el problema de fondo era simple. Lo incómodo de decir esto en voz alta es que a mí también me pasó: instalé Either en un lugar donde un if bastaba, solo porque lo había leído la semana anterior y quería usarlo.

El contraejemplo que sí justifica la inversión es distinto: un formulario con quince campos, cada uno con su propia validación, donde el resultado que necesitás mostrar al usuario es la lista completa de errores, no solo el primero que falló. Ahí Either combinado con Applicative — que permite acumular en vez de cortar en el primer error — resuelve algo que un union type nativo no resuelve sin reinventar la rueda a mano.

// pipeline de validacion compuesta, el caso donde fp-ts paga su costo
import { pipe } from "fp-ts/function"
import * as E from "fp-ts/Either"

const validarEmail = (email: string): E.Either<string, string> =>
  email.includes("@") ? E.right(email) : E.left("email invalido")

const validarEdad = (edad: number): E.Either<string, number> =>
  edad >= 18 ? E.right(edad) : E.left("edad insuficiente")

// sequenceT o Apply permiten acumular errores de ambas validaciones
// en vez de cortar apenas la primera falla

Matriz de decisión: cuándo sí, cuándo no

Esto no es una tabla de verdades absolutas. Es el criterio que aplico antes de elegir, y depende del equipo que tenga que mantener el código después.

Usalo si: hay que combinar tres o más validaciones independientes y necesitás el conjunto completo de errores, no el primero.
Usalo si: el equipo ya tiene experiencia previa con programación funcional y el vocabulario no es una barrera de entrada.
Evitalo si: el flujo tiene un solo punto de falla que se puede resolver con un if o un union type de dos o tres variantes.
Evitalo si: el proyecto es de vida corta o el equipo rota seguido — la curva de aprendizaje no se amortiza.
Mirá primero: cuántas personas del equipo van a tocar ese archivo en los próximos meses. Es la pregunta que más pesa en mi decisión real.

Esta misma lógica de "la abstracción paga cuando el problema tiene forma compuesta" la aplico en otros lados. Cuando escribí sobre revalidatePath vs revalidateTag en Next.js, el punto era parecido: la herramienta más fina gana cuando el caso de uso tiene granularidad real, y pierde cuando la fuerza bruta ya alcanza.

Los límites de esta comparación

No tengo un experimento propio con métricas de tiempo de onboarding entre equipos que usan fp-ts y equipos que no — si alguna vez lo corro, lo publico con números. No hay benchmark de performance entre Either y un union type que valga citar: para el caso típico, la diferencia de runtime es irrelevante porque ambos son estructuras livianas sin overhead real. Lo que tengo es un criterio de legibilidad basado en la forma del problema, no una medición productiva, y prefiero decirlo así en vez de disfrazarlo de dato.

Tampoco voy a afirmar que fp-ts sea "mejor" o "peor" en términos absolutos: depende del equipo, de la rotación de personas y de cuánta experiencia previa tenga el grupo con programación funcional. Si alguien busca una respuesta que no dependa del contexto, no la va a encontrar acá — y yo directamente desconfiaría de cualquier post que la ofrezca sin mostrar de dónde saca el número.

FAQ

¿fp-ts sigue siendo útil en 2025 o quedó reemplazado por TypeScript nativo?
Sigue siendo útil para el caso específico de composición de errores múltiples. TypeScript nativo con union types cubre la mayoría de los casos simples, pero no reemplaza los combinadores de acumulación que fp-ts ya trae resueltos.

¿Cuál es la alternativa más simple a Either de fp-ts?
Un union type del estilo { ok: true, value: T } | { ok: false, error: E }, combinado con funciones helper propias para map y chain si hacen falta. Cubre validaciones simples sin el vocabulario adicional.

¿fp-ts tiene mejor performance que manejar errores con try/catch?
No hay evidencia pública de una diferencia de performance relevante entre ambos enfoques para el caso típico de una aplicación. La decisión debería basarse en legibilidad y forma del problema, no en velocidad.

¿Vale la pena aprender fp-ts si nunca usé programación funcional?
Depende del proyecto. Si el equipo no tiene esa base y el problema no exige composición de errores múltiples, la curva de aprendizaje probablemente no se amortiza a tiempo.

¿Qué reemplaza a Option de fp-ts?
Un tipo T | null o T | undefined con las funciones de narrowing que TypeScript ya ofrece. Para el caso de "puede haber o no un valor", el lenguaje nativo alcanza casi siempre.

¿En qué proyectos SÍ recomendarías fp-ts desde el día uno?
En pipelines de validación de formularios o datos de entrada con múltiples reglas independientes, donde necesitás mostrar todos los errores encontrados y el equipo ya conoce el paradigma.

Mi postura final

No voy a recomendar fp-ts como default en un proyecto nuevo. Punto. Lo voy a recomendar cuando el problema tenga la forma que la librería resuelve mejor que cualquier otra cosa: validación compuesta con acumulación de errores. Fuera de ese caso, un union type nativo es más legible para el próximo que abra el archivo, y esa persona casi nunca es la misma que lo escribió — a veces ni siquiera es la misma versión de vos, seis meses después.

Si estás evaluando esta decisión en un proyecto real, el ejercicio concreto es simple: contá cuántos puntos de falla independientes tiene la función que estás escribiendo. Uno o dos, seguí con lo nativo, sin culpa. Tres o más con necesidad de acumular, ahí abrí la puerta a fp-ts — y aceptá de una que el equipo va a tardar en acostumbrarse, porque esa parte no se salta.

Fuente original:

fp-ts GitHub: https://github.com/gcanti/fp-ts

Este artículo fue publicado originalmente en juanchi.dev

Sniffnet: How Much Traffic Are My AI Agents Generating Behind My Back

Juan Torchia — Mon, 07 Sep 2026 12:00:19 +0000

I have Cline open in VS Code almost all day. In the background, it fires off calls to model APIs, makes requests I never triggered by hand, and — I assume — keeps connections alive while it's "thinking." I never looked at this from the network layer. I check app logs, I check the agent's output, but I never opened a sniffer to see the actual packets leaving my machine while I've got three or four AI tools running at the same time.

That's the concrete friction here: I use AI agents every day and I have zero idea how much "silent" traffic they generate. Not how much the tokens cost me — that I see on each provider's dashboard — but how much actual network traffic crosses my interface while Cline is "thinking" or while some extension is polling.

My thesis is simple, and it's not some grandiose revelation: we don't know how much background traffic our AI agents generate until we look at it with a dedicated tool, and sometimes it's surprising. Not because the traffic is suspicious — it's because we simply never look, period. And that ignorance has a cost later when you want to diagnose weird latency, understand why the agent "takes forever," or just know which processes are talking to which endpoints.

Sniffnet as a Network Traffic Monitoring Tool

Sniffnet is an open source tool written in Rust that analyzes network traffic in real time and shows it with a graphical interface, so you don't have to read raw tcpdump output. According to its repo, it lets you pick a network interface, filter by application, protocol, or IP address, and view live incoming and outgoing traffic graphs.

What the repo says, and what matters to me for this experiment:

It's cross-platform (Linux, macOS, Windows).
It uses pcap under the hood, so it needs elevated permissions to capture packets on the real interface.
It identifies the process or app tied to each connection on some systems, which is exactly what I need to separate "this is Cline" from "this is the browser with fifteen tabs open."
It's not an IDS or a firewall. It doesn't block anything, doesn't alert on anomalies with its own logic. It's passive observability.

What the repo does NOT say, and what's worth knowing before installing it: it doesn't promise to decrypt TLS traffic, it doesn't show you the content of the HTTPS requests LLM APIs make, and it doesn't correlate traffic with token cost or model latency. Sniffnet sees bytes and connections. It doesn't see semantics.

# installation via cargo (needs Rust installed)
cargo install sniffnet

# on Linux, grant capture permissions without running as root
sudo setcap cap_net_raw,cap_net_admin=eip $(which sniffnet)

# run it
sniffnet

That spins up the graphical interface, asks you to pick the active network interface (wifi or ethernet), and starts graphing real-time traffic.

Where People Get These Numbers Wrong

The common recipe is: you install a monitoring tool, you see a traffic spike, you assume "something's wrong" or "the agent's eating way more than expected," and you draw a conclusion without context.

The hidden cost of that recipe is twofold. First, a traffic spike in a five-minute capture session doesn't tell you if that's normal, if it's an isolated case, or if it depends on what the agent was doing at that exact moment — was it uploading context from a large file? Downloading a model? Just keeping a keep-alive alive? Without that context, the number is noise wearing a data costume.

Second, and more important: TCP/IP doesn't distinguish "useful traffic" from "protocol traffic." You see bytes going back and forth, but separating how much is actual LLM call payload versus connection overhead, retries, or polling from some extension that has nothing to do with AI requires looking at finer granularity — filtering by process, by port, by destination IP — something Sniffnet allows but demands active work from whoever's looking. It doesn't come pre-solved.

The classic counterexample: someone runs Sniffnet, sees their editor with AI extensions generating constant traffic even when they're not typing code, and concludes "the agent is doing something weird in the background." It could be extension telemetry, a connection heartbeat, or just the editor syncing config to the cloud — nothing related to the AI agent itself. The tool hands you the raw data. The correct interpretation is something you have to earn.

Decision Matrix: When to Use Sniffnet for This

Situation	Use Sniffnet	Avoid it / use something else
You want to see which processes generate network traffic on your machine in real time	Yes, that's exactly what it's for	—
You need to know how much specific HTTPS traffic an LLM API makes	Partial: you see bytes and destination, not content	For that you need the tool's own logs (Cline exposes its activity in the VS Code panel)
You want to decide if your AI agent "consumes too much" in production	No, a single observation session isn't enough	You need aggregated metrics over time, not a one-off capture
You're trying to diagnose why a connection drops or lags	Yes, useful for seeing retries or drops	—
You need an IDS with automatic alert rules	Not its function	Tools like Suricata or Zeek are built for that
You want to understand the general traffic pattern of your dev setup (Cline + terminal + browser)	Yes, filtering by process lets you separate each source	—

What I'd check first, before drawing any conclusion: which processes show up in the active connections list when the agent is idle (not processing anything) versus when you throw it a big refactor task. That comparison — idle vs. active — tells you more than staring at one isolated number.

If you're already running Cline in autopilot mode with defined limits, this kind of network observation is a reasonable complement: it doesn't replace the autonomy limits you set on the agent, but it gives you visibility from an angle that's usually ignored — the network layer, not the agent's behavior layer.

flowchart LR
  A[Cline running] --> B{Active task}
  B -->|yes| C[LLM API call]
  B -->|no| D[Possible keep-alive or polling]
  C --> E[Sniffnet: see bytes and destination]
  D --> E
  E --> F{Known context?}
  F -->|yes| G[Valid conclusion]
  F -->|no| H[Needs more capture sessions]

Limits: What This Evidence Doesn't Let You Conclude

I have to be honest about what Sniffnet, used in a single observation session, can and can't give you:

You can't conclude how much traffic "is normal" without a series of repeated measurements across different use scenarios. A one-off capture is a data point, not a trend.
You can't separate AI traffic from other tools' traffic just from the general graph. You need to filter by process or port, and that depends on the OS exposing that association correctly — in some containerized environments or with a VPN, the process-connection association gets lost.
It doesn't measure token cost or model latency. Network bytes and LLM tokens are different magnitudes: a short request in bytes can represent a long, expensive prompt, and vice versa.
It doesn't replace application logs. If you want to know exactly which call to which endpoint corresponds to which agent action, the source of truth is the tool's log (Cline, the LLM provider's CLI), not the network sniffer.
A single capture session isn't a reproducible experiment in the strict sense. To draw a conclusion worth publishing you'd need to repeat the observation under comparable conditions, something this post doesn't do and doesn't claim to.

That said: the point of installing the tool isn't to get a final figure, it's to open up a layer we normally never look at. I already went down something similar when I compared pnpm and npm on install friction or when I questioned how cheap an agent like DeepSeek Reasonix actually is in practice: the habit of looking closely at things we use every day but never actually examined.

FAQ

Does Sniffnet need admin permissions?
Yes, because it uses pcap to capture packets at the network interface level. On Linux you can grant specific permissions with setcap instead of running it as root directly, which is the recommended approach for security.

Can Sniffnet see the content of my conversations with an LLM?
No. Traffic between Cline (or any client) and an LLM API goes encrypted via TLS. Sniffnet sees that there's a connection, which IP or domain it's going to, how many bytes get transferred — not the payload content.

Is it useful for measuring how much I spend on tokens?
Not directly. Network bytes don't equal LLM tokens. For actual token cost you need to check the provider's dashboard or the usage logs of whatever tool you're using.

Is it better than Wireshark for this case?
Depends on your goal. Wireshark has more protocol analysis depth and is the standard for advanced diagnostics. Sniffnet aims for a quicker, more visual read of the overall traffic picture by application, without Wireshark's learning curve.

Can I use Sniffnet on macOS or only on Linux?
It's cross-platform: supports Linux, macOS, and Windows according to the project's GitHub documentation.

Does this replace real observability in a production system?
No. It's a local inspection tool, meant for a dev machine. For network observability in production systems there are other layers — aggregated metrics, distributed tracing, infrastructure tools — that aren't the goal of this experiment.

My Take

Installing Sniffnet didn't give me a magic number of "this is what your AI agent spends on network." It gave me something smaller and more honest: the ability to look, whenever I want, at which process is talking to which destination on my machine while I've got four AI tools running at once. That's already more than I had before, which was zero visibility.

What I'd do differently if someone wants to draw a serious conclusion from this: not a five-minute capture, but repeated sessions — idle agent, agent with a small task, agent with a big refactor task — comparing the graphs against each other. That's where the data starts to mean something. A single snapshot of traffic is barely curiosity; a series of compared snapshots is where judgment actually starts.

If you work with local AI agents daily and never looked at the network layer, the logical next step isn't to draw conclusions from one run. It's to install the tool, watch it for a week, and only then decide if there's something worth digging into further.

Original source:

Sniffnet GitHub: https://github.com/GyulyVGC/sniffnet

This article was originally published on juanchi.dev

Sniffnet: cuánto tráfico generan mis agentes IA sin que me avisen

Juan Torchia — Mon, 07 Sep 2026 12:00:15 +0000

Tengo Cline abierto en VS Code casi todo el día. De fondo, corre llamadas a APIs de modelos, hace requests que yo no disparo a mano y — asumo — mantiene conexiones vivas mientras "piensa". Nunca lo miré desde la capa de red. Miro logs de la app, miro el output del agente, pero nunca abrí un sniffer para ver los paquetes reales que salen de mi máquina cuando tengo tres o cuatro herramientas de IA corriendo al mismo tiempo.

Esa es la fricción concreta: uso agentes IA todos los días y no tengo la menor idea de cuánto tráfico "silencioso" generan. No cuánto me cobran los tokens — eso lo veo en el dashboard de cada proveedor — sino cuánto tráfico de red real cruza mi interfaz mientras Cline está "pensando" o mientras alguna extensión hace polling.

Mi tesis es simple y no es una revelación grandilocuente: no sabemos cuánto tráfico de fondo generan nuestros agentes IA hasta que los miramos con una herramienta dedicada, y a veces sorprende. No porque el tráfico sea sospechoso — es porque nunca lo miramos, punto. Y esa ignorancia tiene un costo cuando después querés diagnosticar latencia rara, entender por qué el agente "tarda" o simplemente saber qué procesos están hablando con qué endpoints.

Sniffnet como herramienta de monitoreo de tráfico de red

Sniffnet es una herramienta open source escrita en Rust que analiza el tráfico de red en tiempo real y lo muestra con una interfaz gráfica, sin que tengas que leer output crudo de tcpdump. Según su repositorio, permite elegir una interfaz de red, filtrar por aplicación, protocolo o dirección IP, y ver gráficos de tráfico entrante y saliente en vivo.

Lo que el repo dice, y que me importa para este experimento:

Es multiplataforma (Linux, macOS, Windows).
Usa pcap por debajo, así que necesita permisos elevados para capturar paquetes en la interfaz real.
Identifica el proceso o la app asociada a cada conexión en algunos sistemas, lo cual es justo lo que necesito para separar "esto es Cline" de "esto es el navegador con quince pestañas abiertas".
No es un IDS ni un firewall. No bloquea nada, no alerta de anomalías con lógica propia. Es observabilidad pasiva.

Lo que el repo NO dice, y que conviene tener claro antes de instalarlo: no promete desencriptar tráfico TLS, no te muestra el contenido de los requests HTTPS que hacen las APIs de LLM, y no correlaciona tráfico con costo de tokens ni con latencia del modelo. Sniffnet ve bytes y conexiones. No ve semántica.

# instalacion via cargo (necesita Rust instalado)
cargo install sniffnet

# en Linux, dar permisos de captura sin correr como root
sudo setcap cap_net_raw,cap_net_admin=eip $(which sniffnet)

# correrlo
sniffnet

Con eso levanta la interfaz gráfica, te pide que elijas la interfaz de red activa (wifi o ethernet) y arranca a graficar tráfico en tiempo real.

Dónde se equivoca la gente al leer estos números

La receta común es: instalás una herramienta de monitoreo, ves un pico de tráfico, asumís que "algo está mal" o que "el agente consume mucho más de lo esperado", y sacás una conclusión sin contexto.

El costo oculto de esa receta es doble. Primero, un pico de tráfico en una sesión de captura de cinco minutos no te dice si eso es normal, si es un caso aislado, o si depende de qué estaba haciendo el agente en ese momento exacto — ¿estaba subiendo contexto de un archivo grande? ¿Descargando un modelo? ¿Simplemente manteniendo un keep-alive? Sin ese contexto, el número es ruido con forma de dato.

Segundo, y más importante: TCP/IP no distingue "tráfico útil" de "tráfico de protocolo". Ves bytes yendo y viniendo, pero separar cuánto es payload real de la llamada al LLM versus overhead de conexión, reintentos o polling de alguna extensión que no tiene nada que ver con IA requiere mirar con más granularidad — filtrar por proceso, por puerto, por IP de destino — algo que Sniffnet permite pero que exige trabajo activo de quien mira, no viene resuelto de fábrica.

El contraejemplo clásico: alguien corre Sniffnet, ve que su editor con extensiones de IA genera tráfico constante incluso sin estar escribiendo código, y concluye "el agente está haciendo algo raro en segundo plano". Puede ser telemetría de la extensión, un heartbeat de conexión, o simplemente el editor sincronizando configuración en la nube — nada relacionado con el agente de IA en sí. La herramienta te da el bruto. La interpretación correcta te la tenés que ganar.

Matriz de decisión: cuándo usar Sniffnet para esto

Situación	Usar Sniffnet	Evitarlo / usar otra cosa
Querés ver qué procesos generan tráfico de red en tu máquina en tiempo real	Sí, para eso está pensado	—
Necesitás saber cuánto tráfico HTTPS específico hace una API de LLM	Parcial: ves bytes y destino, no contenido	Para eso necesitás logs de la propia herramienta (Cline expone su actividad en el panel de VS Code)
Querés decidir si tu agente IA "consume demasiado" en producción	No, con una sola sesión de observación no alcanza	Necesitás métricas agregadas en el tiempo, no una captura puntual
Buscás diagnosticar por qué una conexión se corta o tarda	Sí, sirve para ver si hay reintentos o drops	—
Necesitás un IDS con reglas de alerta automática	No es su función	Herramientas como Suricata o Zeek están pensadas para eso
Querés entender el patrón general de tráfico de tu setup de dev (Cline + terminal + navegador)	Sí, filtrando por proceso vas a poder separar cada fuente	—

Lo que miraría primero, antes de sacar cualquier conclusión: qué procesos aparecen en la lista de conexiones activas cuando el agente está inactivo (sin estar procesando nada) versus cuando le tirás una tarea de refactor grande. Esa comparación — inactivo vs. activo — es más informativa que mirar un número aislado.

Si ya usás Cline en modo autopilot con límites definidos, este tipo de observación de red es un complemento razonable: no reemplaza los límites de autonomía que le pongas al agente, pero te da visibilidad de un ángulo que normalmente no se mira — la capa de red, no la capa de comportamiento del agente.

flowchart LR
  A[Cline corriendo] --> B{Tarea activa}
  B -->|si| C[Llamada API LLM]
  B -->|no| D[Posible keep-alive o polling]
  C --> E[Sniffnet: ver bytes y destino]
  D --> E
  E --> F{Contexto conocido?}
  F -->|si| G[Conclusion valida]
  F -->|no| H[Necesita mas sesiones de captura]

Límites: lo que esta evidencia no permite concluir

Acá tengo que ser honesto con lo que Sniffnet, usado en una sesión de observación, puede y no puede darte:

No podés concluir cuánto tráfico "es normal" sin una serie de mediciones repetidas en distintos escenarios de uso. Una captura puntual es un dato, no una tendencia.
No podés separar tráfico de IA de tráfico de otras herramientas solo con el gráfico general. Necesitás filtrar por proceso o puerto, y eso depende de que el sistema operativo expose esa asociación correctamente — en algunos entornos containerizados o con VPN, la asociación proceso-conexión se pierde.
No mide costo en tokens ni latencia del modelo. Bytes de red y tokens de LLM son magnitudes distintas: un request corto en bytes puede representar un prompt largo y caro, y viceversa.
No reemplaza logs de la aplicación. Si querés saber exactamente qué llamada a qué endpoint corresponde a qué acción del agente, la fuente de verdad es el log de la herramienta (Cline, la CLI del proveedor de LLM), no el sniffer de red.
Una sola sesión de captura no es un experimento reproducible en el sentido estricto. Para sacar una conclusión que valga la pena publicar necesitarías repetir la observación en condiciones comparables, algo que este post no hace ni pretende sustituir.

Dicho eso: el punto de instalar la herramienta no es sacar una cifra final, es abrir una capa que normalmente no miramos. Ya avancé algo parecido cuando comparé pnpm y npm en fricción de instalación o cuando cuestioné qué tan barato es en la práctica un agente como DeepSeek Reasonix: la costumbre de mirar cosas que uso todos los días sin haberlas mirado nunca de cerca.

Preguntas frecuentes

¿Sniffnet necesita permisos de administrador?
Sí, porque usa pcap para capturar paquetes a nivel de interfaz de red. En Linux podés dar permisos específicos con setcap en vez de correrlo como root directamente, que es lo recomendable por seguridad.

¿Sniffnet puede ver el contenido de mis conversaciones con un LLM?
No. El tráfico entre Cline (o cualquier cliente) y una API de LLM va cifrado con TLS. Sniffnet ve que hay una conexión, a qué IP o dominio va, cuántos bytes se transfieren — no el contenido del payload.

¿Sirve para medir cuánto gasto en tokens?
No directamente. Bytes de red no equivalen a tokens de LLM. Para costo real de tokens hay que mirar el dashboard del proveedor o los logs de uso de la herramienta que estés usando.

¿Es mejor que Wireshark para este caso?
Depende del objetivo. Wireshark tiene más profundidad de análisis de protocolo y es el estándar para diagnóstico avanzado. Sniffnet apunta a una lectura más rápida y visual del panorama general de tráfico por aplicación, sin la curva de aprendizaje de Wireshark.

¿Puedo usar Sniffnet en macOS o solo en Linux?
Es multiplataforma: soporta Linux, macOS y Windows según la documentación del proyecto en GitHub.

¿Esto reemplaza tener observabilidad real en un sistema de producción?
No. Es una herramienta de inspección local, pensada para una máquina de desarrollo. Para observabilidad de red en sistemas productivos existen otras capas — métricas agregadas, tracing distribuido, herramientas de infraestructura — que no son el objetivo de este experimento.

Mi postura

Instalar Sniffnet no me dio una cifra mágica de "esto es lo que gasta tu agente IA en red". Me dio algo más chico y más honesto: la posibilidad de mirar, cuando quiera, qué proceso está hablando con qué destino en mi máquina mientras tengo cuatro herramientas de IA corriendo a la vez. Eso ya es más de lo que tenía antes, que era cero visibilidad.

Lo que haría distinto si alguien quiere sacar una conclusión seria de esto: no una captura de cinco minutos, sino sesiones repetidas — agente inactivo, agente con tarea chica, agente con tarea de refactor grande — comparando los gráficos entre sí. Ahí el dato empieza a significar algo. Una sola foto de tráfico es apenas curiosidad; una serie de fotos comparadas es donde arranca el criterio.

Si laburás con agentes IA local a diario y nunca miraste la capa de red, el próximo paso lógico no es sacar conclusiones de una corrida. Es instalar la herramienta, mirar una semana, y recién ahí decidir si hay algo que valga la pena investigar más a fondo.

Fuente original:

Sniffnet GitHub: https://github.com/GyulyVGC/sniffnet Instalé Sniffnet para mirar qué tráfico de red generan Cline y las llamadas a APIs de LLM corriendo en segundo plano. Esto es lo que muestra la herramienta y lo que no podés concluir con una sola sesión de observación.

Este artículo fue publicado originalmente en juanchi.dev