{"id":49525888,"url":"https://github.com/mrbildo/collabhost","last_synced_at":"2026-05-30T02:05:02.160Z","repository":{"id":351910862,"uuid":"1191016037","full_name":"MrBildo/collabhost","owner":"MrBildo","description":"A self-hosted application platform: process supervisor, Caddy reverse proxy control, and operator dashboard.","archived":false,"fork":false,"pushed_at":"2026-05-09T23:34:08.000Z","size":2160,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-09T23:36:07.861Z","etag":null,"topics":["aspire","aspnet-core","caddy","csharp","dashboard","dotnet","homelab","mcp","operator-console","platform","process-manager","process-supervisor","react","reverse-proxy","self-hosted","sqlite","typescript"],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MrBildo.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":null,"support":null,"governance":null,"roadmap":null,"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-03-24T20:54:35.000Z","updated_at":"2026-05-08T18:43:53.000Z","dependencies_parsed_at":"2026-05-16T02:00:52.488Z","dependency_job_id":null,"html_url":"https://github.com/MrBildo/collabhost","commit_stats":null,"previous_names":["mrbildo/collabhost"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/MrBildo/collabhost","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrBildo%2Fcollabhost","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrBildo%2Fcollabhost/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrBildo%2Fcollabhost/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrBildo%2Fcollabhost/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MrBildo","download_url":"https://codeload.github.com/MrBildo/collabhost/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrBildo%2Fcollabhost/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33087417,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T20:25:35.270Z","status":"online","status_checked_at":"2026-05-16T02:00:07.515Z","response_time":115,"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":["aspire","aspnet-core","caddy","csharp","dashboard","dotnet","homelab","mcp","operator-console","platform","process-manager","process-supervisor","react","reverse-proxy","self-hosted","sqlite","typescript"],"created_at":"2026-05-02T03:14:05.034Z","updated_at":"2026-05-30T02:05:02.153Z","avatar_url":"https://github.com/MrBildo.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"frontend/public/favicon.svg\" alt=\"Collabhost\" width=\"80\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eCollabhost\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  A self-hosted control plane for your workstation — operated from a dashboard, or driven by agents through a built-in MCP server.\u003cbr/\u003e\n  Native process supervision on Windows and Linux. Runs on macOS with a fallback runner.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/MrBildo/collabhost/actions/workflows/ci.yml\"\u003e\u003cimg alt=\"CI\" src=\"https://github.com/MrBildo/collabhost/actions/workflows/ci.yml/badge.svg?branch=main\" /\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"License: MIT\" src=\"https://img.shields.io/badge/license-MIT-blue?style=flat-square\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://dot.net/download\"\u003e\u003cimg alt=\".NET 10\" src=\"https://img.shields.io/badge/.NET-10-512BD4?style=flat-square\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://nodejs.org/\"\u003e\u003cimg alt=\"Node 22+\" src=\"https://img.shields.io/badge/node-22%2B-339933?style=flat-square\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## What is Collabhost?\n\nCollabhost gives you a single control plane for everything running on your machine — .NET services, Node.js apps, static sites, MCP servers, and arbitrary executables. Register an app, point it at a directory, and Collabhost handles process supervision, reverse proxy routing, log aggregation, and crash recovery. No containers. No YAML. No cloud account.\n\n**Two primary audiences.** An operator runs Collabhost from a War Machine dashboard — tables, log streams, inline actions. An agent runs Collabhost through a built-in MCP server — the same surface, exposed as tools over Streamable HTTP. Register an app from the UI or from Claude Code. Start, stop, tail logs, update settings. Humans and agents share one platform, one auth model, and one source of truth.\n\nIf you're building an AI harness, agent framework, or multi-agent system that needs to manage local infrastructure, Collabhost is the layer that sits underneath. See [For Agents](#for-agents) for MCP configuration.\n\nIt runs natively on **Windows** and **Linux** with platform-specific process management — no WSL required on Windows, no emulation layer on Linux. macOS runs the same control plane with a fallback process runner that has reduced containment — see [Platform support](#platform-support) for what differs. Think of it as a lightweight, self-hosted Heroku for your workstation — a control plane that stays out of your way until something goes wrong.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/dashboard.png\" alt=\"Collabhost Dashboard — stats, app table, and activity feed\" width=\"900\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003csub\u003eThe dashboard. Process supervision, routing, and a live activity feed on one screen.\u003c/sub\u003e\u003c/p\u003e\n\n## Install\n\nOne line. It downloads the latest release archive, verifies its SHA-256 against the release's `checksums.txt`, extracts to `~/.collabhost/bin` (Linux/macOS) or `%USERPROFILE%\\.collabhost\\bin` (Windows), and adds the directory to your `PATH`.\n\n**Linux / macOS:**\n\n```bash\ncurl -fsSL https://mrbildo.github.io/collabhost/install.sh | bash\n```\n\nOr download-then-execute if you'd rather inspect the script first:\n\n```bash\ncurl -fsSL https://mrbildo.github.io/collabhost/install.sh -o install.sh\nbash install.sh\n```\n\n**Windows (PowerShell):**\n\n```powershell\niwr -useb https://mrbildo.github.io/collabhost/install.ps1 | iex\n```\n\nOr download-then-execute:\n\n```powershell\niwr https://mrbildo.github.io/collabhost/install.ps1 -OutFile install.ps1\n.\\install.ps1\n```\n\nThen launch it:\n\n```bash\ncollabhost\n```\n\nOn first run, Collabhost seeds an administrator account and emits the API key once as a critical-level log line:\n\n```\ncrit: Collabhost.Api.Authorization.UserSeedService[0]\n      Collabhost admin key: 01JRSB8XH7D4Z2K9N0MFQPTVCW\n```\n\nCopy that key, open the dashboard at `http://localhost:58400`, and paste it into the API key prompt. You're in.\n\nRe-running the installer is upgrade-safe: your `appsettings.json` and `data/` directory are preserved across versions. For full operator documentation — reinstall, upgrade, uninstall, configuration, troubleshooting — see the `INSTALL.md` shipped inside the release archive (or in your install directory after the first run).\n\n### Caddy is bundled\n\nThe installer ships Caddy next to the Collabhost binary, and seeds `Proxy:BinaryPath` in `appsettings.json` to point at it on first install. No separate install step. On first launch, Collabhost starts the bundled Caddy as a supervised process and every registered app gets an automatic `{slug}.collab.internal` subdomain route.\n\nIf you'd rather use a system-installed Caddy, point Collabhost at it by either setting `COLLABHOST_CADDY_PATH` to the absolute path before launching (env var takes precedence) or editing `Proxy:BinaryPath` in `appsettings.json` directly. Operator edits to that key survive reinstalls — the installer only seeds the value when the key is absent or empty. See INSTALL.md §5.4 for the resolution chain. `BaseDomain` defaults to `collab.internal` — change it to use any domain you control.\n\nIf no Caddy binary is configured, everything else still works (app management, process supervision, logs, dashboard) — apps just don't get automatic subdomain routes, and `proxyState` reports `disabled` on `/api/v1/status`.\n\n### Register your first app\n\n**From the dashboard:** Open `http://localhost:58400` and click **Register App**. Pick an app type, point it at a directory, and hit create. Collabhost auto-discovers the start command and allocates a port. Click **Start** and watch the logs stream in.\n\n**From an agent:** See [For Agents](#for-agents) below. An agent calls `list_app_types`, `browse_filesystem`, `detect_strategy`, `register_app`, and `start_app` — the same flow, scripted.\n\n## Features\n\n**Built-in MCP server** — A Model Context Protocol endpoint at `/mcp` exposes the operator surface as tools. 18 tools across discovery, lifecycle, configuration, registration, and activity. Agents register apps, start and stop processes, tail logs, update settings, and browse the host filesystem — programmatically, over Streamable HTTP. Role-aware: administrators see everything, agents see 17 of 18 tools (everything except `delete_app`). See [For Agents](#for-agents) for setup.\n\n**Operator dashboard** — Real-time stats, app table with inline actions, live activity feed, and streaming log viewers. Everything an operator needs on one screen. The War Machine design system — dark, monospace, industrial — is built for density and quick action.\n\n**Process supervision** — Start, stop, restart, and kill managed processes with platform-native implementations for both Windows and Linux. On Windows: processes launch via `CreateProcess` with dedicated process groups, graceful shutdown via `GenerateConsoleCtrlEvent`, and orphan protection through Win32 Job Objects that guarantee child process cleanup even if Collabhost crashes. On Linux: process groups with `SIGTERM`/`SIGKILL` lifecycle and cgroup-based containment. Crash detection with automatic restart and configurable exponential backoff. Stdout/stderr captured into in-memory ring buffers.\n\n**Reverse proxy** — Every app gets a subdomain route automatically configured through [Caddy](https://caddyserver.com/). HTTPS via Caddy's internal CA. Routes sync on process state changes — no manual proxy config. The base domain is configurable in `appsettings.json`.\n\n**Schema-driven configuration** — App settings are defined by capability schemas. New capabilities surface in the UI and through MCP without frontend or tool changes. Override defaults per-app, see what's customized vs. inherited.\n\n**Multi-runtime support** — Five built-in app types out of the box:\n\n| Type | What it runs |\n|------|-------------|\n| `dotnet-app` | .NET applications (auto-discovers project files) |\n| `nodejs-app` | Node.js applications (reads package.json scripts) |\n| `static-site` | Static file directories (served via Caddy file_server) |\n| `executable` | Arbitrary binaries and scripts |\n| `system-service` | Platform services managed by Collabhost itself |\n\n**User management** — Header-based auth with administrator and agent roles. One-time API key reveal on creation. The same key authenticates the dashboard, the REST API, and the MCP server — mint a key for an agent and it can operate the platform.\n\n**Technology probing** — Automatic detection of runtimes, frameworks, and dependencies for registered apps. No manual tagging required. Surfaces in the dashboard and in `get_app` MCP responses.\n\n## Platform support\n\nProcess supervision is the piece of Collabhost that differs most by platform. The control plane itself — API, dashboard, MCP server, SQLite, Caddy integration — runs identically everywhere .NET 10 does. Process containment does not.\n\n| Platform | How processes are supervised |\n|---|---|\n| **Windows** | `CreateProcess` P/Invoke with dedicated process groups, graceful shutdown via `GenerateConsoleCtrlEvent`, orphan protection through Win32 Job Objects. |\n| **Linux** | `setsid` process groups with `SIGTERM`/`SIGKILL` lifecycle, cgroup v2 containment. Orphan-proof. |\n| **macOS** | `FallbackProcessRunner`. Processes start and stop, stdout/stderr capture works, and hard kill is available. No graceful shutdown (no `SIGTERM`-equivalent signal handling), no Job Object-equivalent isolation, no orphan protection — if Collabhost crashes, child processes may outlive it. |\n\nWindows and Linux are the recommended deployment targets. macOS runs the platform but with the gaps above — it's best suited for local development rather than long-running production workloads.\n\n## A tour\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/apps.png\" alt=\"App list with filter chips and search\" width=\"900\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003csub\u003eApp list. Filter by state, search, start and stop with one click.\u003c/sub\u003e\u003c/p\u003e\n\n\u003cbr/\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/app-detail.png\" alt=\"App detail with log viewer and route info\" width=\"900\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003csub\u003eApp detail. PID, port, uptime, route target, and live log streaming.\u003c/sub\u003e\u003c/p\u003e\n\n\u003cbr/\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/app-detail-tech.png\" alt=\"Technology tab with runtime and dependency detection\" width=\"900\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003csub\u003eTechnology probe. Collabhost detects runtimes, frameworks, and notable dependencies automatically.\u003c/sub\u003e\u003c/p\u003e\n\n\u003cbr/\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/settings.png\" alt=\"Schema-driven app settings\" width=\"900\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003csub\u003eSchema-driven settings. Every capability surfaces here without frontend changes.\u003c/sub\u003e\u003c/p\u003e\n\n\u003cbr/\u003e\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\" align=\"center\"\u003e\n      \u003cimg src=\"docs/screenshots/register-type-picker.png\" alt=\"App type picker\" /\u003e\n      \u003cbr/\u003e\n      \u003csub\u003eRegister, step 1. Pick a type.\u003c/sub\u003e\n    \u003c/td\u003e\n    \u003ctd width=\"50%\" align=\"center\"\u003e\n      \u003cimg src=\"docs/screenshots/register-form.png\" alt=\"Schema-driven registration form\" /\u003e\n      \u003cbr/\u003e\n      \u003csub\u003eRegister, step 2. Configure.\u003c/sub\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cbr/\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/screenshots/routes.png\" alt=\"Routes table showing Caddy proxy configuration\" width=\"900\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003csub\u003eRoutes. Every app gets an automatic \u003ccode\u003e{slug}.collab.internal\u003c/code\u003e subdomain with HTTPS (the base domain is configurable).\u003c/sub\u003e\u003c/p\u003e\n\n## For Agents\n\nCollabhost exposes an MCP (Model Context Protocol) server so agents can operate the platform directly — no custom HTTP client, no REST adapter. If your agent speaks MCP, it speaks Collabhost.\n\n### Endpoint\n\n| | |\n|---|---|\n| URL | `http://localhost:58400/mcp` |\n| Transport | Streamable HTTP (stateless) |\n| Auth | `X-User-Key` header with a user's ULID key |\n| Server name | `collabhost` |\n\nThe API port defaults to `58400`. If something else on your host already owns that port, override it via `Hosting:ListenPort` in `appsettings.json` or the `COLLABHOST_HOSTING_LISTEN_PORT` environment variable.\n\n### Configure an agent client\n\nClaude Code, and any other client that reads project-scoped `.mcp.json`, connects with this config:\n\n```json\n{\n  \"mcpServers\": {\n    \"collabhost\": {\n      \"type\": \"http\",\n      \"url\": \"http://localhost:58400/mcp\",\n      \"headers\": {\n        \"X-User-Key\": \"\u003cyour-agent-key\u003e\"\n      }\n    }\n  }\n}\n```\n\nDrop that in your project's `.mcp.json` (or the equivalent for your client) and your agent has Collabhost as a tool surface. Other MCP-speaking clients typically accept the same three pieces of information in their own configuration format: transport type (`http`), endpoint URL, and the `X-User-Key` header.\n\n### Mint an agent key\n\n1. Sign in to the dashboard as an administrator.\n2. Open **Users** from the topbar.\n3. Click **Create User**, pick the **Agent** role, give it a name, and create.\n4. The key is revealed **once** on creation. Copy it into your MCP config. If you lose it, deactivate the user and mint a new one.\n\n### Roles\n\n| Role | Access |\n|------|--------|\n| Administrator | Full tool surface (18 tools) plus user management through the REST API. |\n| Agent | 17 of 18 tools. Everything except `delete_app` (deletion is administrator-only). |\n\n### Tool surface\n\n18 tools, grouped by workflow:\n\n- **Discovery (4)** — `get_system_status`, `list_apps`, `get_app`, `list_app_types`. The agent's starting point: what's on the platform, what's running, what can it register.\n- **Lifecycle (5)** — `start_app`, `stop_app`, `restart_app`, `kill_app`, `get_logs`. Full process control. `get_logs` is token-budgeted for LLM context.\n- **Configuration (4)** — `get_settings`, `update_settings`, `list_routes`, `reload_proxy`. Read and change schema-driven settings, inspect Caddy routes.\n- **Registration (4)** — `register_app`, `delete_app`, `browse_filesystem`, `detect_strategy`. End-to-end app setup. `browse_filesystem` lets agents locate install directories iteratively; `detect_strategy` reports what Collabhost can auto-discover for a given path and app type.\n- **Activity (1)** — `list_events`. Recent state changes and operator actions, filterable by app, event type, or category.\n\nEach tool has a full description, parameter schema, and read-only/destructive/idempotent annotations. The MCP server also ships `ServerInstructions` describing common workflows (registration, lifecycle, diagnostics) so a freshly-connected agent has a usable mental model without reading the source.\n\nApps are identified by **slug** throughout (e.g. `my-api-server`), not by ULID. Agents use the same identifier operators see in the URL bar.\n\n## Tech Stack\n\n| Layer | Technology |\n|-------|-----------|\n| Backend | .NET 10, C# Minimal API, EF Core, SQLite |\n| Frontend | React 19, TypeScript, Vite |\n| Design System | *War Machine* (custom — dark, monospace, industrial) |\n| Reverse Proxy | Caddy (managed via JSON admin API) |\n| Orchestration | .NET Aspire 13.3 (preview), OpenTelemetry |\n| Testing | xUnit + Shouldly (backend), Vitest (frontend) |\n| Linting | Roslyn analyzers (backend), Biome (frontend) |\n\n## Architecture\n\nCollabhost has four layers:\n\n- **Caddy** is the front door — edge reverse proxy, TLS termination, routing\n- **ASP.NET Core** is the control tower — app registry, process supervision, auth, and the MCP endpoint\n- **React dashboard** is the operator console — the *War Machine* design system\n- **MCP server** is the agent console — the same operator surface, exposed as tools at `/mcp`\n\nApps are registered with a slug, discovered from the filesystem, and supervised as managed processes. Caddy routes are synchronized automatically when process state changes. SQLite handles persistence with zero configuration. The REST API and MCP endpoint are parallel presentation surfaces over the same shared services — anything an operator can do from the dashboard, an agent can do from an MCP client.\n\n## Contributing\n\nContributions are welcome. If you'd like to build from source, run the dev environment, or submit a pull request, see [CONTRIBUTING.md](CONTRIBUTING.md) for prerequisites, setup, coding conventions, and the PR process.\n\n## Security and bundled-binary maintenance\n\nCollabhost ships a Caddy binary in its release archive, which means Collabhost owns Caddy's CVE response window for end users. See [docs/release-process.md](docs/release-process.md) for the upstream-monitoring sources, response-time SLA, release checklist, and version-pin mechanism.\n\n## Credits\n\nCollabhost is built by a human-AI collaborative team. The bots are autonomous AI agents on the Collabot platform — they design, write code, review each other's work, and ship features alongside their human teammate.\n\n**Bill Wheelock** — Concept, design, and technical leadership — [mrbildo@mrbildo.net](mailto:mrbildo@mrbildo.net)\n\n**Bot Nolan** — Project management — [nolan@collabot.dev](mailto:nolan@collabot.dev)\n\n**Bot Dana** — Logo, *War Machine* theme, frontend design, TypeScript — [dana@collabot.dev](mailto:dana@collabot.dev)\n\n**Bot Remy** — Backend design, architecture, C# — [remy@collabot.dev](mailto:remy@collabot.dev)\n\n**Bot Marcus** — Backend design, architecture, C# — [marcus@collabot.dev](mailto:marcus@collabot.dev)\n\n**Bot Kai** — Code review, simplification, tooling, C# — [kai@collabot.dev](mailto:kai@collabot.dev)\n\n**Bot Theo** — Tooling, harness and skill authoring, infrastructure — [theo@collabot.dev](mailto:theo@collabot.dev)\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrbildo%2Fcollabhost","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrbildo%2Fcollabhost","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrbildo%2Fcollabhost/lists"}