GitHub - ramayac/GoPOSIX: A Go-native, single-binary POSIX userland with 100+ tools. Runs as a persistent JSON-RPC daemon or multicall CLI, backed by >98% Busybox test compatibility.

A Go-native, single-binary POSIX userland with 115 tools. Runs as a persistent JSON-RPC daemon or multicall CLI, a typed Go SDK and ~98.2% BusyBox test compatibility (878 of 919 tests pass).

Why?

Well, I wanted to do an experiment on Harsness Engineering, and improve my "agentic development" skills, prompts, instructions and all that. I did LFS in my early 20's and I had this weird itch of "do your own thing" but left it alone for my own sanity. Still the POSIX concepts remained in the back of my head. Last year (2025) I started to learn Go-lang, and then LLMs got really good in December 2025. Good enough that I've been using it at work non stop since then.

During that time I got this notion that AI waste time formating output, so I started doing --json output in a lot of my work scripts and tools (to save some time for my robot friends). Eventually all of these random ideas boiled to the conclusion that I should make a complete implementation of POSIX utilities in Go, with a JSON output and a Go SDK, and then benchmark it against BusyBox. It's the "natural conclusion" ... right?

Also deepseek-v4-pro had an very agressive 75% discount!, and I wanted to try pi.dev instead of Antigravity/ClaudeCode (I ended up using agy for some auditing).

All things kind of aligned in the last month so here we are now.

I'm not the first to start something like this, there is cugo and go-posix, but sadly they seem to be abandoned, and no wonder! A project like this is a huge undertaking, its probably a year of solid work for 1 human, that being said, took about 3 weeks to do with AI, with the proper "harness" and "agentic development" approach, that's really something.

Anyway the project got into a point that I'm happy with the results, that's enough for me ☑️.

Honest and Obvious Recognitions

I want to be very clear about this:

The only reason this works is that there's a brutally thorough, existing corpus of tests to validate against. The AI iterated until it passed. Without BusyBox's tests, this project is just random hallucinated code. The test suite is the real hero.

• So check and support BusyBox project and take a look at its amazing test suite, it's a masterpiece of thoroughness and coverage, and it made this project possible.
• Also Mvdan Shell, it really saved my butt. Absolutely brilliant.
• And goawk, which I used for the awk implementation, another big save!
• blakesmith/ar for reading and writing ar archives.
• cavaliergopher/cpio for cpio archive support.
• hotei/dcompress for decompression helpers.
• sergeymakinen/go-crypt and tredoe/crypt for unix password crypt implementation.
• ulikunitz/xz for xz/lzma compression and decompression.
• golang.org/x libraries (sys, term, crypto) for system call access, terminal control, and cryptographic functions.

Finally: let's not kid ourselves, this project is 90% wiring the AI to do the heavy lifting, 10% is steering it in the right direction, the fact that I was able to "solo dev" this with an LLM, reproducing close to 99% of BusyBox's behavior in a completely different language shows that POSIX utilities are, at their core, text transformers with very well-defined contracts (do one thing and do it well).

Does it work?

Yes! yes it does! see how GoPOSIX replaces BusyBox in Alpine here: docker/Dockerfile (target: alpine-mvp).

Quickstart

See wiki/sdk.md for the full Go SDK guide and wiki/usage.md for CLI usage and Docker recipes.

CLI (secondary)

docker pull ghcr.io/ramayac/goposix:cli
docker run --rm ghcr.io/ramayac/goposix:cli ls --json /

Build & Test

make all          # vet + test + build
make test         # unit tests
make testsuite    # BusyBox integration tests (gates every commit)
make ci           # full pipeline (test + testsuite + coverage + docker)

Environment Variables

Daemon & CLI Configuration

Standard POSIX Environment Variables

Daemon Stdin

The JSON-RPC daemon accepts a stdin field in request params, enabling stdin-consuming utilities (grep, sed, sort, wc, tr, head, tail, cut, tee, uniq, and 30+ others) to receive input directly through the Go SDK without temp files.

// Pass stdin through the daemon
c.Grep(ctx, []string{"foo"}, client.WithStdin("line1\nline2\nfoo\n"))
c.Wc(ctx, []string{"-l"}, client.WithStdin("line1\nline2\nline3\n"))

Performance

Numbers above are approximate. For reproducible benchmarks with scale factors and full methodology, see wiki/performance.md.

Documentation

• Go SDK Guide — typed client for all utilities
• RPC API Reference
• JSON-RPC Protocol — raw socket protocol for non-Go clients
• Architecture
• Security Model
• JSON Schema — --json output schemas for every utility
• Test Coverage & Compliance Matrix — 878/919 (98.2%) BusyBox pass rate
• POSIX FAQ
• Performance Quick Reference

Quick Project Principles

• Multicall Binary: Single binary dispatched via symlink or subcommand (goposix ls).
• Daemon-First: The default image starts the persistent JSON-RPC daemon. Use the Go SDK for programmatic access. CLI is available as a secondary interface (goposix:cli).
• No CGO: Static compilation for FROM scratch containers (CGO_ENABLED=0).
• Little Dependencies: Only 3 external Go modules: mvdan.cc/sh/v3 (shell interpreter), golang.org/x/sys (cross-platform syscalls), golang.org/x/term (terminal detection). No external libraries for flag parsing, output, or utility logic.
• --json Only: Structured output via --json long flag only — no short-form (-j) collision with POSIX flags.
• POSIX Flag Parsing: Custom parser in pkg/common/flags.go with escape hatches for free-form utilities (echo, printf, expr).