DEV Community: Enrico Testori

One login to rule them all: centralized auth for internal tools with Caddy

Enrico Testori — Mon, 20 Jul 2026 20:55:42 +0000

I am lazy. Not in the "I don't want to work" sense¹, but in the "I refuse to solve the same problem twice" sense.
So when I found myself looking at a growing collection of internal tools (each one either completely unprotected or with its own half-baked auth bolted on) I decided it was time to stop and fix it properly.

The dream: one login, backed by the identity provider the company already uses, and every new tool just gets two lines in a config file. No user databases to maintain, no password reset flows to implement, no "hey can you add my colleague to the thing".

In our case the company uses Azure AD, so the plan was to put everything behind Caddy and add OAuth2 authentication against the existing Microsoft tenant. This post is about how that works and the two things that needed some extra attention to get right.

Why Caddy

I've been through the nginx phase. The Apache phase. The "let me just write a quick script to renew certificates" phase.
At some point you just want something that works without making you feel like you're filing paperwork.

Caddy hits a sweet spot I haven't found elsewhere: it's simple enough that you can read the whole config and understand it in one sitting,
but complete enough that you rarely need to reach for anything else. The Caddyfile syntax is human-readable by design, and the defaults are sane,
which sounds like a low bar until you've spent an afternoon debugging a cipher suite.

The thing that genuinely removes the most friction though is automatic HTTPS. Point a domain at your server, add it to the Caddyfile,
and Caddy handles the Let's Encrypt certificate negotiation, renewal, and everything in between. No certbot cron jobs, no --nginx flags,
no "oh the cert expired over the weekend" incidents. It just works, and it keeps working.²

The pieces

Caddy as reverse proxy
Caddy-security (also known as AuthCrunch) for authentication and authorization. It plugs directly into Caddy and adds an authentication portal with OAuth2/OIDC support.

Installation

Caddy supports plugins that get compiled directly into the binary. The canonical way to do this is xcaddy, a build tool that fetches
the plugins you want and compiles everything from source. It works, but it requires a Go toolchain on the server, the build takes a
few minutes, and, going back to the laziness point, it's one more thing to maintain.

The alternative is the official download page on the Caddy website. Select your platform, tick the plugins you want, and it hands you a
pre-built binary. That's it. No Go installation, no waiting, no fuss.

Head to the download page, select Linux amd64 (or your platform), add github.com/greenpau/caddy-security, and download. Then install it:

sudo install /path/to/download /usr/bin/caddy

On SELinux-enabled systems (Fedora, RHEL and friends) you also need to label the binary correctly, otherwise systemd will refuse to run it:

sudo setcap 'cap_net_bind_service=+ep' /usr/bin/caddy

Setting up the service

Caddy doesn't run as root. The recommended approach is a dedicated system user with no login shell and a home directory where Caddy
can store certificates and other state:

sudo groupadd --system caddy

sudo useradd --system \
    --gid caddy \
    --create-home \
    --home-dir /var/lib/caddy \
    --shell /usr/sbin/nologin \
    --comment "Caddy web server" \
    caddy

Create the config directory:

sudo mkdir -p /etc/caddy
sudo touch /etc/caddy/Caddyfile
sudo chown -R caddy:caddy /etc/caddy

The official Caddy repository ships a ready-made systemd unit file, so grab that rather than writing one from scratch:

sudo curl -o /etc/systemd/system/caddy.service \
    https://raw.githubusercontent.com/caddyserver/dist/master/init/caddy.service

The relevant bits of the unit file:

[Service]
User=caddy
Group=caddy
ExecStart=/usr/bin/caddy run --environ --config /etc/caddy/Caddyfile
ExecReload=/usr/bin/caddy reload --config /etc/caddy/Caddyfile --force

ExecReload is worth noting: systemctl reload caddy does a graceful config reload without dropping connections.
You'll use this constantly while tweaking the Caddyfile.

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now caddy
sudo systemctl status caddy

Logs go through journald:

journalctl -u caddy -f

How caddy-security works

The plugin introduces three concepts that work together:

Identity provider: where users actually authenticate. In our case Azure AD via OAuth2, but it works with any OIDC-compliant provider or even a local user database if you need a fallback.
Authentication portal: the login page. It ties together one or more identity providers, manages session cookies, and handles the OAuth2 callback. It lives on a dedicated subdomain (e.g. auth.yourdomain.com).
Authorization policy: the bouncer. Applied per-service, it checks whether the current user has the required roles and redirects to the portal if not.

Azure AD setup

Before touching the Caddyfile, register an application in the Azure Portal:

Azure Active Directory → App registrations → New registration
Name: anything sensible
Supported account types: Accounts in this organizational directory only
Redirect URI (Web): https://auth.yourdomain.com/oauth2/azure/authorization-code-callback

Once created, note down the Application (client) ID and Directory (tenant) ID from the Overview page. Then go to Certificates & secrets → New client secret
and copy the Value immediately; it's only shown once.³

Under API permissions add the Microsoft Graph delegated permissions: openid, email, profile, User.Read, and grant admin consent.

The Caddyfile

{
    email your@email.com
    order authenticate before respond
    order authorize before reverse_proxy

    security {
        oauth identity provider azure {
            realm azure
            driver azure
            client_id YOUR_CLIENT_ID
            client_secret YOUR_CLIENT_SECRET
            tenant_id YOUR_TENANT_ID
            scopes openid email profile
            enable logout
        }

        authentication portal myportal {
            crypto default token lifetime 28800
            crypto key sign-verify YOUR_JWT_SECRET
            enable identity provider azure
            cookie domain yourdomain.com
            cookie path /
            cookie lifetime 28800
            cookie samesite lax
            cookie guess domain
            trust login redirect uri domain suffix yourdomain.com path prefix /

            ui {
                links {
                    "My App" https://myapp.yourdomain.com
                }
            }
        }

        authorization policy protected_services {
            set auth url https://auth.yourdomain.com/login
            enable login hint
            allow roles authp/guest user admin
            crypto key verify YOUR_JWT_SECRET
        }
    }
}

auth.yourdomain.com {
    authenticate with myportal
}

# Protected
myapp.yourdomain.com {
    authorize with protected_services
    reverse_proxy 10.0.0.2:8080
}

anothertool.yourdomain.com {
    authorize with protected_services
    reverse_proxy 10.0.0.3:3000
}

Generate the JWT secret with openssl rand -base64 32.

Two things that needed extra attention

Role remapping is broken in recent builds

caddy-security has a transform user directive that lets you promote authenticated users to named roles based on their email domain:

transform user {
    suffix match email @yourdomain.com
    action add role user
}

In theory this is the right tool: map everyone from your organization to the user role, restrict the authorization policy to allow roles
user admin, and anyone outside your tenant gets nothing even if they somehow authenticated. Clean and explicit.

In practice, as of the current build, the transform doesn't reliably fire after an OAuth2 login. Users end up with only the default
authp/guest role regardless of what the transform says, which means a policy that only allows user will lock everyone out; including
the people you just spent an afternoon trying to let in.

The workaround is to allow authp/guest in the authorization policy. It's not as granular as role mapping, but given that the OAuth2
provider is already scoped to a single tenant, any user who successfully authenticates is implicitly trusted, the gatekeeping is happening
at the Azure level anyway.

This does mean that in practice everyone in the same Azure AD tenant gets access to all protected services. For us that's fine: we're a small
team and internal tools are, well, internal. But the building blocks for something more structured are already there: once transform user is
reliable again, you can map roles per email domain, per specific user, or combine multiple policies to restrict individual services to specific
groups. The concept scales, even if the current implementation needs a nudge.

Keep an eye on the issue tracker if fine-grained role mapping matters for your use case.

Cookies and post-login redirects

Two things need to be correct for the flow to work end to end.

The first is cookie scoping. After login, the browser needs to send the access token cookie to all protected subdomains, not just auth.yourdomain.com.
cookie guess domain handles this automatically. Without it, every request to a protected service finds no token and loops back to the login page indefinitely
(which is as fun as it sounds).

A counterintuitive note from the official docs: don't use a leading dot (.yourdomain.com) for cookie domain. Despite being standard practice in most contexts,
the plugin doesn't support it and things break silently.

The second is the post-login redirect. After a successful login you'd expect to land on the page you were originally trying to reach. Without the right
configuration you land on the portal homepage instead, which is anti-climactic. Two things are needed in combination: set auth url must point to /login
explicitly (not just the root domain), and the portal needs to know which redirect destinations are trusted:

trust login redirect uri domain suffix yourdomain.com path prefix /

Without this the portal ignores the redirect_url query parameter entirely.

The final result

The next time someone asks for a new internal tool, the answer is: spin it up, add two lines to the Caddyfile, reload.
No user database, no password reset flow; nothing.

Everyone with a company account can log in, everyone else can't.

I also added enable login hint so in case anyone needs to login after the previous session expired, it will be presented with the Azure AD login page already filled
with the account of the expired session: easy and effecient.

My laziness form is now complete. Larry Wall would be proud.⁴

Well, not only in that sense. ↩
Caddy also gets an A+ on SSL Labs out of the box, in case you needed another reason. ↩
There are two columns: Secret ID (a GUID) and Value (a long random string). You want the Value. Using the ID will give you a cryptic AADSTS7000215 error and a solid fifteen minutes of confusion. ↩
Larry Wall, creator of Perl, listed the three virtues of a programmer as: Laziness, Impatience, and Hubris. Laziness is first. We are vindicated ↩

Adding a custom DeepSeek model in Junie CLI (No YAML demons required)

Enrico Testori — Mon, 20 Jul 2026 12:11:48 +0000

I switched my Junie CLI default model to DeepSeek last month. The reason wasn't philosophical: Claude and GPT are great, but they cost real money when you're hammering a CLI for hours. DeepSeek is cheaper. Sometimes the best technical decision is the one your wallet makes for you.

The switch itself was anticlimactic. There's no junie model add wizard, no guided setup, and the --help output mentions custom models only in passing with a --model flag that reads like an afterthought. What you actually do is drop a JSON file into ~/.junie/models/ and… that's it. Junie picks it up.

This post documents that process: adding deepseek-v4-pro to Junie CLI, using the actual config format running on my machine right now.¹

Why bother?

Before we touch any config, let's answer the obvious: why not just use the built-in providers?

Because in real life we optimize for different things at different times:

You want…	So you reach for…
Latency minimization	a flash/fast variant
Deep refactors with context	a large-context model
Cost control on long sessions	a cheaper provider
Provider redundancy	a backup endpoint
Experimentation	whatever just dropped on HuggingFace

If your tooling lets you swap models cleanly, you gain operational sanity. And operational sanity is underrated.

Prerequisites

Junie CLI installed. You should already have junie on your PATH. Verify:

   junie --help

A DeepSeek API key. Get one from platform.deepseek.com. You'll need to top up credits.
Basic JSON literacy. No YAML, no TOML, no arcane DSL. Just one JSON file. You've got this.

How Junie CLI discovers custom models

Junie looks for model definitions in two default locations:

~/.junie/models/: global, available to all projects
<project>/.junie/models/: per-project overrides

Each model is a single .json file. The filename becomes the model's identifier within Junie. So ~/.junie/models/deepseek.json registers a model called… deepseek. Creative, I know.

You can also point Junie at additional directories with --model-location <path> if you prefer to keep your model configs in a dotfiles repo or shared volume.

Step 1 — Create the model JSON

Create ~/.junie/models/deepseek.json (or <project>/.junie/models/deepseek.json if you want it scoped to a single codebase):

{
  "id": "deepseek-v4-pro",
  "baseUrl": "https://api.deepseek.com/chat/completions",
  "apiType": "OpenAICompletion",
  "apiKey": "sk-your-deepseek-api-key-here",
  "temperature": 0,
  "primaryModel": {
    "id": "deepseek-v4-pro"
  },
  "fasterModel": {
    "id": "deepseek-v4-flash"
  }
}

Let's unpack what each field does:

Field	Purpose
`id`	The primary model identifier. Junie displays this in the model picker and passes it in API requests.
`baseUrl`	The endpoint Junie POSTs to. DeepSeek's API is OpenAI-compatible, so we point it at their chat/completions endpoint.
`apiType`	Tells Junie which request/response format to use. `"OpenAICompletion"` covers OpenAI, DeepSeek, and most compatible providers.
`apiKey`	Your API key. Yes, it's plaintext in a JSON file. We'll talk about this.
`temperature`	Controls response randomness. `0` means deterministic; bump it to `0.3`–`0.7` for more creative output.
`primaryModel.id`	The model ID sent in the API request body. This must match the DeepSeek model name exactly.
`fasterModel`	(Optional) A lighter/faster model for quick tasks like inline autocomplete or summarization.

A stern word about `apiKey`

Yeah, it's sitting there in plaintext. I know. No, Junie doesn't currently read it from an environment variable for custom models². Your options:

Set restrictive file permissions: chmod 600 ~/.junie/models/deepseek.json. At least other users on the system can't read it.
Use a LiteLLM proxy as middleware (see the LiteLLM section below): this keeps the key out of Junie's config entirely.
Accept it and don't commit the file to a public dotfiles repo. You're an adult.

For what it's worth, Junie stores the key in your home directory, which on a single-user development machine is about as secure as any other dotfile with secrets in it. Not ideal, but not the end of the world either³.

Step 2 — Use the model

Once the JSON file is in place, you have three ways to invoke it:

CLI flag (one-off)

  junie --model custom:deepseek "Explain this function."

This will start junie in interactive mode using the custom model defined previously in json configuration.

Interactive mode

Launch Junie interactively, then pick the model from the selector (usually /model or the equivalent model-switching shortcut):

  junie

Your custom deepseek model should appear in the list alongside the built-in providers.

Settings override (persistent default)

Edit ~/.junie/settings.json and add or edit:

{
  "modelForLaunch": "custom:deepseek",
}

Now every session starts with DeepSeek unless you override with --model.

Step 3 — Verify it works

Before trusting it with a 400-line refactor, run a quick sanity check:

junie --model custom:deepseek "Say hello and confirm which model you're running on."

If the response comes back coherent and the logs show deepseek-v4-pro, you're in business. If you get an auth error, double-check:

The API key is correct and has credits
The baseUrl ends with /chat/completions (no trailing slash weirdness)
The primaryModel.id matches exactly what DeepSeek expects

The bottom line

Junie CLI's custom model system is refreshingly straightforward: drop a JSON file in a directory, and you're done. No YAML anchors, no multi-file inheritance chains, no environment-variable indirection puzzles. Just a flat config that tells the CLI where to send requests and which model ID to use.

Is the plaintext API key ideal? No. But with file permissions and/or a LiteLLM proxy, you can mitigate the concern without adding much friction. For single user dev-machines it's a worth tradeoff.

Now go wire up your DeepSeek model and tell it to write you some code. Or a haiku about YAML. Your call.

Thanks for reading!

If you're looking for the accompanying Italian version of this post… there isn't one. Some topics just work better in English, and CLI config files are definitely in that camp. "Drop un JSON nella cartella models" doesn't quite hit the same way. ↩
If you're reading this from the future and Junie does support apiKeyEnv or similar: congratulations, the timeline is better than mine. Please update this post. ↩
"Not the end of the world" is the security posture equivalent of "it compiles, ship it." Take appropriate precautions. ↩

Balancing flexibility and strictness with lenient Duration deserialization in Kotlin

Enrico Testori — Thu, 16 Jul 2026 10:41:53 +0000

I have written before about Kotlin's Duration class, and its blend of technical sophistication and developer friendliness continues to impress. Recently, a unit test highlighted an important distinction in how Kotlin handles duration parsing. The duration string "1s" works perfectly with Duration.parse(), but fails during JSON deserialization when dealing with real-world data.

This apparent inconsistency is actually a deliberate design choice. The Duration.parse() method is flexible by design, while kotlinx.serialization is intentionally strict to enforce standardization.

What happens under the hood?

Examining Kotlin's source code clarifies this behavior. First, let's look at the Duration class itself:

// In Duration.kt
public inline class Duration internal constructor(
    private val rawValue: Long
) : Comparable {
    // ...
    companion object {
        public fun parse(value: String): Duration = try {
            parseDuration(value, strictIso = false)
        } catch (e: IllegalArgumentException) {
            throw IllegalArgumentException(
                "Invalid duration string format: '$value'.", e
            )
        }
    }
}

A few key points stand out in this implementation:

Duration is an inline class with an internal constructor.
This constructor cannot be used for deserialization due to its internal visibility.
The parse() method intentionally accepts non-ISO formats by explicitly setting strictIso = false.

Now, let's look at how kotlinx.serialization handles the Duration class:

internal object DurationSerializer : KSerializer {
    override val descriptor: SerialDescriptor =
        PrimitiveSerialDescriptor("kotlin.time.Duration", PrimitiveKind.STRING)

    override fun serialize(encoder: Encoder, value: Duration) {
        encoder.encodeString(value.toIsoString())
    }

    override fun deserialize(decoder: Decoder): Duration {
        return Duration.parseIsoString(decoder.decodeString())
    }
}

The serializer makes a deliberate choice to use parseIsoString() for deserialization. Instead of relying on the more permissive parse() method, it enforces the ISO-8601 standard for data integrity.

Implementing a lenient custom serializer

Since we cannot change the built-in behavior of kotlinx.serialization—and generally shouldn't, given the importance of enforcing standards in data exchange—we can create our own custom lenient serializer.

internal object LenientDurationSerializer : KSerializer {
    override val descriptor: SerialDescriptor =
        PrimitiveSerialDescriptor("kotlin.time.Duration", PrimitiveKind.STRING)

    override fun deserialize(decoder: Decoder): Duration {
        return Duration.parse(decoder.decodeString())  // Using the lenient parser
    }

    override fun serialize(encoder: Encoder, value: Duration) {
        encoder.encodeString(value.toIsoString())  // Still formal in output using ISO
    }
}

This serializer accepts casual input formats by using parse(), but ensures formal ISO-8601 formatting on output by using toIsoString(). You can apply it to your data classes using the @Serializable annotation:

data class ProcessDuration(
    @Serializable(with = LenientDurationSerializer::class)
    val duration: Duration
)

// Now both these work:
val formal = """{"duration": "PT1S"}"""
val casual = """{"duration": "1s"}"""

This approach adheres to a fundamental principle of data exchange: be flexible in what you accept, but strict in what you produce. Watch how our duration gets standardized during serialization:

// What goes in
{"duration": "1s"}

// What comes out
{"duration": "PT1S"}

Both strings represent the exact same duration, but the output is standardized. When writing data that might be consumed by other systems, enforcing an ISO format is a necessary practice for maintaining a reliable ecosystem.

Standards vs. reality

While enforcing ISO-8601 in serialization is technically correct, real-world data is often much less organized. Anyone who has dealt with dates, times, and durations in production environments knows the variety of formats that can appear.

In a typical production environment, you might encounter:

Natural language timestamps generated by NLP parsing services (e.g., "Last Monday").
Inconsistent timezones represented in various ways such as "GMT+1", "UTC+1", "+0100", or "Europe/Paris".
Varying date formats originating from legacy systems (e.g., "23-11-2023", "11-23-2023", or "2023/11/23").
Raw millisecond values typically found in Java integrations ("5400000ms").
Excessively verbose XML-style durations from older architectures ("P0Y0M0DT1H30M0S").

The variety of time formats is a persistent challenge in software development. While standards like ISO-8601 are crucial for reliable data exchange, being overly rigid can cause integrations to fail. A pragmatic approach requires us to handle the data as it arrives, gracefully converting it into a standardized format for the future.

Conclusion

Dealing with rigid data formats can sometimes feel like P100Y of ISO-litude¹: an endless century of strict parsing errors and isolated systems. However, examining Kotlin's source code reveals the thoughtful design behind its time packages.

By allowing Duration.parse() to welcome various formats for developer convenience, while keeping kotlinx.serialization anchored to ISO standards, the ecosystem strikes a perfect balance. You do not have to be isolated by strict formats; you simply need a custom serializer to bridge the gap between human-friendly inputs and machine-standardized outputs.

For the uninitiated: P100Y is the valid ISO-8601 duration string for exactly 100 years, with apologies to Gabriel García Márquez ;-) ↩

Fish, Foot and beyond: a terminal setup that finally smells right 🐟👣

Enrico Testori — Wed, 15 Jul 2026 06:59:22 +0000

Picture this: there I was, happily using Tilix for my terminal needs on Fedora.
Split panes, dropdown terminal, the whole shebang. Life was good... until it wasn't.
Recent Fedora updates started making Tilix throw tantrums, and suddenly my trusty terminal setup felt like that friend who keeps flaking on plans.

After some soul-searching (and a lot of Reddit threads), I realized I needed to break down my terminal needs: a rock-solid Wayland-native terminal emulator, a shell that wouldn't make me hate scripting, and a multiplexer that could keep up with modern workflows.

Enter the new trio: Foot, Fish, and Zellij. Yes, I know - between Fish and Foot, this setup sounds like it came from a very weird pet shop. But stick with me here!

Sometimes less is more

For terminal emulation I wanted something simple, stable, and Wayland-native. Foot checked all these boxes and then:

is blazing fast thanks to being written in C
is hardware accelerated rendering (hello, smooth scrolling!)
has minimal dependencies (goodbye, random breakages!)
has simple configuration in a single file
has Sixel support for those fancy terminal graphics

Now, I'll be honest - when people talked about "fast terminals," I used to roll my eyes. How fast does a terminal need to be to show some text? Well, turns out I was wonderfully wrong - you don't realize how much terminal lag affects your workflow until you try a faster one.

Life's too short for boring shells!

Remember the first time you saw someone's terminal autocomplete something magical? That's Fish, all day, every day; no hacky setups required.
Here's what made me fall hook, line, and sinker for it:

Fish remembers your commands and suggests them as you type. It's like having a very eager assistant who actually knows what they're doing. Autosuggestions feel like mind-reading!
Colors! So many colors! And they actually mean something (unlike my old prompt that I made pretty but couldn't remember what anything meant)
No more if [ -f something ] syntax that looks like it came from the 80s. Fish makes scripting feel like actual programming

Sure, there's the occasional "this shell script isn't compatible with Fish" moment, but let's be real - when was the last time you looked at a bash script and thought "wow, this is so intuitive"? Fish makes the trade-off simple: give up some backwards compatibility, get a shell that feels like it was actually designed in this century. And for those rare occasions when you really need to run a bash just prefix it with bash and move on with your life.

Getting on the right Foot

First things first - let's get our Foot in the door (sorry, not sorry).
On Fedora, it's as simple as this:

sudo dnf install foot fish zellij

Easy, isn't it?

And of course, CTRL-ALT-T still spawns my terminal - some habits are worth keeping.

Foot configuration

My Foot configuration is straightforward but purposeful. Let's break it down:

[main]
font=JetBrains Mono:size=16
initial-window-mode=fullscreen
shell=/usr/bin/fish

The main section is minimal:

JetBrains Mono because it's a fantastic monospace font with great readability
terminals starts fullscreen because that's what I ended up doing as first action every time I opened a Tilix in my old setup
last but not least, of course, Fish is set as the default shell because that's the whole point of this setup.

[colors]
# A wild variety of Catppuccin Mocha colors...

While I'm unsure about the theme interaction with zellij, it's working fine, and so I'll briefly give an overview of it. I'm using Catppuccin Mocha - a soothing dark theme that's easy on the eyes. It provides:

A dark background (1e1e2e) with light text (cdd6f4) for good contrast
Carefully chosen colors for different terminal elements
Nice selection colors that don't make you squint (I am colorblind myself)
Special colors for search and jump labels that actually stand out

The URLs are highlighted in a gentle blue (89b4fa) - because clickable links should be obvious but not screaming for attention.
Nothing fancy, no transparency effects or padding tweaks - just a clean, functional setup that gets out of your way while being pleasant to look at.

Fish configuration

My Fish config is minimalist but gets the job done. Let's see what's happening here:

set -x ZELLIJ_AUTO_EXIT true
if status is-interactive
    # Commands to run in interactive sessions can go here
    eval (zellij setup --generate-auto-start fish | string collect)
end

The first line sets up Zellij to automatically exit when the last pane closes (as easy as pressing CTRL-D). It's a quality-of-life setting - when you're done with your last terminal window, Zellij closes cleanly instead of hanging around with an empty session.
Then, we check if we're in an interactive shell (as opposed to running a script)
Lastly, we auto-start Zellij using its built-in Fish integration. The string collect bit ensures all the output from the setup command is handled properly

The result? Every time I open Foot, it automatically launches Fish, which automatically starts Zellij. No manual steps, no "oops I forgot to start my multiplexer" moments - everything just flows.
You know those tiny tasks that seem insignificant? "Oh, it's just two keypresses to start Zellij..." But when you do them 20 times a day, those micro-interruptions add up and break your flow. Now my terminal setup just works, and I can focus on what I actually opened the terminal for in the first place.

Zellij configuration

Nothing, it works out of the box! No question asked.

Out of the box, Zellij shows you what shortcuts you can use right in the status bar.
It's a nice way to learn while you work, until your fingers start doing their thing automatically.

A small note about SSH

Here's a little gotcha I discovered when working with remote servers. By default, Foot uses its own terminal type (foot or foot-direct), which is great for local use but can confuse some remote hosts. Adding this tiny bit to my ~/.ssh/config:

Host *
SetEnv TERM=xterm-256color

This tells SSH to identify as the widely-supported xterm-256color when connecting to remote machines.
It's a simple fix that prevents those annoying "unknown terminal type" errors and weird formatting issues when SSHing into servers.
Sure, you lose some of Foot's fancy features on remote connections, but it's a fair trade for having everything just work™ without
having to install terminal definitions on every server you access.

Future experiments: down the Zellij rabbit hole

While this setup is already solid, I've got my eyes on some interesting Zellij possibilities. First up is the SSH client multiplexing - being able to manage multiple SSH connections in a single Zellij session, with each remote server neatly organized in its own space. Gone would be the days of juggling terminal windows trying to find that one production session.

Zellij's plugin system caught my attention too. Since plugins can be written in any language that compiles to WebAssembly, I might try my hand at building something that scratches my own itches - maybe something to streamline my SSH session management or Git workflow. The project is still quite active, so there's room to play around.

I also want to dig into Foot's session management. The idea is to have a single main Foot window that all new terminal instances connect to when I hit my terminal shortcut. Should be doable with Foot's --server mode and some window manager tweaks. That way I could keep my workflow exactly the same but avoid the window clutter.

These might be solutions looking for problems, but hey - isn't that half the fun of terminal customization? Plus, unlike my Tilix tweaking days, if something breaks, my base setup remains rock-solid. Stay tuned for potential updates if any of these experiments turn out particularly useful!

Final considerations

After a few months with this setup, I can't imagine going back. The combination of Foot's speed, Fish's smarts, and Zellij's flexibility has genuinely improved my daily workflow. Sure, it took a bit of tweaking to get everything just right, but that's the beauty of it - each piece is simple enough that customizing doesn't feel like solving a puzzle.

Looking back at my Tilix days, I realize sometimes "just works" beats "works with all the features." This setup is faster, more stable, and honestly, just more enjoyable to use. Plus, there's something satisfying about having a terminal setup that's both modern and respectful of system defaults. If you're on the fence about modernizing your terminal setup, consider this your sign to take the plunge - your future self will thank you.

Oh, and here's a neat thing about this setup: it doesn't touch your system's default shell at all. Bash remains as the system shell, handling all its traditional duties, while Fish only kicks in when you're actually using the terminal interactively. It's like having your cake and eating it too: the system keeps humming along with bash while you get all the nice Fish goodies.

P.S. No Fish were harmed in the making of this terminal setup, though some bad shell scripts were rightfully abandoned.¹

I realized I haven't left any foot notes in a post about Foot. Had to fix that! ↩