GoX | Pomai Ecosystem

Why GoX?

When a Go project grows beyond go run main.go, things get messy. You end up with complex go.work setups, chaotic Makefiles, and custom bash scripts to manage multiple processes. GoX solves this.

Instant Workspace

Architecture

Scaffolds a scalable Go workspace architecture in seconds with standard directories.

⚡ Multi-Process Dev

Workflow

Run your API, Worker, and CLI simultaneously with beautifully color-coded logs.

Smart Scaffolding

Automation

Add new microservices or shared libraries automatically linked to your go.work.

🩺 Built-in Doctor

Diagnostics

Automatically detects missing dependencies, broken module links, and port conflicts!

One-Click Release

CI/CD

Cross-compiles lean, production-ready binaries for Windows, Mac, and Linux with SHA-256 checksums.

Quick Start Journey

Initialize a new Workspace

Create a brand new system with a standardized, scalable architecture. This creates the gox.yaml and initializes go mod/work.

gox init my-system
cd my-system

Scaffold Microservices

Add a new backend API, a background worker, and a shared library. GoX handles the boilerplate and linking automatically.

gox app add api
gox app add worker
gox lib add database

Run Everything in Dev Mode

Start all your services at once. No more opening 5 different terminal tabs! Enjoy graceful shutdowns and unified logging.

gox dev

Installation

# Clone the repository
git clone https://github.com/your-username/gox.git

# Build the tool
cd gox
go build -o gox ./cmd/gox

# Move it to your PATH (Linux/Mac)
sudo mv gox /usr/local/bin/

# On Windows, move gox.exe to your System PATH

The gox.yaml Engine

Your entire ecosystem is orchestrated by a single config file at the root of your project:

name: my-system
apps:
  api:
    path: apps/api
    main: ./cmd/api
    port: 8080
  worker:
    path: apps/worker
    main: ./cmd/worker
libs:
  database:
    path: libs/database
tasks:
  dev:
    - run: api
    - run: worker
release:
  targets:
    - windows/amd64
    - linux/amd64
    - darwin/arm64

Commands & Diagnostics

Command Reference

Command	Description
gox init [name]	Initialize a new gox workspace.
gox app add <name>	Generate a new app and link it.
gox lib add <name>	Generate a new library and link it.
gox dev	Start all apps defined in tasks.dev.
gox build [app]	Compile all/specific apps to bin/.
gox test [mod]	Run tests recursively across apps.
gox doctor	Run env and conflict diagnostics.
gox release [v]	Cross-compile optimized binaries.

The Doctor is IN

Tired of weird errors because someone forgot to add a folder or two apps are fighting for port 8080? Just ask the doctor.

$ gox doctor

--- Gox Doctor ---

Go installed: go version go1.22.0

App 'api' directory exists

Port conflict: App 'worker' and 'api' both use port 8080

Found 1 issue(s) that need your attention.

Philosophy

go command = Engine | gox = Steering Wheel

GoX is not a package manager or a Go replacement. The Go official toolchain is incredibly powerful. GoX simply acts as the missing workflow operating layer, built for Gophers who love shipping fast.