I built it for the gap between configuring an agent and using that agent somewhere else. A skill you added on your laptop should be available on the box. A change to your global instructions should reach both. Keeping those files in sync by hand becomes another job every time you improve your setup.

Copying all of ~/.claude would also copy credentials and session data. Ferry selects the configuration to share and leaves authentication on each machine. Your setup travels. Your logins stay on the machine that created them.

The sections below cover setup and daily use, followed by the details of what Ferry syncs.

- Install and first sync - Log in to your tools, with terminal examples - Move a project between your laptop and the box - What Ferry carries and its security model - Remote MCP servers - Automatic sync and updates - Command reference

How it works

Ferry has three parts:

- The operator machine. This is your laptop, macOS or Linux. Ferry runs here, and here is where you edit your skills and settings. - A private snapshot repository. A git repository that you create, for example git@github.com:you/ferry-snapshot.git. It holds the skills, the global instruction file, the Claude subagents and commands, an allowlist of Claude settings keys, and the remote MCP server declarations. - The box. A Linux machine that you reach over Tailscale or SSH. The box does not run Ferry. Ferry runs commands on it over SSH.

Both machines clone the snapshot repository into ~/.ferry/store. Ferry links managed paths into that clone. Individual skills link to the store; Claude subagent and command directories link as whole directories. On your laptop you keep editing files where you always did. ferry sync commits and pushes the store, then connects to the box, pulls the new commit, and links everything into place.

Sync runs from your laptop to the box. Make shared configuration changes on your laptop. If you remove a carried settings key on your laptop, sync removes it on the box too.

Authentication happens separately on each machine. When the box needs a login, Ferry starts the vendor login on the box and prints the URL. You finish the login in a browser on your laptop, and the token stays on the box.

Requirements

- An operator machine with macOS or Linux. Windows is not supported. - A Linux box that you can reach with SSH. ferry install and ferry update use apt for gh, so Debian or Ubuntu is the tested target. - Tailscale on both machines, or one OpenSSH destination such as user@box.example. - An empty private git repository for the snapshot. Ferry does not create it. - For an SSH snapshot URL, an SSH agent on the operator machine with a loaded key that can read and push the snapshot repository. - Bun 1.4 or later, if you install from source.

Install

The quickest way is the install script:

`sh curl -fsSL https://raw.githubusercontent.com/dlhck/ferry/main/install.sh | sh `

The script downloads the executable for your platform from the latest GitHub release, checks it against the release's SHA256SUMS file, and installs it to ~/.local/bin/ferry. It supports macOS and Linux on arm64 and x64, and it needs curl or wget plus sha256sum or shasum. If ~/.local/bin is not on your PATH, the script prints the line to add to your shell profile.

Run the remaining commands on your laptop. Ferry runs commands on the box over SSH; you do not install Ferry there.

To update Ferry, run the same command again. Three variables change what the script does:

- FERRY_VERSION installs a specific release, for example curl -fsSL https://raw.githubusercontent.com/dlhck/ferry/main/install.sh | FERRY_VERSION=v0.2.0 sh. - FERRY_INSTALL_DIR installs to a different directory. - FERRY_SKIP_CHECKSUM=1 skips the checksum check. You need it only for v0.1.1 or earlier, which have no SHA256SUMS file.

If you run ferry watch as a service, it keeps the old executable until it restarts. Restart it after an update with launchctl kickstart -k gui/$(id -u)/dev.ferry.watch on macOS or systemctl --user restart ferry-watch.service on Linux.

Ferry is also on npm:

`sh npm i -g @dlhck/ferry `

The package runs the same prebuilt executable and does not need Bun. npm installs only the executable for your platform, from the optional dependency @dlhck/ferry--, so do not install with --omit=optional. Update with npm i -g @dlhck/ferry@latest. ferry update updates the agent tools, not Ferry itself.

To install from source with Bun 1.4 or later:

`sh git clone https://github.com/dlhck/ferry.git cd ferry bun install bun link `

bun link puts ferry on your PATH and runs src/cli.ts with Bun.

Quick start

`sh ferry init # record the box and the snapshot URL, seed the snapshot, link this machine ferry install # install gh, Claude Code, Codex, Pi, and Cursor Agent on the box ferry sync # publish the snapshot and apply it on the box ferry auth gh # start a login on the box, finish it in a browser here ferry auth claude ferry status # check the link, the snapshot, the managed paths, and the box logins `

ferry install shows each install command and asks before it runs it on the box. Repeat ferry auth for each tool you use. Add --dry-run to init, sync, or update to see the changes before Ferry makes them.

After setup, edit skills and settings on your laptop and run ferry sync, or use ferry watch.

Connecting to the box

ferry init asks whether to use a Tailscale host or an SSH-only destination. You can also pass the answer as flags.

A Tailscale peer:

`sh ferry init \ --host build-box \ --ssh-user ferry \ --snapshot-url git@github.com:you/ferry-snapshot.git `

An explicit OpenSSH destination:

`sh ferry init \ --ssh-destination user@box.example \ --snapshot-url git@github.com:you/ferry-snapshot.git `

Ferry stores the transport in ~/.ferry/config.toml. It never falls back from Tailscale to direct SSH, and SSH-only mode never runs Tailscale.

With an SSH snapshot URL, Ferry checks that your SSH agent has a loaded identity, forwards the agent to the box, and tests read access to the snapshot repository. If the git host is not in the box's known_hosts, Ferry prints the host-key fingerprints and asks before it adds them. Your private key stays on your machine.

Logging in on the box

Run ferry auth for gh, claude, codex, or cursor.

Ferry first checks whether the tool is already logged in on the box. If it isn't, Ferry starts the vendor login on the box, detached from the SSH session, and prints the URL and code as soon as the login shows them. You open the URL on your machine and finish there. Ferry checks the box every 5 seconds and reports when the login is complete. The login on the box stops after 15 minutes.

- gh prints a one-time code for https://github.com/login/device. - claude prints the login URL. After the login, the browser shows a code. Paste it at the Ferry prompt, and Ferry hands it to the login on the box. - codex prints a one-time code for https://auth.openai.com/codex/device. If the device login gives no code, Ferry uses the Codex callback login. It prints the URL and forwards local port 1455 to the box for 120 seconds. Press Ctrl-C after the browser reports success. - cursor prints the login URL.

Pi has no remote login that Ferry can start. SSH to the box, run pi, and use /login.

ferry auth without a tool shows which logins Ferry can start:

`shellsession $ ferry auth gh: startable claude: startable codex: startable cursor: startable pi: manual SSH flow `

Examples

These illustrative transcripts follow Ferry's output messages; they are not recordings of live sessions. Codes and the build-box hostname are examples, and authorization URLs are shortened. Use the URL and code printed by your own command.

A first gh login. After the login, Ferry sets up GitHub over SSH and prints one line per step:

`shellsession $ ferry auth gh │ ◇ Starting the gh login on the box URL: https://github.com/login/device Code: 7F3K-92QD Open the URL in a browser on this machine and enter the code. │ ◇ Waiting for you to finish the login in the browser (up to 15 min) gh: logged in SSH key: added to GitHub as build-box (ferry) known_hosts: added github.com git protocol: ssh ssh -T git@github.com: authenticated `

The same command when gh is already logged in:

`shellsession $ ferry auth gh │ ◇ Starting the gh login on the box │ ◇ Checking the gh setup on the box gh: already authenticated SSH key: already on GitHub git protocol: ssh ssh -T git@github.com: authenticated `

A Claude login. The browser shows a code at the end, and you paste it at the prompt. Ferry masks it:

`shellsession $ ferry auth claude │ ◇ Starting the claude login on the box URL: https://claude.ai/oauth/authorize?code=true&client_id=... Open the URL in a browser on this machine. After the login, paste the code that the browser shows. │ ◇ Code from the browser │ ▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪ │ ◇ Waiting for you to finish the login in the browser (up to 15 min) claude: logged in `

A Codex device login:

`shellsession $ ferry auth codex │ ◇ Starting the codex login on the box URL: https://auth.openai.com/codex/device Code: Q8RZ4-TK27M Open the URL in a browser on this machine and enter the code. │ ◇ Waiting for you to finish the login in the browser (up to 15 min) codex: logged in `

In a terminal, each ◇ line is a spinner until its step is done. When Ferry doesn't run in a terminal, for example in a script, it writes each step as one plain line, such as Starting the gh login on the box....

GitHub over SSH

Ferry forwards your SSH agent only for its own snapshot update, so agents on the box need their own key to push. ferry auth gh sets that up:

1. Before the login, Ferry creates ~/.ssh/id_ed25519 on the box if it does not exist. The key has no passphrase and the comment @ ferry. Ferry never replaces an existing key. 2. The gh login asks for the admin:public_key scope, which gh needs to add the key. 3. After the login, Ferry adds ~/.ssh/id_ed25519.pub to your GitHub account with the title (ferry), unless GitHub already has it. 4. If the box ~/.ssh/known_hosts has no github.com entry, Ferry reads the ed25519 host key with ssh-keyscan. It adds the key only if the fingerprint matches the one the GitHub meta API publishes. 5. Ferry runs gh config set -h github.com git_protocol ssh. 6. Ferry runs ssh -T git@github.com and reports whether GitHub accepts the key.

If you don't finish the login, Ferry skips steps 3 to 6. If gh is already logged in, Ferry runs only steps 1 and 3 to 6. A gh login without the admin:public_key scope cannot add the key. Run gh auth refresh -h github.com -s admin:public_key on the box, then run ferry auth gh again.

To revoke the box key, delete the key titled (ferry) under GitHub Settings > SSH and GPG keys, or use gh ssh-key list and gh ssh-key delete . To remove it from the box, delete ~/.ssh/id_ed25519 and ~/.ssh/id_ed25519.pub there.

Moving a project

Your setup is on both machines, but a project usually lives on one of them. ferry move moves a project to the other machine, so an agent on the box can pick up where you stopped, or you can take the box's work back to your laptop.

`sh ferry move ~/Developer/app # this machine -> box ferry move --from-box ~/Developer/app # box -> this machine ferry move ~/Developer/app --dry-run # show what Ferry carries, refuses, and skips ferry move ~/Developer/app --remove # after verification, move the source copy to a trash directory ferry move ~/Developer/app --include-env # also carry .env files that pass the deny rules `

The project must be inside your home directory, and it keeps the same path relative to home. ~/Developer/app on your laptop becomes ~/Developer/app on the box. Ferry doesn't copy the git history. The destination clones the project from origin, and Ferry carries only the files that git doesn't have. The steps:

1. Preflight. Ferry reads the branches and tags of origin with git ls-remote. It refuses the move if a commit on a local branch is not on origin, unless git cherry shows an equivalent patch on the default branch of origin. Ferry does not fetch, so run git fetch first if the patch was merged recently. Ferry also refuses uncommitted changes to tracked files and a destination path that already exists. It reports stashes, because the clone does not get them. 2. Clone. The destination clones the project from origin, at the current branch if origin has it. The box uses its own SSH key, so run ferry auth gh first. 3. Carry. Ferry carries the untracked and ignored files. It skips node_modules, .next, .nuxt, .svelte-kit, .turbo, .cache, .parcel-cache, dist, build, coverage, target, __pycache__, .venv, venv, .gradle, .terraform, .idea, .vscode, .DS_Store, and ._* at any depth. Each carried file must pass the same deny rules as a sync. Ferry refuses symbolic links and nested git repositories. 4. Environment files. Ferry refuses .env and .env.* files. With --include-env, it carries an environment file only if it has no token and no PASSWORD, SECRET, API_KEY, or similar key with a value. 5. Verify. Ferry compares the SHA-256 checksum of each file on the destination with the checksum of the bytes it checked. 6. Paseo. If the destination has the paseo CLI, Ferry runs paseo project create there. 7. Remove. With --remove, Ferry moves the source copy away after verification: to ~/.Trash/- on macOS, and to ~/.ferry/trash/- on the box and on Linux. Ferry never deletes the source copy. If Ferry refuses a local-only file, it refuses --remove before it changes anything.

A folder without git has no clone. Ferry copies all its files with the same skip list and deny rules.

--dry-run prints the plan: the clone, and each file that Ferry carries, refuses, or skips. It writes nothing on either machine. With --from-box, Ferry reads the box files into a temporary directory on your laptop for the deny checks and removes that directory after the run.

:::warning If a step fails after the clone, the destination copy is incomplete. Ferry does not remove it. Move it away before you try again. :::

Supported harnesses

Ferry supports the following tools and their global configuration directories. Ferry calls each configuration a harness:

| Harness | Skill root | Instruction file | MCP servers | | --- | --- | --- | --- | | Shared agents | ~/.agents/skills | ~/AGENTS.md | None | | Claude Code | ~/.claude/skills | ~/.claude/CLAUDE.md | ~/.claude.json | | Codex | ~/.codex/skills | ~/.codex/AGENTS.md | ~/.codex/config.toml | | Pi | ~/.pi/agent/skills | ~/.pi/agent/AGENTS.md | None | | Cursor Agent | ~/.cursor/skills | None | ~/.cursor/mcp.json |

~/AGENTS.md is the shared global instruction file. Ferry links it as the instruction file of each harness, so every agent reads the same instructions. You can add your own harness. See Custom harnesses.

Security model

Ferry carries skills, ~/AGENTS.md, the Claude subagents and commands, an allowlist of Claude settings keys, and the name and HTTPS URL of each remote MCP server. What Ferry carries has the details.

Ferry excludes:

- credential files, OAuth sessions, or Keychain items - tokens, API keys, MCP tokens, or request headers - settings keys that can hold secrets, such as env and apiKeyHelper - local MCP servers, which have a command, args, or env - session history, caches, databases, or whole settings files

Ferry checks carried files against deny rules for credential filenames, known token patterns, and secret fields. A match stops the sync. The error names the file without printing the secret value.

Ferry opens no public listening port. The Codex callback login forwards local port 1455 to the box for 120 seconds. Ferry never turns off SSH host-key checks. It forwards your SSH agent to the box only for the snapshot update.

ferry auth gh creates an SSH key without a passphrase on the box and adds it to your GitHub account, so agents on the box can push. See GitHub over SSH.

:::warning Ferry runs commands on the box as your SSH user. Use a box and an SSH user that you trust with the agents that run there. :::

What Ferry carries

- Skills from every global harness skill root, such as ~/.agents/skills and ~/.claude/skills. Ferry skips the .system directory, because Codex manages it and installs its own copy on each machine. - ~/AGENTS.md, linked as the instruction file of each harness. - Claude subagents and commands in ~/.claude/agents and ~/.claude/commands. Ferry links each directory whole into the store. On the box, a live directory at one of these paths stops the sync. ferry sync --force moves it to ~/.ferry/backups and then links it. - Four keys from ~/.claude/settings.json: enabledPlugins, extraKnownMarketplaces, permissions, and hooks. The snapshot holds them in settings/claude.json. No other key and no plugin cache. - Remote MCP servers from Claude, Codex, and Cursor Agent. Only the name, the transport, and the HTTPS URL. See Remote MCP servers.

It does not carry project-local skills.

Deny rules

The deny rules apply to every carried directory. Any of these stops the sync:

- A file such as .env or credentials.json, or content that matches a known token pattern. - A JSON, YAML, or TOML file with a password, passwd, secret, client_secret, private_key, or api_key key that has a string value, at any depth. Ferry compares keys without regard to case, -, or _, so clientSecret matches too. If the file does not parse, Ferry checks each key: value or key = value line. - An ELF, Mach-O, or PE executable. A script with a shebang and a Java class file are fine. - A carried settings key that holds a token or request headers.

Empty values and recognized placeholders pass. For token examples in skill documentation, use a body made only of x, only of X, or only of 0. Ferry also accepts x and X with the token format's separators, such as xoxb-xxxx-xxxx-xxxx. Arbitrary fake values can still trigger the deny rules.

Hooks

A hook that points at a file in your home directory breaks on the box if that file isn't there. Ferry checks each hook command before it carries it.

Ferry splits the command into words at spaces, quotes, ;, |, &, (, ), <, >, and =. A word that starts with ~/, $HOME/, or ${HOME}/ must point into a place Ferry fills on the box: a skill root, ~/.claude/agents, ~/.claude/commands, or a managed instruction file such as ~/AGENTS.md. An absolute path under your home, such as /Users/you/bin/check.sh, never passes, because the box home has a different path. Programs on PATH, such as jq, pass this check. So do $CLAUDE_PROJECT_DIR paths and absolute paths outside your home. You must make those programs and paths available on the box yourself.

Ferry leaves out each hook that fails the check and carries the rest. Ferry also removes matcher groups and events left empty by these exclusions. The sync continues, and ferry sync prints one Skipped hook: line per hook with its location, for example hooks.PreToolUse[0].hooks[1].command.

Scripts in ~/.claude/hooks are not carried. Move them into a carried directory, such as a skill, or onto PATH on both machines.

Claude plugins and settings

Claude does not install a plugin from settings alone. So on the box, ferry sync runs claude plugin marketplace add for each carried marketplace and claude plugin install for each enabled plugin. Then it writes the carried keys into the box ~/.claude/settings.json.

The box keeps all other keys, such as env and model. A carried key that your machine does not have is removed from the box. If you have no hooks key, the box ends up with no hooks key. A marketplace or plugin that the box cannot install gives a warning and does not stop the sync. A marketplace with a directory or file source lives on your machine only, so the box cannot add it.

ferry sync --dry-run lists the carried settings keys that will change, compared with the last publish in ~/.ferry/store/settings. It does not connect to the box, so it can't see changes someone made there.

:::info If a plugin in enabledPlugins comes from a marketplace that extraKnownMarketplaces does not list, run claude plugin marketplace add for it once on your machine. For example, claude plugin marketplace add anthropics/claude-plugins-official. :::

Adding skills

Use ferry skills add to install skills. It runs npx skills add and passes your arguments through:

`sh ferry skills add vercel-labs/agent-skills --skill frontend-design -a claude-code -y `

Ferry adds -g and --copy if you don't pass them, so the command above runs npx skills add vercel-labs/agent-skills --skill frontend-design -a claude-code -y -g --copy. A global copy install puts each skill in a real directory in a global skill root, and the next sync moves it into the store. A plain npx skills add installs into the current project, which Ferry does not see.

Add --project to keep a project install. Ferry then does not add -g. Put arguments after -- to keep Ferry from reading them. If npx skills add fails, Ferry exits with the same code.

Installing a skill does not publish it. Run ferry sync, or keep ferry watch running.

The Ferry agent skill

Ferry has its own agent skill, in skills/ferry. It tells agents on both machines how to work with Ferry. The most important rule is for agents on the box: do not edit a Ferry-managed file there, because the next sync resets it. The skill also tells agents to run --dry-run before ferry sync and ferry move, to leave ferry auth and confirmation prompts to you, and never to work around a deny rule.

Install it on your laptop and sync it to the box like any other skill:

`sh ferry skills add dlhck/ferry --skill ferry ferry sync `

When an installer replaces a link

Some installers replace the store link of a skill with a real directory that holds a newer version, for example in ~/.agents/skills. Sync then updates the store copy from that directory, publishes it, and links the directory back to the store. It does this only when:

- exactly one skill root has a real directory for the skill, - every other skill root that has the skill links to ~/.ferry/store/skills/, directly or through a chain of links, and - the store copy has no uncommitted changes in ~/.ferry/store.

In every other case, sync stops with a clash and leaves the decision to you. ferry sync prints Updated store skill from for each update, and ferry sync --dry-run lists them under Store updates from a harness root:.

Remote MCP servers

Ferry supports remote MCP server declarations with a name and an HTTPS URL. Servers such as Linear use OAuth for authentication. Ferry declares these servers on the box. It never copies an MCP token, so you log in to each server on the box.

Ferry reads only the MCP key of each file: mcpServers in ~/.claude.json, [mcp_servers] in ~/.codex/config.toml, and mcpServers in ~/.cursor/mcp.json. It does not include the account data from ~/.claude.json in the snapshot.

Ferry skips local servers, which have a command, and servers with a plain http:// URL. Sync prints one Skipped MCP server: line for each. Ferry stops the sync if a remote server has any of these:

- request headers (headers, headersHelper, http_headers, env_http_headers, http_headers_helper) - a bearer_token_env_var, an env or env_vars value, or args - a URL with a user name, a password, a token, or a query parameter such as api_key or token - a name with characters other than letters, digits, ., _, and -, because the name goes into commands on the box

On the box, sync declares each server:

- Claude: claude mcp add --transport http --scope user - Codex: codex mcp add --url . This command also starts a login and waits for it, so Ferry stops it after 20 seconds. Codex writes the declaration before the login starts. - Cursor Agent: Ferry writes the server into mcpServers in the box ~/.cursor/mcp.json, because Cursor Agent has no add command.

Pi has no MCP support of its own, so Ferry declares no Pi servers.

If the box already has a server with the same URL, Ferry leaves it alone and its login stays. If the URL changed, Ferry replaces the declaration and you log in again. Ferry never removes a server from the box. If you remove a server on your machine, remove it on the box yourself. A missing CLI or a rejected server gives a Box MCP: warning and does not stop the sync.

ferry status lists each box MCP server that needs a login, and the command to run:

`shellsession $ ferry status ... MCP logins: claude/linear: LOGIN REQUIRED, run ferry auth claude --mcp linear codex/linear: LOGIN REQUIRED, run ferry auth codex --mcp linear ... `

Ferry starts the tool's MCP login on the box under script, because Claude and Codex need a terminal, and prints the authorize URL. Open it on your machine. The browser then redirects to a localhost callback port, which Ferry forwards to the box for 300 seconds, so the tool on the box gets the callback and keeps the token. Press Ctrl-C when the browser reports success. The callback port must be free on your machine. Claude uses port 3118.

`shellsession $ ferry auth claude --mcp linear │ ◇ Starting the claude/linear MCP login on the box URL: https://mcp.linear.app/authorize?response_type=code&client_id=...&redirect_uri=http%3A%2F%2Flocalhost%3A3118%2Fcallback&... Open the URL in a browser on this machine. Ferry forwards local port 3118 to the box for 300 s. Press Ctrl-C after the browser reports success. `

Run ferry status again to verify the login. After a successful login, the server should no longer appear under MCP logins:.

Automatic sync

ferry watch runs in the foreground and watches every global skill root, ~/AGENTS.md, the Claude subagents and commands, and the carried Claude settings keys. When a change stays stable for one second, it runs a normal sync without --force. Network, SSH, and git failures retry with a backoff capped at 60 seconds. If the deny rules refuse a file, the watch names the path and waits for your next edit.

To run it as a user service:

`sh ferry watch install `

The installer uses the absolute path of the running Ferry executable and records the current PATH and, if set, SSH_AUTH_SOCK. Run it again after you move Ferry or either value changes.

On macOS, Ferry writes ~/Library/LaunchAgents/dev.ferry.watch.plist, unloads an older Ferry job, and bootstraps the new one. The log goes to ~/Library/Logs/ferry-watch.log. launchd does not inherit your shell's PATH or SSH_AUTH_SOCK, so before you install, make sure PATH contains git, ssh, and, for a Tailscale host, tailscale. If the snapshot remote needs an SSH agent, point SSH_AUTH_SOCK at its stable socket.

On Linux, Ferry writes ~/.config/systemd/user/ferry-watch.service, reloads the user manager, and enables and starts the service. Read the logs with:

`sh journalctl --user -u ferry-watch.service -f `

:::warning Do not put tokens or private keys in the plist or the unit file. :::

Keeping the agent tools up to date

ferry update updates the agent tools, not Ferry itself. To update a standalone Ferry installation, replace the executable with a newer release and restart the watch service if you use it.

The agent update commands are:

| Tool | Update command | On your machine | | --- | --- | --- | | gh | sudo apt update && sudo apt install gh -y | Skipped. Ferry does not guess your package manager. | | Claude Code | claude update | Runs if installed. | | Codex | codex update | Runs if installed. | | Pi | pi update | Runs if installed. Updates Pi only, not its packages. | | Cursor Agent | cursor-agent update | Runs if installed. |

Ferry finds each tool with command -v and never installs a tool on your machine. It prints the plan and asks first. --yes skips the prompt, and --dry-run prints the plan only. A failed update does not stop the others. At the end, Ferry names each failure and exits non-zero.

The watch can also run ferry update --yes once a day. Add this to ~/.ferry/config.toml and restart the watch:

`toml [update] watch = true `

The update runs next to the sync loop, so it never delays a sync. Ferry records the last start time in ~/.ferry/update-state.json, so restarting the watch does not trigger an extra update.

Passwordless sudo for the gh update

The gh update needs sudo on the box, and the watch has no terminal to type a password. Membership in the sudo group is not enough, because the default rule on Ubuntu and Debian asks for a password. Add this rule on the box, with your SSH user in place of :

`

/etc/sudoers.d/ferry (edit with: sudo visudo -f /etc/sudoers.d/ferry)

> AI + good judgment + taste = mega software

The more I thought about it, the more the plus signs felt wrong. Multiplication describes it better because AI amplifies the judgment and taste you bring to it.

AI × judgment × taste = mega software.

AI is an incredible accelerator. I am extremely bullish on it. It has completely changed how quickly we can turn an idea into working software. But faster production does not automatically result in a better product.

If you point AI at the wrong problem, it helps you get to the wrong result faster. If you accept the first reasonable output, you will end up with software that works but feels generic. Combined with good judgment and taste, however, it gives small teams a level of leverage that would have been impossible only a few years ago.

Why AI Slop Is So Easy to Recognize

There is a lot of software being produced right now. AI made plausible results incredibly cheap.

A first version can work, look acceptable, and come with professional sounding copy. But after using it for a few minutes, you notice that something is missing. The workflows feel generic. Every action seems equally important. Features exist because they were easy to add, not because somebody decided they should be there.

People have developed a feeling for this. They might not call it AI slop, and they might not be able to explain exactly what is wrong, but they recognize the absence of intent.

I don't think the bar for a good experience has increased that much. Clarity, coherence, usefulness, and care have always mattered. What changed is the quantity of software people encounter. We now see more software, compare more software, and recognize much faster when nobody held a high standard while building it.

Judgment Starts With Whom You Serve

For me, mega software is not software that tries to do everything for everyone.

It is software built for a clearly understood group of users. It is shaped around their everyday work, their problems, and the way they think. It improves their quality of life because somebody took the time to understand what matters to them.

Judgment decides whom the product is for, which problems are worth solving, which trade-offs to accept, and what to leave out. AI can help explore all of these questions. With enough context, it can propose very good solutions. But somebody still needs to decide which customer conversations matter, how to reconcile conflicting needs, and what the product should become.

AI can participate in that process, but a team first needs to develop and articulate its own judgment. Otherwise there is nothing meaningful for AI to work with.

Opinions Inside a Customizable Platform

At Vendure, we intentionally built a highly customizable ecommerce platform. Our users bring their own opinions about how their final solution should work and look, and we do not prescribe one universal commerce experience.

Our opinions live one layer lower. We care deeply about how developers reach their desired outcome. The primitives, extension model, workflows, and boundaries are our responsibility.

I have been thinking about this a lot while working on the next iteration of our design system and adopting it in the Vendure Admin Dashboard. The dashboard has many extension surfaces where developers can add their own components and actions. In the past, we placed very few restrictions on these surfaces. You could put almost anything almost anywhere.

That sounds flexible, but flexibility without constraints often transfers the design burden to every extension author and, eventually, to every user.

Take an action bar that allows extensions to add buttons. Previously, an extension could add another primary button. And another. The result was a busy interface where users could no longer tell which action mattered most.

With the new design system, extensions can still add actions, but they cannot add primary ones. Our opinion is simple: every view should have one clear primary action.

Developers still have the extension point, while the dashboard retains a clear hierarchy.

AI is excellent at accelerating the implementation of this migration. It can find extension surfaces, convert components, apply established patterns, and produce convincing interfaces. Deciding that unrestricted primary actions were a product-level design flaw required more than code context.

That conclusion came from context beyond the code: experience with the product, conversations with users, and a clear opinion about how the interface should behave.

Taste and High Benchmarks

Taste is harder to define because it is subjective. I see it almost as a character trait, something you develop over time through everything you have seen, built, rejected, and learned to care about.

Over time, you develop a feeling for details that are technically acceptable but do not fit the product you want to build.

Taste shows up in visual hierarchy, behavior, language, consistency, restraint, and hundreds of small details. But it also shows up in the benchmark you hold. It means not accepting the first plausible idea simply because producing another one is easy.

AI makes the first acceptable answer almost free, which makes it tempting to stop there. Taste shows in the willingness to keep questioning and improving that answer.

Taste cannot be fully captured in a checklist, but its consequences can be shared. A team can turn past decisions into design principles, strong defaults, component APIs, examples, naming conventions, and constraints. The rule that every view gets one primary action is one small example. Once encoded in the system, future developers and agents benefit from it without having to revisit the same discussion.

Good DX Helps Agents Too

The same thinking applies to developer experience. Agents write a lot of code today, but humans must still be able to read it, understand it, maintain it, and make confident decisions about it. Clear APIs, strong conventions, good names, explicit contracts, and understandable architecture make that possible.

Interestingly, the things that improve DX for humans usually improve it for agents too. A well-designed system contains less ambiguity. Agents can produce better code, navigate the codebase more reliably, and answer questions more accurately.

Software now has human and non-human users. The best experience is not identical for each group. A human might need a clear workflow and strong visual hierarchy. An agent might need predictable APIs and explicit boundaries. In both cases, good judgment begins by understanding who is using the product and designing around their needs.

A Better Way to Build With AI

I want us to use AI as much as possible while bringing more context, judgment, and taste to the process.

The loop I aim for looks like this:

1. Give AI the product context and constraints, not only the task. 2. Use it to explore several credible approaches. 3. Apply human judgment to choose the right trade-off. 4. Apply taste through critique and iteration until the result meets a high benchmark. 5. Encode the decision into the system so future humans and agents inherit it.

This changes the role of a product builder. More of our time can go into understanding users, translating their problems, setting the standard, and deciding what good means because AI takes on more of the implementation.

There Is No Universal Best

AI will become much better at proposing context-sensitive and tasteful solutions. I expect it to participate in more of these decisions over time.

But there is no universal best product. Best is different for every group of users, human or non-human. It depends on whom you choose to serve, which trade-offs you accept, and what you believe their experience should be.

As AI takes on more judgment, we will still have to choose which opinion it should follow and which outcome is worth pursuing.

That is why I am so optimistic about what comes next. Small, thoughtful teams have unprecedented leverage and can build exceptional software faster than ever before. To use that leverage well, they need to understand their users deeply, hold strong opinions, reject output that is merely plausible, and encode what they learn into the product.

Team,

I want to share some thoughts on something we've been discussing internally. Every developer knows the iron triangle: fast, good, cheap. Pick two. It's been the unspoken law of software development for decades.

I think that rule is dead. And I want to explain why I believe that, because it shapes how I think we should work going forward.

The Time Split Has Flipped

Before AI, building a feature estimated at three days looked something like this: 20-30% of the time went into thinking. Understanding the problem, laying out a plan, figuring out how to tackle it. The remaining 70-80% was spent writing code, writing tests, wiring things together. The mechanical work dominated.

Now that ratio has completely flipped. A three-day task becomes a day and a half. But here's the important part: out of that day and a half, roughly 70% goes into thinking about how to solve the problem. The remaining 30% is spent by AI agents actually building it.

And this is exactly why quality goes up, not down. Thinking time is directly proportional to quality. When you compress the mechanical part and expand the thinking part, you don't just ship faster. You ship something better.

Why We're Pushing for Speed

We're building commercial products and pushing hard to ship fast. Not because we love velocity for its own sake, but because we want to get to market as quickly as possible. We want real customer feedback. Not hypothetical theories from whiteboards and meeting rooms.

The only way to get meaningful feedback is to put something real in front of paying customers. And that means we need to build momentum: ship fast and ship quality. Because shipping garbage doesn't generate useful feedback. Customers can't tell you what to improve if the product doesn't work in the first place.

Execution Is No Longer the Bottleneck

The biggest shift I've personally felt is that execution is no longer a constraint. When I'm speaking to customers or prospects, I can identify their pain points, find the gaps between what we offer and what they need, and turn that into a solution. Fast.

The loop between learning about a problem and delivering a fix has become incredibly tight. I'm pushing into an 80/20 mentality: ship at 80%, then let the remaining 20% be shaped by real customer feedback from actual usage.

Here's what I want all of us to internalize: don't start by thinking about how much budget or time you have to implement something. Think about how you would build it in a perfect world. And then actually do that. AI removed the ceiling. The constraint used to be "what can I afford to build?" Now it's simply "what's the best solution?"

Rethinking Quality

When I say "quality," I don't just mean clean code. Code quality is one dimension under a much larger umbrella. Quality also means:

- Problem-solution fit. Does this actually solve the customer's problem? - Implementation ease. How easily can a customer adopt this for their specific use case? - Business value. Does it serve a clear business need?

Customers don't read your code. They don't care about your abstractions or your test coverage. They care about whether the product works and whether it solves their problem. Beautiful code that solves the wrong problem isn't quality.

This is really important for us as developers to understand: code quality is just one dimension, and it needs to serve a clear business need and a clear purpose.

The New Economics of Code Review and Testing

This part might be controversial, and I'm fine with that.

Why did we do code reviews in the past? Because every change to the codebase was expensive. A developer had to find the issue, understand the context, make the change. And if something slipped through, fixing it later was costly. Code review was a form of insurance: catch problems early to save money later.

But that economic argument has shifted. If fixing a bug reported by a real customer costs almost nothing and takes almost no time, the ROI of heavy upfront review changes fundamentally. The same logic applies to exhaustive test suites.

I'm not saying throw all discipline out the window. There's an important distinction here: yes, we can quickly fix a reported bug now. But some bugs cause real damage that no hotfix can undo. Data loss. Security incidents. Broken trust with customers. Being able to ship a fix in minutes does nothing to repair that kind of real-world damage.

So a solid infrastructure and test setup is still essential. The obvious things need to be covered. Critical paths, data integrity, security boundaries. That's non-negotiable. What changes is how much time we spend reviewing every cosmetic detail or writing tests for edge cases that will never happen in practice.

Architecture still matters enormously and needs deep human thinking, ideally done together with AI. Describe how customers use the product, find the right patterns for today, and think about how the problem might evolve in the future. Is the architecture ready to support a changed context down the road?

But spending hours reviewing every line of code for style and minor issues? That math doesn't add up anymore.

Smaller Teams, Bigger Output

The most expensive part of building software was never version one. It was everything after. All the iterations, touching existing code, maintaining backwards compatibility, responding to feedback across a growing codebase.

AI drives that iteration cost toward zero. Writing code, changing code, iterating on code. It approaches a zero-sum game. And that changes how we should structure ourselves.

A smaller team is an advantage, not a compromise. We communicate better. We can be in the same room, talk to customers constantly, share learnings internally. Each person tackles a problem, comes back with improvements, distills those learnings into a knowledge base that levels up the whole company over time.

That's what I want us to be. A tight group that learns fast and ships fast.

Where Confidence Really Comes From

Some people hear "smaller teams, faster shipping, less code review" and think it sounds reckless. I get it. But I'd challenge where we're building our confidence.

Confidence shouldn't come from passing tests in a GitHub Action. It should come from the sentiment and feedback of our actual customers. The people paying us to use the product. If they say "this is great, this solves exactly the problems we have, this helps us in our day-to-day business," then we're doing something right.

That's real confidence. Building it on vanity metrics in a test suite or a code quality dashboard is a false sense of security.

The Developer of the Future

If you're a developer who's only good at coding, you're going to have a hard time. The most important skill now is the ability to talk to your users, quickly build a mental model of their problems, and extract the information you need to improve the product.

You need to translate features into benefits. You need to bridge the gap between what a user struggles with and what the product should do. You need to build these mental models fast and turn them into action.

Our role is evolving from "code writer" to "problem translator." The code is the easy part now. Understanding the problem, that's where the value is.

What This Means for Us

The iron triangle isn't gone. It's just that AI has made execution so cheap and fast that the triangle collapses. We can have all three: fast, good, and cheap. But only if we stop optimizing for code and start optimizing for customer outcomes.

Let's do exactly that.

This article is the start of documenting my personal journey from founder to what I hope will become a true CEO. I'm writing this because during my research, I found surprisingly few public resources about this specific struggle that technical founders face—the ones who can code, sell, and market, but suddenly don't know where they fit anymore. If you're reading this and nodding along, this is for you.

The Comfort of Exhaustion

When I started Elevantiq in 2019 from rural Kitzbühel, Austria—a place dominated by tourism and construction, not exactly a tech hub, known for the famous Hahnenkamm Ski Race and loved by the millionaires and billionaires of this world—I had zero experience building a company. But I had the energy and hunger to do everything myself. In the morning I'd be building features for clients, then jump into meetings before lunch, carve out two hours for marketing, and immediately switch to emergency client support because something went wrong. Days didn't end at 5pm, they ended at 8 or 10pm, and I was exhausted. But it felt good. I could see my to-do list getting shorter, feel the progress in my bones through sheer physical exhaustion, and know that I was moving the company forward with my own two hands.

Everyone tells you the same thing as you grow: "Make yourself irrelevant. Step out of day-to-day operations. Focus on what's 2-3 years ahead, not the now." I read this in every business book, every founder biography, every leadership article. So I built a great leadership team—Max, who gradually took over more and more operations starting in 2021 and eventually became COO, and Michael, who joined our universe in 2022 through a joint venture focused on Vendure and now leads all technical work as CTO. I trusted them completely, and they delivered beyond expectations. The team was committed in ways I never forced them to be, fixing bugs late Friday evenings not because they had to, but because they cared.

Here's what made the delegation "easy" in hindsight: I had hired people who were strong enough to not need me. When my anxiety kicked in later and I pushed to reconsider our entire strategy multiple times throughout the year, Max and Michael had strong enough convictions to push back. They didn't just execute my vision—they had their own, and they defended it. The company kept moving in the right direction not because I was steering it, but because I had built a system that could steer itself. This was exactly what I wanted, and exactly what terrified me.

But this created an unexpected problem: What was my role now?

The Identity Crisis of a Technical Founder

I was left with marketing and sales. I don't dislike this work—it's necessary, and I'm decent at it—but it doesn't fulfill me the way engineering does. I did it because I'm used to doing things I don't love when they need to get done, and if it wasn't me, who would it be? But the moment an opportunity to code appeared—supporting Vendure's new admin dashboard, building the new website—I'd drop everything and dive in. Then I'd realize I was avoiding what I should be doing, force myself back to marketing tasks, but never deliver anything that felt meaningful to me because I was constantly monitoring what was happening on the engineering side.

For the first time in my company's life, I couldn't see the day-to-day progress. I wasn't in the trenches anymore, and that meant I couldn't feel how well we were working, how fast we were moving forward. My mind filled that vacuum with anxiety. Were we heading in the wrong direction? Was our strategy wrong? Was the competition pulling ahead? Should we change everything? The urge to throw everything up in the air was overwhelming because I convinced myself it wasn't working—not because of any real evidence, but because I couldn't see the daily wins anymore.

And then there was the deeper issue: my self-worth. I had this idea that I needed to be the best software engineer in the company, that everyone should look up to me for my technical skills—my speed, my ability to solve problems the moment they arose. When I stepped back from that, my value to the company felt like it had dropped to zero. What was I actually doing that moved us forward if I wasn't coding? The question haunted me.

Taking Space to Think

By November 2025, I was spinning. I told Max and Michael I needed space until the end of the year and essentially stepped away, telling the team I was focusing on a private construction project with my brother. Everyone understood. The first two weeks I did basically nothing—spent time with my girlfriend, went to the gym, read books, occasionally coded for fun. But I also started researching. Not the company's problems. My problem.

My research broke into three phases: 1. Are there others who experience this? 2. What is a CEO actually supposed to do? 3. And most importantly, do I really want to be a CEO?

I searched for "technical founder identity crisis" and similar terms, diving through blogs, forums, and business publications. I found maybe five articles from other technical founders describing similar experiences—not many, but enough to know I wasn't alone. Then I immersed myself in understanding what CEOs actually do: reading books on leadership transitions, listening to podcasts with founder-CEOs, watching interviews with successful technical founders who made the leap, and buying articles from Harvard Business Review on the founder-to-CEO journey. This wasn't the surface-level "set vision and strategy" stuff—I wanted to understand what world-class CEOs actually spend their time on, how they think, how they create value when they're not personally building the product.

---

Here are some of my raw notes that I took while researching:

- As founder to need to shift from operator to architect - The founder finds value in their own output; the CEO finds value in the system's output - Founders manage employees; CEOs lead leaders - The founder is a firefighter, addicted to the urgency of the next crisis. The CEO is a strategist, focused on the five-year horizon - Founders believe the best product wins. CEOs know the best culture wins, because it can build any product - Founders equate speed with doing things themselves, CEOs see scale in systems that run independently - As a founder your self-worth becomes a function of your to-do list - Becoming a CEO from a founder is ultimately about pulling away from daily operations. The discipline is in resisting the lure of the urgent. - Instead of being the best worker in the room, the founder must design the system that makes work flow without them. This is the essence of the founder to CEO transition. It is not abandoning responsibility but elevating it. - The 5 most important shifts from founder to CEO - doing→designing systems - deciding→coaching decisions - managing→leading leaders - short-term→long-term - product→culture obsession - A founder brings an idea into the world. A CEO sets direction while building and motivating an entire organization to capitalize on the opportunity. - Disseminate Culture from the Top by holding team discussions and view it as a strategy session - Getting mentors for different areas is incredibly important to always self-reflect and learn - Creating space to reflect is massively important (aka taking vacation) - Recruiting must be a top priority - the CEO sets the tone. The people you hire are your brand. - Create alignment by establishing overarching corporate goals and empower each "unit" of the organization to create their own under this umbrella

---

The last question took longer. I tried to remember why I started this company in the first place. I went back through old notes and emails from 2019, when I was still freelancing. What I found was revealing: I had told everyone back then that I wanted to build a team because I was tired of working alone on someone else's projects. I wanted to work with others on our stuff—building a team, building a company, building products, delivering unique services.

The hilarious realization: where I am now is exactly what I dreamed of back then.

I had achieved my first major challenge—building a profitable, stable, growing company with an incredible team. But I had no next challenge focused on me as a person, on my own growth and development. The crisis wasn't that I had failed; it was that I had succeeded at the first mountain and couldn't see the next one to climb.

Redefining Value

Somewhere along the way, I had gotten the equation backwards. I thought making myself irrelevant meant making myself worthless. But the dream was never to be the best engineer in the room—it was to build something bigger than myself, to have a team executing a shared vision.

I decided my next challenge would be to become the best CEO I could be—measured not by traditional metrics, but by whether I'm genuinely learning new skills and staying out of my comfort zone of software engineering, even when coding feels easier. Success means resisting the pull back to what's familiar and mastering an entirely new set of skills, behaviors, and ways of thinking.

The shift required reframing everything: My value isn't measured by my personal output anymore, but by the company's output. Founders equate speed with doing things themselves; CEOs see scale in systems that run independently of them. I need to figure out how to make these systems visible to myself—what metrics, processes, and markers of progress matter when I'm not personally shipping code. I don't have all these answers yet, and that's part of the work ahead.

Going Forward

My focus is shifting entirely to what only a CEO can do: Culture. Systems. Recruiting. Strategy. Vision. Alignment. I'll still code occasionally, but with clear goals and oversight from others—otherwise I know I'll relapse and disappear into the flow state for weeks.

Hiring will become a major focus, not to suddenly scale to 40 people next year, but to invest seriously in employer branding, building a network of potential talent, and establishing ourselves in Vienna's and Europe's tech scene. I'm also hiring an experienced Growth leader to take over marketing entirely so I can focus on sales—something I actually love and get amazing feedback on, partly because my technical knowledge lets me connect dots quickly and give qualified answers instead of generic sales talk.

Most importantly, I'm being open with my team about this journey. Being vulnerable about the fact that nobody is born knowing how to be a CEO, that I'm learning too, and that this is completely normal.

The Fire Returns

My fire is back. My hunger is back. I'm more motivated going into 2026 than I've been in a while, knowing that this year will mark the next major step—for the organization, but also for me as a person.

But this isn't a success story yet—it's the beginning of one. I don't have the systems figured out. I don't know if I'll succeed at becoming a true CEO. I might discover I hate it, or that I'm terrible at it, or that the role doesn't suit me. What I do have is clarity on the challenge ahead and the fire to pursue it. That's enough to move forward with purpose.

I plan to write a follow-up article in July 2026 to share what I've learned, what worked, what didn't, and how this journey has evolved. Taking these two months to step back and think was the best decision I've made for myself and the company in years.

I keep coming back to one insight that reminds me daily why I'm doing this:

> A founder who continues to define their value by personal effort inevitably caps growth. A CEO, by contrast, defines value by the systems they design and the leaders they empower.

If you're a technical founder struggling with similar questions about your role, your value, and your purpose as your company grows—you're not alone. And the answer might be simpler than you think: the dream you're living now might be exactly the one you started with. You just need a new challenge to chase.

---

This is the first in a series documenting my journey from founder to CEO. Follow along at dlhck.com for updates.

TypeORM stands now at more than 12M monthly downloads and 36k GitHub stars. The project is truly alive!

!TypeORM Downloads

Now we're working toward v1.0.0 and our next big milestone: establishing an official TypeORM association with clear governance, committed maintainers, and sustainable funding.

Why an Association in Austria?

We're incorporating in Vienna, Austria for several practical reasons:

Vienna hosts numerous international non-profit organizations and institutions. Austria maintains political neutrality—important for a project open to everyone globally, regardless of geography or politics. Michael and I live here, making incorporation straightforward. The bureaucracy and costs are minimal.

Our North Star

We're building toward:

- Clear governance structure with a board steering technical direction and strategic partnerships - Committed maintainers investing 2-4 hours weekly, compensated for their work so TypeORM isn't an afterthought - Sustainable sponsorships that fund the maintenance team - Market visibility alongside Drizzle, Prisma, and other modern ORMs - Benefits and incentives that make sponsoring TypeORM attractive to companies and individuals

The Roadmap

Step 1: Incorporation Found the association with proper bylaws (~€50 incorporation cost). Elevantiq will cover upfront costs and submit invoices to OpenCollective.

Step 2: Build the Board Find a third board member responsible for technical steering—triaging, roadmap planning, releases, and community communication. Michael and I will focus on database company relationships, framework collaborations, and public communications.

Step 3: Improve Financial Infrastructure Move beyond OpenCollective's current limitations to better manage donations, funds, and payments to maintainers.

Step 4: Grow the Maintenance Team Build toward 6-8 maintainers over 18-24 months, each committing 2-4 hours weekly. Compensation will be buying-power adjusted hourly rates—not market rates, but fair reimbursement for opportunity cost.

Step 5: Secure Sponsorships Establish recurring donations from database companies, frameworks, and organizations to fund the team.

Step 6: Establish Release Discipline Create a maintainable release routine prioritizing stability over rapid innovation.

Step 7: Transparency Operate with open accounting—visible incoming sponsorships and outgoing payments.

Join Us

Feedback: What are we missing? What could be better? Let us know.

Third Board Seat: We're reaching out to candidates who've shown strong commitment over recent months.

Maintenance Team: Interested in joining the official maintenance team? Email your application and tell us why you should be part of TypeORM's future.

Sponsorships: Work at a database company interested in collaboration? Have budget for open source sponsorships? Reach out to us.

TypeORM has been a cornerstone of the TypeScript ecosystem. Together, we're building the foundation for its next chapter.

This guide contains every hard-won lesson from deploying and maintaining Next.js applications at scale. Whether you're using Kubernetes, Docker Swarm, or platforms like Northflank and Railway, these solutions will save you from the production challenges I've already faced.

The Hidden Challenge: Why Next.js Breaks at Scale

Here's what nobody tells you about self-hosting Next.js: the framework assumes it's running as a single instance. The moment you spin up multiple replicas for high availability (which you absolutely need in production), everything that touches the filesystem becomes a problem.

Next.js loves writing to disk. Cache files, optimized images, temporary data, it's all stored locally in .next/cache. This works perfectly on Vercel because they abstract this complexity away. But when you have three replicas running simultaneously, you get this challenging scenario:

- User hits replica 1: Cache miss, generates content, stores locally - Same user hits replica 2: Cache miss again, regenerates identical content - Result: Inconsistent performance, wasted resources, confused users

This guide covers six critical areas where Next.js needs special configuration for production self-hosting: Dockerfiles, reverse proxies, caching, image optimization, CDNs, and server actions. Get any of these wrong, and your application may not function as expected in production, often in ways that only appear under load.

Important Context

It's worth noting that Next.js documentation states that ISR and caching work "automatically when self-hosting" with next start. The challenges we're addressing here primarily emerge when:

- You need horizontal scaling with multiple replicas - You're operating at significant scale (thousands of concurrent users) - You require zero-downtime deployments - You have strict performance SLAs

For smaller deployments or single-instance setups, many of these issues won't apply.

A Note on Context and Scope

This guide is based on real-world experience deploying Next.js applications serving thousands of concurrent users in enterprise e-commerce environments. The solutions presented here address challenges that primarily emerge at scale with:

- Multiple replica deployments - Kubernetes or similar orchestration - Strict performance and availability requirements - Complex caching needs

Many of these issues are standard distributed systems challenges that aren't unique to Next.js. The framework handles many scenarios well out of the box, especially for single-instance deployments. These solutions are for when you need to go beyond the default setup.

Performance metrics mentioned are from production systems under NDA and will vary significantly based on your specific implementation, infrastructure, and traffic patterns.

1. Production-Ready Dockerfiles: The Foundation

Start with the official Next.js multi-stage Dockerfile, but don't use it as-is. Here are the essential modifications:

`dockerfile

In your base stage

Add health checks for zero-downtime deployments

:::info Health checks are critical for zero-downtime deployments, but can be tricky to get right, as they might lead to restart loops. Please verify that health checks are working before deploying.

If you're using a platform like Northflank or Railway, they might have a health check feature that you can use. If not, you can use a simple HTTP health check like the one above. :::

Why Health Checks Matter More Than You Think

Without proper health checks, your orchestrator doesn't know when a replica is ready to serve traffic. During deployments, this causes:

- Request failures as traffic routes to starting containers - Downtime when rolling updates kill healthy replicas before new ones are ready - Zombie containers that crashed but still receive traffic

The health check configuration above ensures:

- New replicas are fully started before receiving traffic - Crashed replicas are detected and replaced within x seconds - Zero-downtime deployments actually achieve zero downtime

2. Reverse Proxy Configuration: The Streaming Killer

Your reverse proxy or ingress controller (Traefik, NGINX, HAProxy, Kong) needs specific configuration for Next.js. The critical requirement: disable response buffering.

Without this, React Suspense and streaming responses may not function as expected. Your users see blank pages or experience massive delays as the proxy buffers the entire response before sending it.

NGINX Configuration

Add this header in your next.config.js:

`javascript module.exports = { async headers() { return [ { source: "/:path*{/}?", headers: [ { key: "X-Accel-Buffering", value: "no", }, ], }, ]; }, }; `

Traefik with Docker Swarm

`yaml labels: - "traefik.http.middlewares.nobuffering.buffering.maxResponseBodyBytes=0" - "traefik.http.routers.myservice.middlewares=nobuffering" `

This single configuration issue has caused more production incidents than any other in my experience. Test streaming responses explicitly before going live.

3. Distributed Caching with Redis: The Filesystem Alternative

The default filesystem cache is completely incompatible with horizontal scaling. You have three options:

1. Shared volume (doesn't work): File locking issues, race conditions, data corruption 2. Master-slave setup (challenging): Requires complex coordination to ensure only designated instances write to cache, which can limit write throughput 3. Redis (works perfectly): Centralized, fast, battle-tested

Official Cache Handler Approach

The Next.js documentation provides an example of creating a custom cache handler. Here's the official approach:

`javascript // From Next.js official documentation module.exports = { cacheHandler: require.resolve("./cache-handler.js"), cacheMaxMemorySize: 0, // disable default in-memory caching }; `

While you can implement your own cache handler following the official documentation pattern, I strongly recommend @trieb.work/nextjs-turbo-redis-cache for its production-ready features. The official docs even provide a Redis example that you can adapt to your needs.

_Note: This is a third-party solution we've found reliable in production. It's not officially endorsed by Vercel/Next.js. Always evaluate third-party packages for your security and compliance requirements._

Basic setup:

`javascript const nextConfig = { cacheHandler: require.resolve("@trieb.work/nextjs-turbo-redis-cache"), cacheMaxMemorySize: 0, // Disable in-memory caching }; `

Critical Warning: The Monorepo Trap

If you're using a monorepo (Nx, Turborepo, etc.), require.resolve can cause connection failures. The cache handler file gets duplicated during build, breaking the singleton pattern. Solution:

`javascript const path = require("node:path"); const CopyPlugin = require("copy-webpack-plugin");

const nextConfig = { cacheHandler: path.join(__dirname, ".next/server/cache-handler.js"), // Absolute path cacheMaxMemorySize: 0, webpack: (config, { isServer }) => { if (isServer) { config.plugins.push( new CopyPlugin({ patterns: [ { from: "./cache-handler.js", to: "./cache-handler.js", }, ], }) ); } return config; }, }; `

Performance Optimization: Cache Size Matters

In our experience with large e-commerce deployments, we discovered that caching full API responses led to slower Redis read times. The solution:

- Pre-process data before caching - Only cache essential fields - Monitor cache item sizes (we target under 1MB based on our infrastructure) - Monitor Redis memory usage constantly

Your optimal cache size will depend on your Redis configuration, network latency, and data structure.

Also, be extremely careful with data passed from server to client components. Large prop sets create:

- Massive cache entries - Huge DOM sizes - Slow hydration - Poor Core Web Vitals

4. Image Optimization: External Processing is Non-Negotiable

Next.js's built-in Sharp-based image optimizer stores resized images on the filesystem. With multiple replicas, every instance processes the same images independently. This is wasteful and slow.

Solution 1: Image Transformation Services

Use ImageKit, Akamai, or similar:

_Note: These are third-party services. Always evaluate them for your security, compliance, and cost requirements._

`javascript const customLoader = ({ src, width, quality }) => { return `https://cdn.your-company.com/transform?url=${src}&w=${width}&q=${ quality || 75 }`; };

module.exports = { images: { loader: "custom", loaderFile: "./image-loader.js", }, }; `

Solution 2: Self-Hosted with IPX

Deploy ipx as a separate service:

_Note: IPX is a third-party open-source solution. Always evaluate third-party packages for your security and compliance requirements._

Benefits:

- Centralized image cache shared across all replicas - Reduced memory usage in Next.js containers - CDN-ready with proper cache headers - Consistent performance across all instances

5. CDN Configuration: Cache-Control is Everything

A CDN dramatically improves performance, but misconfiguration breaks your application. The golden rule: Your CDN must respect the origin's Cache-Control headers.

Next.js sets different cache headers based on:

- export const revalidate = 3600 - Dynamic routes - Authentication state - Cookie presence

If your CDN ignores these headers, you'll serve stale content to logged-in users or cache personalized pages publicly.

Testing Checklist

Before production:

1. Verify static assets are cached (CSS, JS bundles) 2. Test that revalidate values are respected 3. Confirm dynamic routes bypass cache appropriately 4. Validate authenticated requests aren't cached 5. Check cache invalidation works as expected

6. Server Actions: The Deployment Consistency Challenge

Server Actions use encrypted identifiers that change with every build by default. During rolling deployments, this causes the dreaded error:

:::error "Failed to find Server Action "XYZ". This request might be from an older or newer deployment." :::

The Fix

Set a consistent encryption key per environment:

`bash

In your .env file

Generate different keys for each environment (dev, staging, production) but keep them consistent across deployments within that environment.

Security Consideration for Server Actions

It's crucial to understand that according to the Next.js documentation, Server Actions "create a public HTTP endpoint and should be treated with the same security assumptions." This means:

- Always validate and authorize within your Server Actions - Treat them like public API endpoints - Never rely solely on encryption for security - Implement proper authentication and authorization checks

The encryption key consistency we discussed above helps with deployment, but is not a security feature by itself.

Real-World Performance Results

After implementing these solutions in large-scale enterprise commerce projects:

- Response times: Significant reduction for cached content (specific metrics vary by implementation) - Server load: Substantial decrease during peak traffic - Deployment failures: Zero-downtime achieved consistently - User experience: Eliminated inconsistent page load times

Note: These results are from enterprise deployments under NDA. Your results will vary based on traffic patterns, infrastructure, and implementation details.

Your Production Checklist

Before deploying self-hosted Next.js at scale:

- Multi-stage Dockerfile with health checks configured - Reverse proxy with disabled buffering verified - Redis cache handler installed and tested under load - External image optimization service configured - CDN respecting Cache-Control headers validated - Server Actions encryption key set consistently - Load testing completed with multiple replicas - Monitoring for cache hit rates implemented - Alerting for replica health configured - Rollback strategy tested

Conclusion

Self-hosting Next.js at scale is absolutely achievable, but it requires understanding and solving these architectural challenges upfront. Every issue I've outlined here cost us hours or days of debugging in production. Learn from our mistakes.

The solutions in this guide are battle-tested with thousands of concurrent users. They work. But remember: production is where theory meets reality. Monitor everything, test thoroughly, and always have a rollback plan.

If you're implementing these solutions and hit edge cases I haven't covered, I'd love to hear about them. The Next.js ecosystem evolves rapidly, and sharing knowledge helps us all build better production systems.

But I never found the time or the motivation to actually build my own website (again).

Building such a simple website is not tickling my brain enough to get me excited.

And I need excitement to get me going.

Thanks to Cursor and Next.js I was able to build this website in a few hours.

This article is just a memory for myself to remind me when I have started to write again. Of course I already have some ideas for articles swirling around in my head, so let's hope that I'll stick with it.

Why do I want to write? Well, there are a few reasons and all of them are egotistical to some degree.

- I want to share my thoughts and ideas with the world. - I want to improve my writing skills. - I want to improve my thinking skills. - I want to improve my communication skills. - I want to improve my problem solving skills. - I want to improve my decision making skills. - I want to improve my leadership skills.

I'm not sure if I'll continue to write here, but I'm glad I took the first step.