hatchkit

Interactive CLI for scaffolding full-stack projects with composable ML services — from npx hatchkit to a deployed app on your own infrastructure in minutes.

---

What is hatchkit?

Hatchkit turns the messy 2-week ritual of "start a new product" into a single guided command. It:

• Scaffolds a production-ready full-stack TypeScript app from a batteries-included starter (websockets, Stripe, analytics, S3, native desktop (Electron) / mobile (Capacitor), auth — pick what you need).
• Provisions observability, email, and analytics clients (GlitchTip, Plausible, Listmonk + SES) paired per environment.
• Deploys DNS, a VPS, and a Coolify app via Terraform — or pushes to an existing server you already own.
• Ships ML by deploying pre-built GPU services (subtitles, image recognition, background removal, 3D extraction) to Modal, RunPod, Hugging Face, or Replicate.
• Encrypts secrets with dotenvx and keeps private keys in the OS keychain — never in git.

No vendor lock-in. Everything it spins up — your server, your Coolify, your GitHub repo, your DNS — stays yours.

---

Quickstart

# One-time: wire up credentials (GitHub, Coolify, Hetzner, DNS, …)
npx hatchkit setup

# See what's configured and what's next
npx hatchkit status

# Scaffold + deploy a new project
npx hatchkit create

That's it. You'll be walked through name → domain → features → ML → deploy target, then hatchkit will scaffold, commit, create the GitHub repo, provision DNS + server, and push the app to Coolify.

Every one of those questions also has a flag. Pass the answers you already know and only the rest get prompted, or add --yes to skip prompting entirely:

hatchkit create --yes --name blog --domain blog.example.com \
  --surfaces fullstack --deployment-mode coolify --features analytics --public

Run hatchkit create --help for the full flag list, or see the commands reference.

New to the CLI? Run hatchkit explain for a one-page mental model covering every concept, command, and the canonical workflow.

---

Commands at a glance

Full reference: Commands, or hatchkit help <command>.

---

What gets set up

           ┌──────────────────────────────────────────────┐
           │              hatchkit create                  │
           └──────────────────────────────────────────────┘
                                │
        ┌───────────────────────┼────────────────────────┐
        ▼                       ▼                        ▼
 ┌─────────────┐         ┌─────────────┐          ┌─────────────┐
 │  Scaffold   │         │   Infra     │          │     ML      │
 │             │         │             │          │             │
 │  starter →  │         │ Terraform → │          │  Modal /    │
 │  your repo  │         │ DNS + VPS   │          │  RunPod /   │
 │  + GitHub   │         │ + Coolify   │          │  HF / …     │
 └─────────────┘         └─────────────┘          └─────────────┘
        │                       │                        │
        └───────────────────────┼────────────────────────┘
                                ▼
                     https://your-domain.example

See Architecture for the deeper tour.

---

For agents

Agents (Claude Code, Cursor, Claude Desktop) can drive hatchkit without scraping CLI output:

• hatchkit status --json → StatusSnapshot (providers, nextStep, suggested commands).
• hatchkit doctor --json → per-provider health with a hint[] array on failing checks (credential rotation URL, required scopes, the exact hatchkit config add <x> to re-run).
• hatchkit explain --json → full mental model (concepts, commands, workflows, state locations).
• hatchkit keys show <project> --json → { project, found, key }.

SKILL.md at the repo root (plus .agents/skills/hatchkit/SKILL.md and .claude/skills/hatchkit/SKILL.md) tells agents when and how to reach for hatchkit.

The optional @hatchkit/mcp package exposes local CLI status and doctor tools. The mcp project feature generates a separate server for one app's public API. See the MCP guide and operator server README.

---

Shell completion

hatchkit completion zsh  > ~/.zsh/completions/_hatchkit
hatchkit completion bash > /usr/local/etc/bash_completion.d/hatchkit
hatchkit completion fish > ~/.config/fish/completions/hatchkit.fish

---

State — where things live

HATCHKIT_CONF_DIR overrides the config directory.

---

Documentation

Full docs live under docs/ and are published at https://hatchkit.trebeljahr.com/.

• Getting Started — install, onboard, create your first project
• Commands reference — every command + every flag
• Providers — GitHub, Coolify, Hetzner, DNS, S3, GPU platforms
• ML services — deploy GPU-backed models the CLI understands
• GitHub Pages — hatchkit gh-pages for static sites, SPAs, Jekyll docs, and Docusaurus docs
• Cloudflare Workers — hatchkit cloudflare for static sites on Cloudflare
• Architecture — how scaffold / infra / deploy fit together
• Deploying the docs site — the deployment flow used by this repo

Source for those pages lives in docs/content/docs/.

---

Community and support

• Contributing — local setup, validation, and PR expectations
• Security — how to report vulnerabilities or leaked secret issues privately
• Support — where to ask questions and what diagnostics help
• Code of Conduct — project participation expectations
• Changelog — user-visible release notes

---

Repo layout

hatchkit/
├─ cli/              # the npm package (published as `hatchkit`)
├─ mcp/              # @hatchkit/mcp — MCP server for agents
├─ starter/          # full-stack starter template (subtree-merged)
├─ infra/            # Terraform + Coolify automation (subtree-merged)
├─ services/ml/      # pre-built ML service templates
│  ├─ image-recognition/
│  ├─ subtitles/
│  ├─ 3d-extraction/
│  └─ background-removal/
├─ docs/             # Next.js/Fumadocs docs site — deployed to GitHub Pages
└─ .github/workflows/
   ├─ ci.yml         # typecheck + lint + scaffold matrix
   ├─ gitleaks.yml   # secret scanning
   └─ deploy.yml     # container build + deploy

---

Development

# Install deps (monorepo)
pnpm install

# Run the CLI against the local source (tsx)
pnpm --filter hatchkit dev

# Typecheck + lint + scaffold test matrix
pnpm --filter hatchkit check

# Install locally as a global command
pnpm --filter hatchkit install-local

Clone the repo and you're set — starter/ and infra/ are in-tree (previously git submodules; merged via git subtree).

git clone https://github.com/trebeljahr/hatchkit.git

---

Related tools

Hatchkit handles scaffolding, providers, infrastructure, and deployment. These sibling tools cover asset and naming work that often happens before or beside a Hatchkit project.

• conv3d — converts FBX, OBJ, and glTF assets to GLB and can emit typed React Three Fiber components for 3D, game, or asset-heavy starters.
• sprite-tools — builds game-ready 2D sprite assets with collision polygons, pivots, animation tags, palettes, atlases, and exports.
• name-checker — checks candidate names across trademarks, domains, socials, app stores, package registries, and code hosts before launch setup.
• gamedev-asset-library — catalogs free, permissively licensed game assets for Hatchkit games, prototypes, R3F scenes, and ML-backed asset workflows.

---

License

MIT — see LICENSE.