DEV Community: johnohhh1

I spent 6 hours debugging a VM that didn't need to exist

johnohhh1 — Thu, 16 Apr 2026 17:07:13 +0000

The setup

I'm trying to get Anthropic's Cowork feature running on Linux. Cowork is officially Mac-only. It works by booting a sandboxed Ubuntu VM inside Claude Desktop, then running Claude Code inside that VM so it can safely read and write your project files.

Claude Desktop for Linux exists as a community build — I maintain a deb package that repackages the official Windows MSIX for Ubuntu. The desktop app works fine. But Cowork doesn't start. The VM service socket never appears.

So I open Claude Code on my terminal and say: fix this.

The rabbit hole

What follows is roughly 6 hours of two problem-solvers — me and Claude — locked in a feedback loop where we're both hyperfixated on the same wrong question: how do we make this VM boot?

Here's an abbreviated tour of the damage:

Hour 1: We extract the Electron app's app.asar, find the minified JavaScript, locate the platform check. The Windows version uses a named pipe \\.\pipe\cowork-vm-service. We patch it to use a Unix socket. We write a custom Node.js service that listens on that socket and spawns QEMU. Claude Desktop connects. It sends startVM. QEMU boots. The guest agent connects. Progress.

Hour 2: The installSdk call loops forever. We make it return success locally. Startup completes in 2.5 seconds. Then isProcessRunning keepalives timeout because the guest agent isn't responding. We discover the guest's sdk-daemon binary uses vsock, not the virtio serial port we set up.

Hour 3: The sdk-daemon inside the VM can't find the "smol-bin" disk. It scans for NVMe devices. QEMU's NVMe emulation produces "bogus Namespace Identifiers" that the Ubuntu 22.04 kernel rejects. nvme1n1 never appears as a block device. We try uuid=auto, nguid=auto, eui64-default=on. None of it works.

Hour 4: We try SCSI instead of NVMe. The device appears as /dev/sda but the sdk-daemon only scans NVMe paths. We try virtio-blk. Same. We discover the "smol-bin" disk is actually just an empty ext4 sessions disk, not the binary distribution we thought. We patch the rootfs with a fake tmpfs mount. The sdk-daemon gets past the smol-bin check.

Hour 5: New error: VirtioFS mount fails. We add virtiofsd and memory-backend-memfd to QEMU. The sdk-daemon gets further. It mounts the sessions disk. It starts a MITM proxy. Then: [rpc] connecting to host CID=2 port=51234 — connection refused. We write a Python vsock bridge. It connects.

Hour 6: The bridge works but the sdk-daemon crashes on restart because the fake mounts get torn down. We patch the rootfs systemd units. We patch the wrapper script. We fight with rootfs journal persistence. We're deep in the weeds of a QEMU VM running Ubuntu 22.04 inside Ubuntu 26.04, bridging vsock through Python to Node.js through Unix sockets to Electron, trying to make a Go binary that was compiled for Hyper-V happy inside KVM.

Then I find this repo.

The fix was 3 lines of thinking

The entire README of claude-cowork-linux by @johnzfitch can be summarized as:

Why does Cowork use a VM? Because it needs a Linux environment to run Claude Code. On macOS, that means spinning up an Ubuntu VM. On Windows, same thing — Hyper-V boots a Linux guest.

But you're already on Linux.

So just... don't boot the VM. Stub out the macOS native module. Run Claude Code directly on the host. Translate the VM paths to real paths. Done.

The install took 30 seconds. Cowork started immediately. The spawned Claude Code process ran for 23ms to confirm, then the full session worked.

Every single thing I spent 6 hours debugging — NVMe namespace identifiers, vsock port discovery, VirtioFS permissions, rootfs systemd patches, Python-to-Node socket bridges — was a consequence of not asking why the VM existed in the first place.

The pattern

This is a pattern I've seen before but never this clearly:

Hyperfixation on the error, not the cause.

The error said "VM service not running." So we made the VM service run. Then the error said "guest agent not connected." So we connected the guest agent. Then "smol-bin device not found." So we tried to make the device appear. Every error led to the next error, and we solved each one, and we were making "progress" the entire time.

But the actual cause was upstream of all of it: the VM shouldn't exist on Linux in the first place. We never questioned the premise. We just tried to make the wrong thing work really, really well.

And here's the uncomfortable part: Claude Code was the perfect partner for this kind of mistake. It's incredible at "make X work" tasks. Give it an error, it'll fix it. Give it the next error, it'll fix that too. It will reverse-engineer a binary's vsock port by reading Go strings out of an ELF executable at 2 AM and not complain. It's a relentless debugger.

But relentless debugging is exactly what you don't need when the whole approach is wrong. What you need is someone to say: wait, why are we doing this?

What I should have done

Before touching any code:

Ask what the VM is for. It runs Linux so Claude Code has a sandbox. We're on Linux. We don't need the sandbox VM.
Search for prior art. Someone already solved this. 30 seconds of GitHub search would have found it.
Question the frame. The logs said "VM service not running" and I read that as "I need to make the VM service run." A better read: "this component assumes a VM is needed — is it?"

The takeaway

AI coding assistants are force multipliers. If you're pointed in the right direction, they're unbelievable. If you're pointed in the wrong direction, they'll help you dig the most elaborate, well-engineered hole you've ever seen.

The fix for Cowork on Linux was a JavaScript stub and a path translation layer. We built a QEMU VM orchestrator with NVMe disk emulation, vsock bridging, VirtioFS shared filesystems, and rootfs systemd patching.

Next time the debugging gets complicated, I'm going to stop and ask: am I solving the right problem, or am I just solving the next error?

Credit to @johnzfitch for claude-cowork-linux, which solved in an afternoon what I couldn't solve in a night. The deb package with Cowork support is at johnohhh1/claude-desktop-ubuntu.

I Ported ComfyUI Desktop to Ubuntu 26.04

johnohhh1 — Wed, 15 Apr 2026 03:06:51 +0000

Another Desktop App ported to Linux That was not available. I will Keep going until release day or I run out of apps to port. Let me Know what one you would like to see next!

The official ComfyUI Desktop app ships for Windows and macOS.

I wanted it on Ubuntu 26.04.

So I ported it.

Not a web wrapper. Not a fake launcher. Not a shell script around a browser tab.

The actual desktop app.

The Goal

I had two requirements:

build the real app on Linux
make it usable on a machine that already runs ComfyUI normally

That second one mattered more than people think.

If a Linux user already has:

a real ~/ComfyUI install
a running server on 127.0.0.1:8188

then the desktop app should not pretend the machine is blank and try to push a fresh install into ~/Documents/ComfyUI.

That is bad product behavior, even if the package technically launches.

The Starting Point

The upstream repo is here:

https://github.com/Comfy-Org/desktop

At first glance it looks cross-platform enough:

Electron app
bundled frontend assets
uv bootstrap
asset build pipeline
electron-builder config with Linux bits already half-present

But “half-present” is the dangerous state.

That usually means:

some paths exist
some assets exist
some packaging config exists
and the app still does not actually ship on Linux

Which is exactly what was going on here.

The Real Problems

There were a few distinct failures.

1. Linux was gated out of asset/bootstrap flow

The app would build fine for supported platforms, but Linux was not being carried all the way through asset setup and build verification.

That meant some Linux artifacts were never properly prepared even though the source tree looked close.

2. Packaged builds were missing `desktop-ui`

This was the first hard packaging bug.

The app launched, then died with a file-not-found error because the packaged build did not contain the desktop onboarding UI bundle.

That is the kind of bug that makes a port look dead before you even get to runtime behavior.

3. AppImage hit Electron sandbox issues

This is the standard Linux Electron tax.

The AppImage mounted fine, but Chromium tripped over the sandbox helper and aborted before the app could become useful.

I did not waste time pretending AppImage was the right hill to die on.

For Ubuntu, .deb was the better target.

4. Linux runtime assumptions were wrong

The app still had platform checks and install behavior that were effectively “Windows/macOS first, Linux later.”

A Linux port cannot just compile. It has to stop acting like Linux is unsupported at runtime.

5. Existing Comfy installs were ignored

This was the most important UX issue.

On my machine, ComfyUI was already installed and already running in the browser.

The desktop app still tried to start from scratch and push a managed install path into Documents.

That is technically launchable, but functionally wrong.

So I fixed it.

What I Changed

I split the work into build fixes, runtime fixes, and “make it behave like a sane Linux app” fixes.

Build and packaging fixes

enabled Linux asset bootstrap
enabled Linux build verification
packaged the missing desktop-ui bundle
switched the Linux target to .deb

Runtime fixes

added Linux config/reset path handling
made Linux hardware validation non-fatal
added fallback behavior for missing compiled requirements
added Linux-safe Electron startup defaults

Existing-install behavior

This was the good part.

I changed the app so it now:

prefers an existing ~/ComfyUI directory as the default base path
detects a live local Comfy server on 127.0.0.1:8188
persists external-server mode into desktop config
skips the desktop-managed venv validation path when attaching to that external server
opens the frontend against the already-running instance instead of forcing first-run install flow

That last bit is what makes the port feel real instead of merely “bootable.”

Why `.deb` Won

I know someone will ask why I did not just ship AppImage.

Because Ubuntu users need something that works, not something ideologically pure.

The .deb route gave me:

stable installation under /opt/ComfyUI
normal desktop integration
no AppImage sandbox headache
a clean launcher path

On Linux, packaging format is not theology. It is operational reality.

What the App Does Now

On an Ubuntu 26.04 machine with an existing Comfy setup:

launch the desktop app
it detects ~/ComfyUI
it sees the live server on 127.0.0.1:8188
it stores that as the desktop install state
it attaches instead of onboarding

That is the behavior I wanted from the start.

Commands I Actually Used

Install dependencies:

corepack enable
corepack yarn install

Bootstrap app assets:

corepack yarn make:assets

Verify:

corepack yarn typecheck
corepack yarn vitest run

Build the package:

corepack yarn make

Install the package:

sudo apt install ./dist/ComfyUI-0.8.30-amd64.deb

The Nice Surprise

The upstream repo was not hopeless.

This was not one of those situations where “Linux support” secretly meant rewriting the app from scratch.

Most of the work was:

finishing incomplete Linux paths
fixing packaging omissions
picking the right distribution target
making startup logic respect an existing local Comfy workflow

That is still real work, but it is not fantasy.

The Useful Lesson

A port is not finished when the window appears.

A port is finished when the app behaves correctly on the target machine.

For this one, the difference was:

not just “ComfyUI Desktop launches on Ubuntu”
but “ComfyUI Desktop understands an Ubuntu user who already runs ComfyUI”

That is the difference between a demo and a port.

Upstream and Source

Upstream desktop app: https://github.com/Comfy-Org/desktop
ComfyUI core: https://github.com/comfyanonymous/ComfyUI

My Repo

https://github.com/johnohhh1/comfyui-desktop-port-linux.git

git clone https://github.com/johnohhh1/comfyui-desktop-port-linux.git

Kimi Desktop on Ubuntu 26.04: Fixing the Broken .deb with Tauri v2

johnohhh1 — Tue, 14 Apr 2026 02:54:43 +0000

You install the official Kimi desktop .deb, fire sudo dpkg -i, and boom:

dpkg: dependency problems prevent configuration of kimi:
 kimi depends on libwebkit2gtk-4.0-37; however:
  Package libwebkit2gtk-4.0-37 is not installed.

That library doesn't exist on Ubuntu 24.04, let alone 26.04. It was removed from the repos over a year ago. The official Kimi desktop package is built on Tauri v1, which hard-depends on libwebkit2gtk-4.0.so.37 — a library that shipped with webkit2gtk 4.0, superseded by 4.1 and then dropped entirely.

So the app is just... broken on any modern Ubuntu. Here's how I fixed it.

The problem in one sentence

Tauri v1 → libwebkit2gtk-4.0 → removed from Ubuntu 24.04+ → dpkg fails.

The fix: rebuild with Tauri v2

Tauri v2 links against libwebkit2gtk-4.1, which is the version shipped in Ubuntu 24.04 and 26.04. So the fix is straightforward: rebuild the app with Tauri v2 instead of v1.

I used Pake v3, which wraps any web app into a native desktop app using Tauri under the hood. One build script, one config file, and you get a .deb that actually installs.

What you get

Feature	Detail
Tauri v2 runtime	Links against `libwebkit2gtk-4.1` — the one Ubuntu actually ships
OAuth / SSO	`--new-window` flag means Google sign-in works in-app instead of being blocked
System tray	Desktop integration that works
1200x780 window	Matches the original Kimi desktop dimensions

Rebuild it yourself

Prerequisites — Rust, Node, and the usual GTK/webkit dev packages:

# Rust >= 1.85
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Node.js >= 22 — use nvm, brew, whatever you prefer

# Build deps
sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev \
  libayatana-appindicator3-dev librsvg2-dev

# Pake CLI
npm install -g pake-cli

Then it's one command:

./build.sh

The .deb lands in dist/. Install it:

sudo dpkg -i dist/kimi_1.0.0_amd64.deb

Done. Kimi runs natively on Ubuntu 26.04 with no missing libraries.

The config that makes it work

Everything lives in config/pake.json. The important bits:

{
  "windows": [{
    "url": "https://kimi.moonshot.cn",
    "new_window": true,
    "width": 1200,
    "height": 780
  }],
  "user_agent": {
    "linux": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36"
  }
}

The two things that matter:

new_window: true — Without this, OAuth popups (Google sign-in, etc.) get blocked by the webview's navigation policy. This flag tells Pake/Tauri to open them in a new window instead.
user_agent.linux — Spoofing a Chrome UA because some OAuth providers reject webview user agents.

Why not just use the web app in a browser?

Fair question. A native desktop app gives you:

Alt-Tab separation — Kimi isn't buried among 40 browser tabs
System tray — Quick access, stays running in the background
Own window chrome — Feels like an app, not a tab
Smaller memory footprint — Tauri uses the system webview, not a bundled Electron instance

The repo

github.com/johnohhh1/kimi-app

Clone it, build it, install it. If you're on Ubuntu 24.04+ and want Kimi as a desktop app, this is currently the only way that works.

Uninstall

If you need to remove it:

sudo dpkg -r kimi

Kimi is a product of Moonshot AI. This project uses the open-source Pake tool (MIT license) to wrap the Kimi web interface as a native desktop application.

I Ported the Ollama Desktop App to Linux Just in Time for Ubuntu 26.04 LTS

johnohhh1 — Sat, 11 Apr 2026 22:46:54 +0000

Ubuntu 26.04 LTS drops this week. I've been running the RC for months. And I think it's going to be the release that finally pulls a meaningful chunk of people off Windows — especially AI-curious developers who are tired of the telemetry, the forced updates, and the general feeling that Microsoft is treating them like a product.

So I've been on a mission: take the cool AI tooling that still assumes Windows or macOS, and make it work natively on Linux.

This week's project: the official Ollama desktop app.

The Problem

Ollama is incredible. Local LLMs, dead simple, fast. But their desktop app — the polished GTK-style chat UI with model management, file attachments, settings, chat history — officially ships for Windows and macOS only.

Every single Go file in the app/ directory of ollama/ollama starts with:

//go:build windows || darwin

Linux users are left running ollama serve and pointing a browser at localhost:11434. It works, but it's not the experience.

The Discovery

Before writing a single line of code, I did what any good engineer does: I read the source.

The Ollama desktop app is built on webview — a lightweight C++ library that wraps the platform's native browser engine. On Windows it uses WebView2 (Edge). On macOS it uses WebKit. And on Linux?

// From webview.h, line ~400:
#if defined(WEBVIEW_GTK)
// Full GTK3 + WebKit2GTK implementation

The Linux support was already there. Fully implemented. Sitting in the header file, waiting. The Go build tags were the only thing blocking it.

The Port

Six new files. A patch. About 350 lines of Go.

1. Unlock the build tags

~40 files needed one line changed:

// before
//go:build windows || darwin

// after  
//go:build windows || darwin || linux

2. Wire up the CGo flags

app/webview/webview.go needed Linux-specific build flags to find GTK and WebKit:

#cgo linux CXXFLAGS: -DWEBVIEW_GTK -std=c++14
#cgo linux LDFLAGS: -ldl
#cgo linux pkg-config: gtk+-3.0 webkit2gtk-4.1

Note: Ubuntu 26.04 ships webkit2gtk-4.1 — not 4.0. If you're targeting older distros, check your version.

3. Platform files

The app architecture expects platform-specific implementations of a handful of interfaces. I wrote six _linux.go files:

app_linux.go — GTK window management via CGo, lockfile-based single-instance enforcement, signal cleanup:

func handleExistingInstance(startHidden bool) {
    f, err := os.OpenFile(lockPath, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o644)
    if err != nil {
        slog.Info("another ollama-app instance detected, exiting")
        os.Exit(0)
    }
    f.Close()
    go func() {
        c := make(chan os.Signal, 1)
        signal.Notify(c, syscall.SIGINT, syscall.SIGTERM, syscall.SIGHUP)
        <-c
        removeLock()
    }()
}

server_linux.go — The app normally spawns the Ollama daemon itself. On Linux, systemd handles that. So this file is just a health-checker that pings localhost:11434 every 30 seconds and logs if it's unreachable. Never spawns a process.

updater_linux.go — All no-ops. systemd and apt manage updates on Linux.

filepicker_linux.go — File/folder dialogs via zenity:

func selectDirectory(title string) (string, error) {
    out, err := exec.Command("zenity", "--file-selection", "--directory", "--title="+title).Output()
    if err != nil {
        return "", err
    }
    return strings.TrimSpace(string(out)), nil
}

dialog/dlgs_linux.go — zenity implementations of the app's dialog interface (yes/no, info, error, file pickers).

webview_linux.go — The Webview struct without the Windows menu.h CGo baggage, plus all the JS bindings: ready, close, drag, doubleClick, zoomIn, zoomOut, selectFiles, selectWorkingDirectory.

4. The one frontend bug

The React sidebar had:

{isWindows && (
  <Link href="/settings">Settings</Link>
)}

On Linux, navigator.platform returns "Linux x86_64" — so isWindows is false and Settings just... doesn't appear. One-line fix:

const isMac = navigator.platform.toLowerCase().includes("mac");

{!isMac && (
  <Link href="/settings">Settings</Link>
)}

The Result

git clone https://github.com/johnohhh1/ollama-webchat-ubuntu.git
cd ollama-webchat-ubuntu
bash build.sh
sudo cp build/ollama-app /usr/local/bin/ollama-app
ollama-app

A native GTK3 window. WebKit2GTK rendering the full React SPA. Chat history in SQLite. File attachments. Model management. Settings. Dark mode. Wayland-native — no XWayland needed.

The NVIDIA gotcha

Running an RTX 5070 (Blackwell) with the proprietary driver? You'll see a wall of EGL warnings on startup:

libEGL warning: egl: failed to create dri2 screen
libEGL warning: pci id for fd 17: 10de:2f04, driver (null)

Ignore them. There's no open-source Mesa driver for Blackwell yet — WebKit probes Mesa EGL, fails, and falls back to Cairo software rendering for the compositor. For a chat UI it's completely imperceptible. Page layout and text were always CPU-rendered anyway.

Why Ubuntu 26.04 changes things

26.04 LTS is the first Ubuntu release with X11 removed entirely — Wayland only. GNOME 50. The desktop finally feels like a first-class target, not an afterthought.

At the same time, the local AI tooling ecosystem has exploded. Ollama, LM Studio, Open WebUI, llama.cpp — these tools are genuinely good, and they mostly work on Linux. The desktop app experience is just lagging behind.

That's the gap I'm trying to close. If you're a developer making the jump from Windows to Ubuntu 26.04 this week, you shouldn't have to give up your tools.

Repo

github.com/johnohhh1/ollama-webchat-ubuntu

PRs welcome — especially if you test on Fedora, Arch, or Ubuntu 24.04. And if you're building other AI tools that are stuck behind Windows/macOS build tags, the pattern here is reusable.

The C library usually already supports Linux. The build tags are almost always the only thing in the way.

Anthropic Limited Claude Subscription Usage for Third-Party Harnesses. So We Ported NanoClaw to Codex

johnohhh1 — Thu, 09 Apr 2026 19:01:29 +0000

NanoClaw started as an app effectively built by running Claude inside its own repo. Porting it to Codex meant rewriting not just the runtime, but the markdown instruction layer Claude had been using to build and operate the system.

Most "AI app ports" are not actually ports.

They are usually one of these:

swap the SDK
change the model name
keep the old runtime assumptions
call it done

This was not that.

On April 4, Anthropic began limiting Claude subscription usage for third-party harnesses, including tools in the OpenClaw/NanoClaw category, pushing that usage toward extra paid usage instead of normal subscription limits. That policy shift did not magically make NanoClaw unusable overnight, but it did make one thing obvious:

Building a serious agent system on top of a first-party subscription runtime is not a stable foundation.

NanoClaw started life as something much stranger and much more interesting: an agent harness that was not just running on Claude-native assumptions, but was also largely shaped by Claude while working inside the repo.

The original workflow was basically:

point Claude Code at the repo
give it a stack of markdown instructions
run commands like /setup
let it scaffold, extend, and evolve the app from inside its own preferred operating model

That means the old codebase was not merely "compatible with Claude."

It was, in a very real sense, built by running Claude inside a repo that was designed to teach Claude how to keep building it.

That distinction is the whole story.

Because once we decided to make NanoClaw truly Codex-native, the work was not "replace Anthropic with OpenAI."

The work was simple to describe and hard to do:

separate the app from the agent that originally co-authored its architecture.

The Weird Part: The Markdown Was Part of the Runtime

A lot of projects have docs.

NanoClaw had something closer to an instruction substrate.

The Claude-native version depended on a pile of markdown-driven behavior:

CLAUDE.md
.claude/skills/...
setup flows like /setup
branch/workflow docs
installer docs
capability docs
hidden conventions for how the agent should extend the app

These files were not just "developer notes."

They were part of the product's behavioral layer.

They told the agent:

how to initialize the app
how to install integrations
how to shape features
how to think about memory
how to extend channels
how to apply skills

So when we started the port, one thing became obvious fast:

some of the .md files were effectively code.

Not executable code in the TypeScript sense, but runtime-significant architecture in the agent sense.

That meant the port had two layers:

Port the actual Node.js/container runtime
Audit and rewrite the instruction layer that Claude had been using to build and operate the app

If we didn't do both, we wouldn't have a Codex-native system.

We would just have Claude-shaped behavior hiding under a new logo.

What NanoClaw Actually Is

At its core, NanoClaw is a small Node.js orchestrator for running isolated assistants in containers.

The host process handles:

channels
routing
SQLite state
scheduling
group registration
IPC
container lifecycle

The container handles:

the actual agent runtime
group-local context
active skills
delegated subagents
tool access via MCP

That architecture survived the port.

What changed was the substrate it was built on.

What Was Claude-Specific

Before the port, the Claude-specific assumptions were everywhere:

Claude SDK query loop
CLAUDE.md instruction contract
.claude/ state and session layout
.claude/skills/ install model
Claude slash-command workflows like /setup
Claude-era delegation semantics
remote control built around Claude tooling

And because Claude had been used to keep extending the app from inside the repo, those assumptions were reinforced both in code and in markdown.

So the first real task was not coding.

It was indexing and classifying the repo:

which parts were host application behavior
which parts were Claude-specific runtime behavior
which parts were portable concepts wearing Claude-shaped names
which markdown files were still product-significant
which markdown files were now just historical scaffolding

That review step mattered more than any individual code patch.

Because if you misclassify those layers, you end up deleting real features or preserving the wrong abstractions.

The Port Was Not "Remove Claude, Add Codex"

A real port required four kinds of changes.

1. Replace the runtime contract

The old container runner was built around Claude-native execution.

The new one is built around Codex CLI running non-interactively in the container.

That meant:

building prompt context from host state plus group instructions
invoking Codex cleanly for fresh turns and resumed turns
streaming results back through a stable host/container protocol
preserving session continuity where possible

This sounds like a simple runner swap.

It wasn't.

Because CLI contracts differ in annoying, subtle ways.

We hit real bugs around things like:

flags that work on codex but not codex exec
flags accepted on fresh turns but rejected on codex exec resume

Those are not theoretical portability problems. They are the kinds of issues that make a working-looking system fail in production after the host queue has already done its job.

2. Rewrite the instruction layer

This was the part that most clearly separated a fake port from a real one.

The Claude-native repo had accumulated behavior through markdown:

skills
setup flow
integration guidance
memory conventions
extension/install patterns

We had to go through those files and make hard calls:

convert
prune
delete
replace

That meant moving from Claude-specific conventions to Codex-native ones:

CLAUDE.md became AGENTS.md
repo/group skills became SKILL.md-based
old .claude/skills/ assumptions were removed
the setup story was rewritten around the current runtime rather than old slash-command flows

This was not glamorous work, but it was absolutely core to the port.

If the old markdown continues to teach the wrong mental model to the next agent working in the repo, the architecture drifts backwards immediately.

3. Keep the real product features

One of the easiest mistakes in a port is to treat every old feature as vendor-specific and quietly delete it.

That would have been wrong here.

Some things were truly Claude-specific and should die:

Claude SDK integration
Claude remote control
old Claude-only skill marketplace conventions

But other things were just app features that happened to be implemented in a Claude-native system:

Telegram
WhatsApp
web UI channel
subagent delegation
host skills

Those needed to be ported, not removed.

That was an important correction during this work.

The right question was not:

"Does this mention Claude?"

The right question was:

"Is this a real app capability, and does Codex have a legitimate equivalent or integration path?"

4. Make the host own the architecture

This is the core lesson of the whole effort.

The clean architecture is:

NanoClaw owns orchestration
NanoClaw owns state
NanoClaw owns channels
NanoClaw owns skills
NanoClaw owns setup
Codex is the agent backend

If the host owns those things, the backend is replaceable.

If the backend owns those things, the host is just branding.

The Bugs That Proved the Point

The best part of a port like this is that the bugs are revealing.

They tell you where your assumptions still belong to the old system.

Bug 1: The bot looked alive but was brain-dead

Telegram connected.
Messages were being stored.
But nothing was being processed.

Why?

Because WhatsApp was loading even when it was not configured, entering a reconnect loop, and blocking the async startup path before the message loop came online.

That produced a nasty half-working state:

inbound messages reached the DB
logs looked active
startMessageLoop() never really came alive
"NanoClaw running" never appeared

The fix was to stop treating channel startup as monolithic:

load channels conditionally from real config/auth state
allow channel connect failure without killing startup
skip missing channels cleanly instead of blocking the process

That sounds basic, but it was exactly the kind of bug you get when a system has grown around agent-era assumptions rather than explicit host orchestration.

Bug 2: The auth existed, but Codex still 401'd

This was my favorite bug in the whole port because it was pure systems work.

The host was logged into Codex.
The container was supposed to inherit auth.
But every in-container turn failed with:

401 Unauthorized: Missing bearer or basic authentication in header

The credentials were not absent.
They were misplaced.

The chain was:

auth was copied into a nested .codex/.codex/auth.json
that directory was mounted into the container
Codex expected auth relative to $HOME/.codex/auth.json
the file existed on disk, just not where the CLI actually looked

This is the kind of bug that disappears if you talk only in architecture diagrams.

It only becomes obvious when you trace:

host path
mounted path
container $HOME
actual CLI lookup convention

The fix:

flatten the per-group Codex state layout
mount it directly to /home/node/.codex
migrate old nested state forward

After that, the 401 vanished and the live message path finally completed.

Bug 3: Resume was not the same as fresh execution

Another seam bug.

We got fresh turns working, then resume failed because codex exec resume did not accept the same options as the fresh path.

That is a perfect example of why "we already integrated the CLI" is not enough.

You have to test:

fresh turn path
resumed turn path
session restoration
output handling after resume

Those are separate runtime contracts, even when they share most of the binary name.

What the System Looks Like Now

The current branch is not "Claude code with Codex paint."

It is a different runtime model.

Today it has:

Codex-native container runner
AGENTS.md for project/group instructions
SKILL.md-based host skills
per-group Codex state
Telegram, WhatsApp, and Web UI channels
Codex-backed delegation via MCP
host-owned setup and orchestration

And critically, it is no longer relying on the repo being interpreted through Claude-native markdown conventions to keep itself evolving correctly.

That was the actual finish line.

Not "build passes."

Not "logs look nice."

But:

the app can now be operated, extended, and reasoned about as a Codex-native system.

The Real Lesson

The strongest takeaway from this work is that agent-built systems can end up with architecture embedded in places most teams don't normally treat as architecture.

In this case, that meant:

markdown instruction files
slash-command setup flows
skill directories
implied agent workflows
hidden filesystem conventions

If you want to port a system like that, you have to audit all of it.

Not just the code.

Not just the API client.

All of it.

Because once an agent has spent enough time building inside a repo, the repo starts to encode assumptions about that agent's worldview.

That is fascinating when it works. It is dangerous when you need to switch runtimes.

If You're Thinking About Doing This Yourself

My advice is:

inventory the instruction layer before you touch the runtime
treat markdown conventions as potentially executable architecture
separate host ownership from backend ownership early
verify real CLI behavior instead of trusting docs from memory
test startup, auth, fresh turns, resumed turns, and recovery independently
do not call it a port if you quietly deleted capabilities that had real equivalents

The hard part is not replacing the model.

The hard part is identifying all the places where the old model had already shaped the app.

And once you do that, the job becomes much clearer:

you are not porting an SDK. You are reclaiming the architecture.

How I repackaged the official Windows Codex MSIX into a working Linux .deb

johnohhh1 — Thu, 09 Apr 2026 18:13:34 +0000

I wanted a real Linux desktop app for Codex.

At first, this looked like it should be straightforward: take the official Windows package, unpack it, swap in Linux Electron, rebuild whatever was platform-specific, and turn it into a .deb.

That is not what happened.

What actually worked was more pragmatic: preserve the official Codex payload, branding, and resources from the Windows MSIX, but replace the runtime shell with a small Linux Electron wrapper that opens Codex in its own desktop window.

This post is the write-up I wish I had before I started.

The Goal

The target was simple:

install Codex on Ubuntu as a .deb
get a desktop launcher and icon
make it feel like a native app
avoid relying on a browser tab
keep the build repeatable

I already had something similar working for ChatGPT, so I assumed Codex would follow the same path.

That assumption was wrong.

What I started with

The source payload was the official Windows MSIX:

OpenAI.Codex_26.313.5234.0_x64__2p2nqsd0c76g0.Msix

The repo I ended up with is here:

git@github.com:johnohhh1/codex-ubuntu.git

The main build script is:

./build-codex-native-deb.sh

The obvious approach

The first plan was the normal "repackage the Electron app" playbook:

Extract the MSIX.
Grab the bundled app.asar.
Swap the Windows Electron runtime for Linux Electron.
Rebuild or replace native modules.
Repackage everything into a .deb.

In theory, that should have produced a Linux .deb built directly from the original app bundle.

In practice, it failed in multiple different ways.

Problem 1: the Windows bundle was not actually Linux-ready

The Codex payload included resources and binaries that looked promising, but the packaged app still carried Windows assumptions.

The biggest issue was native modules.

At one point I confirmed the app was dying because a native dependency was still Windows-built:

invalid ELF header

That is the classic sign that Linux is trying to load a binary module compiled for the wrong platform.

So the next move was to rebuild native modules for Linux and wire them back into the extracted app.

That still did not get me to a usable app window.

Problem 2: getting the app to "launch" was not the same as getting it to work

I got as far as installing the package cleanly and starting Electron on Linux.

That was progress, but not enough.

The app process would launch and then exit without showing a window, or fail during startup after getting past the first set of issues.

This is one of the most annoying parts of Electron packaging work: "the binary started" sounds good, but it does not mean the app is actually viable.

Problem 3: Electron GPU startup was fatal on Linux

Once I simplified the runtime enough to observe the real failure clearly, the next blocker showed up:

FATAL: GPU process isn't usable. Goodbye.

That changed the direction of the fix immediately.

Instead of trying to preserve every part of the original desktop behavior, I needed a Linux-friendly launcher path that was stable in the actual Ubuntu session I was using.

The fix was to disable GPU at both levels:

in the Electron app itself with command-line switches
in the launcher wrapper used by the packaged .deb

The final launcher executes Electron like this:

exec /opt/codex-desktop-native/electron/Codex \
  --no-sandbox \
  --disable-setuid-sandbox \
  --disable-gpu \
  --disable-gpu-compositing "$@"

That was not elegant, but it was effective.

The pivot: stop trying to preserve the original runtime shell

This was the real turning point.

Instead of continuing to patch the original Windows desktop runtime deeper and deeper, I switched to a simpler architecture:

use Linux Electron as the runtime
keep the official Codex assets from the MSIX
build a tiny Linux wrapper app
load https://chatgpt.com/codex inside a dedicated desktop window

That approach still let me build from the official Windows MSIX, but it stopped me from getting trapped in the least portable parts of the original runtime.

What the final wrapper does

The generated wrapper app is very small.

It:

creates a BrowserWindow
hides the menu bar
uses a Codex title and icon
opens external popups in the default browser
allows normal http and https navigation
forces the window to show even if page paint is slow
points at https://chatgpt.com/codex by default

The wrapper also supports overriding the URL with an environment variable:

CODEX_WEB_URL=https://chatgpt.com/codex codex-desktop-native

That is useful if the endpoint ever changes or if you want a staging/test flow.

Packaging details that mattered

There were a few packaging details that turned out to be more important than I expected.

1. The app had to present itself as Codex

I renamed the Linux Electron binary from electron to Codex so the app identity looked correct on Linux.

That helped with launcher behavior and window class handling.

2. Desktop entry details mattered

The .desktop file sets:

Name=Codex
Exec=codex-desktop-native
Icon=codex-desktop-native
StartupWMClass=Codex
X-GNOME-WMClass=Codex

Without that, you can end up with weird launcher grouping or desktop integration issues.

3. Old install leftovers had to be cleaned up explicitly

Earlier experiments left behind app.asar.unpacked content from previous versions.

Even after the packaging approach changed, those leftovers could survive upgrades and create confusing behavior.

So I added a preinst cleanup step to the package:

rm -rf "/opt/codex-desktop-native/electron/resources/app.asar.unpacked"

That made upgrades deterministic again.

Making the build self-contained

At first I was borrowing tools from another workspace, which worked but was brittle.

I cleaned that up by making the project self-contained with local dev dependencies:

{
  "devDependencies": {
    "asar": "^3.2.0",
    "electron": "^40.0.0"
  }
}

That way the repo can be built with:

npm install
./rebuild-install.sh

instead of depending on some other directory on disk having the right binaries in it.

The build flow now

The working build pipeline looks like this:

Validate the MSIX input.
Extract the package and detect its version from AppxManifest.xml.
Copy the official assets into a staging directory.
Copy in Linux Electron.
Replace the original runtime shell with a generated Linux wrapper app.asar.
Build a .deb with the desktop entry, icon, launcher script, and package hooks.

The helper script for rebuild and reinstall is:

./rebuild-install.sh

The result

The final output is a package like this:

dist/codex-desktop-native_26.313.5234.0_amd64.deb

And the user-facing launch command is simply:

codex-desktop-native

Most importantly: it actually opens, stays up, and works as a desktop app on Ubuntu.

What I learned

The biggest lesson from this project is that "porting" is sometimes the wrong framing.

I went in thinking I needed to preserve the original Windows desktop runtime as faithfully as possible.

What I really needed was:

a reliable Linux package
a clean desktop launcher
Codex in its own app window
a build process I could rerun later

Once I optimized for that instead of purity, the solution got much simpler.

That tradeoff is worth stating directly: the final app is absolutely built from the official Windows MSIX, but it is not a perfect binary carryover of the original runtime. It is a Linux-native wrapper around the official Codex experience, using the original payload where it helps and replacing the parts that did not survive the platform jump well.

That was the right call.

If you want to try it

The repo is here:

git@github.com:johnohhh1/codex-ubuntu.git

Quick start:

git clone git@github.com:johnohhh1/codex-ubuntu.git
cd codex-ubuntu
npm install
./rebuild-install.sh
codex-desktop-native

Closing thought

A lot of cross-platform packaging work looks like a debugging problem, but the real work is architectural judgment.

You have to decide when to keep forcing the original design, and when to admit that a thinner, more native solution is the thing that will actually ship.

This project only started working once I made that call.

a build process I could rerun later

Once I optimized for that instead of purity, the solution got much simpler.

That was the right call.

If you want to try it

The repo is here:

git@github.com:johnohhh1/codex-ubuntu.git

Quick start:

git clone git@github.com:johnohhh1/codex-ubuntu.git
cd codex-ubuntu
npm install
./rebuild-install.sh
codex-desktop-native

Closing thought

A lot of cross-platform packaging work looks like a debugging problem, but the real work is architectural judgment.

You have to decide when to keep forcing the original design, and when to admit that a thinner, more native solution is the thing that will actually ship.

This project only started working once I made that call.

Run the Real ChatGPT Desktop App on Ubuntu Linux (Not a Wrapper)

johnohhh1 — Tue, 07 Apr 2026 13:51:17 +0000

TL;DR: OpenAI ships a Windows MSIX binary. You can unpack it, patch three platform assumptions, and run the actual official app natively on Ubuntu — same binary Windows users get. No Electron wrapper, no web view in a box.

The Problem With Every Other Guide

Search "ChatGPT desktop Ubuntu" and you'll find two things:

Articles pointing you at lencx/ChatGPT — a third-party Electron wrapper that loads chatgpt.com in a window. It's not the real app.
Articles pointing you at other wrappers doing the same thing.

These work, but you're getting a community-built shell around a website — not the app itself. The real ChatGPT Desktop (the one in the Windows Store) has features, update hooks, and auth flows that wrapper apps can't replicate cleanly.

This guide unpacks the official binary and runs it on Ubuntu 26.04. Tested on kernel 7.0.0, RTX 5070, NVIDIA 580/CUDA 13.0, both X11 and Wayland via XWayland.

What the Script Actually Does

Extracts the x64 MSIX from the official .msixbundle
Pulls out the official app.asar (the real app logic)
Patches three platform assumptions so it boots on Linux:
- Routes the platform chooser through the macOS-style implementation (Linux is close enough)
- Disables macOS-only setVibrancy() calls
- Skips the macOS ioreg device ID path
Stages Linux Electron around the official app resources
Packages everything as a proper .deb — chatgpt-desktop-native

You end up with a system package you can install, update, and uninstall like anything else.

Prerequisites

System packages

sudo apt-get install -y dpkg-dev nodejs python3 file

Local Electron tooling

mkdir ~/chatgpt-windows-deb && cd ~/chatgpt-windows-deb
npm install electron @electron/asar --no-save

Get the Official MSIX Bundle

You need the official Windows package from OpenAI. Download OpenAI.ChatGPT-Desktop_<version>.Msixbundle from the Microsoft Store or OpenAI's distribution endpoint and drop it in your working directory.

The repo includes the version current at time of writing as an example payload.

Build

cd ~/chatgpt-windows-deb
git clone https://github.com/johnohhh1/chatgpt_desktop_ubuntu .
npm install electron @electron/asar --no-save
./build-chatgpt-native-deb.sh --exe ./OpenAI.ChatGPT-Desktop_2026.212.2039.0.Msixbundle

Output lands in dist/:

dist/chatgpt-desktop-native_2026.212.2039.0_amd64.deb

Install

sudo apt-get install ./dist/chatgpt-desktop-native_2026.212.2039.0_amd64.deb

Rebuilding without a version bump? Force refresh:

sudo apt-get install --reinstall ./dist/chatgpt-desktop-native_2026.212.2039.0_amd64.deb

Register Auth Callback Handlers

The package installs a helper that registers your desktop session as the handler for the chatgpt: and chatgpt-alt: URL schemes (used for the login flow):

chatgpt-desktop-native-register

Verify it took:

xdg-mime query default x-scheme-handler/chatgpt
xdg-mime query default x-scheme-handler/chatgpt-alt

Both should return chatgpt-desktop-native.desktop.

Launch

chatgpt-desktop-native

The desktop entry sets the WM class to electron so GNOME binds the running window to the ChatGPT icon instead of the generic gear icon.

Known Quirks

The terminal will print Electron/NVIDIA/VA-API noise. This is normal — ignore it.
The success signal is functional login and working chat, not a clean terminal.
If GNOME still shows the generic icon after first launch: close the app fully and relaunch once. Stubborn shell? Log out and back in.
If OpenAI updates the Windows app significantly, the patch targets in build-chatgpt-native-deb.sh may need updating. PR welcome.

Reproducing on Another Machine

Clone the repo to the target machine
Drop a real ChatGPT .msix, .msixbundle, .appx, or .appxbundle in the directory
npm install electron @electron/asar --no-save
./build-chatgpt-native-deb.sh --exe <your-payload>
Install the generated .deb
Run chatgpt-desktop-native-register
Launch chatgpt-desktop-native

Repo

github.com/johnohhh1/chatgpt_desktop_ubuntu

Issues and PRs open. If a new MSIX version breaks the patches, open an issue with the version string and I'll update the patch targets.

Tested on Ubuntu 26.04 "Noble" with kernel 7.0.0-10, RTX 5070, NVIDIA driver 580, CUDA 13.0.

DEV Community: johnohhh1

I spent 6 hours debugging a VM that didn't need to exist

The setup

The rabbit hole

The fix was 3 lines of thinking

The pattern

What I should have done

The takeaway

I Ported ComfyUI Desktop to Ubuntu 26.04

Another Desktop App ported to Linux That was not available. I will Keep going until release day or I run out of apps to port. Let me Know what one you would like to see next!

The Goal

The Starting Point

The Real Problems

1. Linux was gated out of asset/bootstrap flow

2. Packaged builds were missing desktop-ui

3. AppImage hit Electron sandbox issues

4. Linux runtime assumptions were wrong

5. Existing Comfy installs were ignored

What I Changed

Build and packaging fixes

Runtime fixes

Existing-install behavior

Why .deb Won

What the App Does Now

Commands I Actually Used

The Nice Surprise

The Useful Lesson

Upstream and Source

My Repo

Kimi Desktop on Ubuntu 26.04: Fixing the Broken .deb with Tauri v2

The problem in one sentence

The fix: rebuild with Tauri v2

What you get

Rebuild it yourself

The config that makes it work

Why not just use the web app in a browser?

The repo

Uninstall

I Ported the Ollama Desktop App to Linux Just in Time for Ubuntu 26.04 LTS

The Problem

The Discovery

The Port

1. Unlock the build tags

2. Wire up the CGo flags

3. Platform files

4. The one frontend bug

The Result

The NVIDIA gotcha

Why Ubuntu 26.04 changes things

Repo

Anthropic Limited Claude Subscription Usage for Third-Party Harnesses. So We Ported NanoClaw to Codex

The Weird Part: The Markdown Was Part of the Runtime

What NanoClaw Actually Is

What Was Claude-Specific

The Port Was Not "Remove Claude, Add Codex"

1. Replace the runtime contract

2. Rewrite the instruction layer

3. Keep the real product features

4. Make the host own the architecture

The Bugs That Proved the Point

Bug 1: The bot looked alive but was brain-dead

Bug 2: The auth existed, but Codex still 401'd

Bug 3: Resume was not the same as fresh execution

What the System Looks Like Now

The Real Lesson

If You're Thinking About Doing This Yourself

How I repackaged the official Windows Codex MSIX into a working Linux .deb

The Goal

What I started with

The obvious approach

Problem 1: the Windows bundle was not actually Linux-ready

Problem 2: getting the app to "launch" was not the same as getting it to work

Problem 3: Electron GPU startup was fatal on Linux

The pivot: stop trying to preserve the original runtime shell

What the final wrapper does

Packaging details that mattered

1. The app had to present itself as Codex

2. Desktop entry details mattered

3. Old install leftovers had to be cleaned up explicitly

Making the build self-contained

2. Packaged builds were missing `desktop-ui`

Why `.deb` Won