{"id":50319138,"url":"https://github.com/solcreek/creekd","last_synced_at":"2026-05-29T02:06:23.920Z","repository":{"id":358767064,"uuid":"1242991613","full_name":"solcreek/creekd","owner":"solcreek","description":"Multi-tenant process supervisor and HTTP dispatcher. Cgroup v2 + Linux namespace isolation. Single Go binary.","archived":false,"fork":false,"pushed_at":"2026-05-27T13:49:56.000Z","size":1164,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T15:09:04.509Z","etag":null,"topics":["bun","cgroups","creek","deno","golang","linux-namespaces","multi-tenant","nodejs","paas","process-supervisor","sandbox","self-hosted"],"latest_commit_sha":null,"homepage":"https://github.com/solcreek/creekd","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/solcreek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-19T00:33:43.000Z","updated_at":"2026-05-27T13:50:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/solcreek/creekd","commit_stats":null,"previous_names":["solcreek/creekd"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/solcreek/creekd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solcreek%2Fcreekd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solcreek%2Fcreekd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solcreek%2Fcreekd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solcreek%2Fcreekd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/solcreek","download_url":"https://codeload.github.com/solcreek/creekd/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solcreek%2Fcreekd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33633468,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bun","cgroups","creek","deno","golang","linux-namespaces","multi-tenant","nodejs","paas","process-supervisor","sandbox","self-hosted"],"created_at":"2026-05-29T02:06:22.659Z","updated_at":"2026-05-29T02:06:23.914Z","avatar_url":"https://github.com/solcreek.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# creekd\n\n[![ci](https://github.com/solcreek/creekd/actions/workflows/ci.yml/badge.svg)](https://github.com/solcreek/creekd/actions/workflows/ci.yml)\n[![Go Reference](https://pkg.go.dev/badge/github.com/solcreek/creekd.svg)](https://pkg.go.dev/github.com/solcreek/creekd)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n\n\u003e Multi-tenant process supervisor and HTTP dispatcher. Cgroup v2 + Linux namespace isolation. Single Go binary.\n\n`creekd` is the host-side daemon that runs a fleet of independent application processes on one machine and routes HTTP traffic to them. Each app is its own child process, confined by cgroup v2 limits and (optionally) Linux namespaces. The supervisor handles spawn, restart, health, log capture, and zero-downtime blue-green deploys.\n\nIt is the runtime substrate of the [Creek](https://github.com/solcreek/creek) platform, but it has no Creek-specific dependencies — `creekd` will host any process that listens on a TCP port.\n\n## Status\n\n**Phase 1, pre-release.** API and CLI surfaces are still in flux. Not production-ready. See [`docs/ROADMAP.md`](docs/ROADMAP.md) for what's planned and [`CHANGELOG.md`](CHANGELOG.md) for what's shipped.\n\n## Why it exists\n\nMost \"run my process and route traffic to it\" systems force a choice: heavyweight (Kubernetes, Nomad, full container runtimes) or single-tenant (systemd, supervisord, pm2). `creekd` is the middle: multi-tenant on one host, no container daemon, no scheduler, no overlay network — just a Go binary that owns child processes and the listening socket.\n\nTrade: you give up multi-host orchestration. You get a 10 MB binary that runs hundreds of isolated apps on a $30 VPS.\n\n## When creekd makes sense\n\nYou already build and ship binaries (Bun / Node / Deno or any process that listens on a port), and:\n\n- you want multiple of them on one box with real isolation between them\n- you want pm2-level operational simplicity but with cgroup v2 + namespace teeth\n- you'd rather own the supervisor than rent it\n- you're fine running one machine — multi-host is solved one layer up (a load balancer in front of N creekd hosts)\n\nSee [`examples/`](examples/README.md) for the runnable recipes — supervisor replacement, sandboxed code runner, branch review apps, Bun framework demo, Next.js density vs `docker run`, idle-PSS per stack (Bun / Hono / SvelteKit / Astro / Next.js), cgroup memory tuning, observability, soak test, traffic density, and the volume substrate PoC. Most carry head-to-head benches with reproducible numbers.\n\n## When it doesn't (yet)\n\n- **You need `git push` deploys.** No build pipeline in `creekd`; that lives in the wider Creek stack.\n- **You need TLS in the daemon.** Put Caddy / Cloudflare / nginx in front.\n- **You need a web dashboard.** Only CLI (`creekctl`) and JSON API right now.\n- **You need multi-host scheduling.** One host per `creekd`; no clustering.\n- **You're running hostile multi-tenant workloads.** Phase 1 sandbox (cgroup + namespaces + chroot + NoNewPrivs) is meaningful but not full — seccomp and capability drop land in Phase 2.\n\n## Install\n\nReleased binaries for linux + darwin × amd64 + arm64:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/solcreek/creekd/main/install.sh | sh\n```\n\nOr build from source — requires Go 1.22+, Linux for the full feature set, macOS for dev (cgroup / namespace paths self-skip):\n\n```bash\ngo build -o bin/creekd  ./cmd/creekd\ngo build -o bin/creekctl ./cmd/creekctl\n```\n\n## Quickstart\n\n```bash\n# Run the daemon (loopback only, no auth — dev mode).\ncreekd \u0026\n\n# In another shell: spawn an app.\ncreekctl up hello \\\n    --command /bin/sh \\\n    --arg -c \\\n    --arg 'while true; do printf \"HTTP/1.1 200 OK\\r\\nContent-Length: 5\\r\\n\\r\\nhello\" | nc -l -p 18000 -q 1; done' \\\n    --port 18000\n\n# Route to it via the dispatch listener.\ncurl -H 'X-Creek-App: hello' http://127.0.0.1:9000/\n# =\u003e hello\n\n# Inspect, then stop.\ncreekctl ps\ncreekctl rm hello\n```\n\nFor real apps see [`docs/CONFIG.md`](docs/CONFIG.md) and the runtime profiles in [`internal/runtime/`](internal/runtime).\n\n## Architecture\n\n```\n                       creekd\n   ┌──────────────────────────────────────────┐\n   │                                          │\n   │  admin api    ◀──── HTTP/JSON ────  creekctl\n   │  127.0.0.1:9080     (bearer auth)\n   │  ├─ spawn / stop / restart / deploy\n   │  ├─ ps / get / logs / stats\n   │  └─ /debug/pprof  (opt-in)\n   │                                          │\n   │  dispatch    ◀──── HTTP ──────────  end-users\n   │  :9000              (host/header → app)\n   │                                          │\n   │  supervisor                              │\n   │   ┌─────┐  ┌─────┐  ┌─────┐              │\n   │   │ app │  │ app │  │ app │   ← child processes\n   │   │  A  │  │  B  │  │  C  │     each w/ own cgroup,\n   │   │ Bun │  │Node │  │Deno │     optional netns/PID ns,\n   │   └─────┘  └─────┘  └─────┘     setpriv NoNewPrivs\n   │                                          │\n   └──────────────────────────────────────────┘\n\n       state ──────► state.json   (declared apps, atomic write)\n       logs  ──────► \u003clog-dir\u003e/\u003cid\u003e/*.log  (size-rotated)\n```\n\nControl plane and data plane are **separate listeners** so admin tooling can sit behind one auth boundary while end-user traffic goes through another. The dispatch listener is also independently disable-able for admin-only deployments.\n\nSee [`docs/DESIGN.md`](docs/DESIGN.md) for design rationale and [`ARCHITECTURE.md`](ARCHITECTURE.md) for the principles that govern what gets added.\n\n## Configuration\n\nEverything is environment-variable driven. Full reference: [`docs/CONFIG.md`](docs/CONFIG.md).\n\nThe essentials:\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `CREEKD_ADMIN_ADDR` | `127.0.0.1:9080` | Admin / control plane listener |\n| `CREEKD_ADMIN_TOKEN` | _empty_ | Bearer token; **required** for non-loopback admin |\n| `CREEKD_DISPATCH_ADDR` | `127.0.0.1:9000` | Public dispatch / data plane (empty disables) |\n| `CREEKD_LOG_DIR` | _empty_ | Per-app log capture root |\n| `CREEKD_CGROUP_PARENT` | _empty_ | Cgroup v2 slice for per-app sub-cgroups |\n| `CREEKD_STATE_DIR` | _empty_ | Directory holding `state.json` (declared-app persistence) |\n| `CREEKD_NET_SUBNET` / `CREEKD_NET_BRIDGE_NAME` | _empty_ | Per-app netns subnet (e.g. `10.42.0.0/24`) + bridge name. Both required for `--net-isolation` |\n| `CREEKD_DEBUG_PPROF` | _unset_ | Set to `1` to mount `/debug/pprof` |\n\n## Building \u0026 testing\n\n```bash\ngo build ./...                                  # build everything\ngo test  -race ./...                            # full unit suite\n\nmake test-linux                                 # privileged Linux suite\n                                                # (cgroup v2, netns, namespaces)\n                                                # runs inside Docker; works\n                                                # on macOS hosts\n\nmake bench                                      # benchmark smoke\nmake bench-cpu                                  # + cpu/mem profiles\n```\n\nCI runs all three (`test`, `test-linux-privileged`, `bench`) on every push and PR.\n\n## Project layout\n\n```\ncreekd/\n├── cmd/\n│   ├── creekd/           # daemon entry point\n│   └── creekctl/         # admin CLI (talks to the admin API)\n├── internal/\n│   ├── supervisor/       # child-process lifecycle, restart policy\n│   ├── runtime/          # Bun / Node / Deno auto-detection\n│   ├── cgroup/           # cgroup v2 (memory / pids / cpu)\n│   ├── sandbox/          # Linux namespaces, chroot, NoNewPrivs\n│   ├── network/          # per-app netns + veth + iptables\n│   ├── dispatch/         # HTTP router, host → app\n│   ├── deploy/           # blue-green zero-downtime swap\n│   ├── logs/             # capture + size-based rotation\n│   ├── state/            # state.json persistence (atomic rename)\n│   ├── adminapi/         # HTTP/JSON control plane\n│   └── adminclient/      # typed Go client for the admin API\n├── docs/                 # roadmap, design, config\n└── .github/workflows/    # CI\n```\n\n## Related\n\n- [`solcreek/creek`](https://github.com/solcreek/creek) — runtime libraries, CLI for end developers, examples (TypeScript)\n\n## License\n\nApache 2.0. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolcreek%2Fcreekd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsolcreek%2Fcreekd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolcreek%2Fcreekd/lists"}