{"id":51101670,"url":"https://github.com/fox-in-the-box-ai/fox-fleet","last_synced_at":"2026-06-24T11:02:03.689Z","repository":{"id":363056293,"uuid":"1261041634","full_name":"fox-in-the-box-ai/fox-fleet","owner":"fox-in-the-box-ai","description":"  The Apache 2.0 management plane for Fox in the Box — provisioning, health monitoring, and lifecycle management for fleets of AI assistants.","archived":false,"fork":false,"pushed_at":"2026-06-17T07:08:09.000Z","size":3825,"stargazers_count":0,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-17T07:11:40.167Z","etag":null,"topics":["ai","ai-agent","ai-assistant","ai-tools","apache-2","docker","enterprise","fleet-management","golang","hermes-agent","hermes-managed","llm","nous-hermes","nous-research","nousresearch","open-source","self-hosted"],"latest_commit_sha":null,"homepage":"https://foxinthebox.io","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/fox-in-the-box-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","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-06-06T06:55:39.000Z","updated_at":"2026-06-17T07:05:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fox-in-the-box-ai/fox-fleet","commit_stats":null,"previous_names":["fox-in-the-box-ai/fox-fleet"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/fox-in-the-box-ai/fox-fleet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fox-in-the-box-ai%2Ffox-fleet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fox-in-the-box-ai%2Ffox-fleet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fox-in-the-box-ai%2Ffox-fleet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fox-in-the-box-ai%2Ffox-fleet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fox-in-the-box-ai","download_url":"https://codeload.github.com/fox-in-the-box-ai/fox-fleet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fox-in-the-box-ai%2Ffox-fleet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34728928,"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-06-24T02:00:07.484Z","response_time":106,"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":["ai","ai-agent","ai-assistant","ai-tools","apache-2","docker","enterprise","fleet-management","golang","hermes-agent","hermes-managed","llm","nous-hermes","nous-research","nousresearch","open-source","self-hosted"],"created_at":"2026-06-24T11:02:02.951Z","updated_at":"2026-06-24T11:02:03.674Z","avatar_url":"https://github.com/fox-in-the-box-ai.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fox Fleet\n\n[![CI](https://github.com/fox-in-the-box-ai/fox-fleet/actions/workflows/ci.yml/badge.svg)](https://github.com/fox-in-the-box-ai/fox-fleet/actions/workflows/ci.yml)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![Go](https://img.shields.io/github/go-mod/go-version/fox-in-the-box-ai/fox-fleet)](go.mod)\n\nOpen-source management plane for [Fox in the Box](https://github.com/fox-in-the-box-ai/fox-in-the-box) AI assistants. One binary, one config file, one Docker host — provision, monitor, update, and destroy a fleet of Fox instances through a CLI and browser-based panel.\n\n\u003e **Status: v1.8.0 GA.** Production-ready. Subdomain-per-instance routing, per-user sessions, signed releases (cosign + SBOM), conformance suite, full deployment paths (Compose / Helm / systemd / Homebrew / apt / container image).\n\n---\n\n## Why Fox Fleet\n\nRunning one Fox assistant is easy. Running five for a team means five containers, five port assignments, five health checks, five image updates — all by hand.\n\nFox Fleet eliminates that. A single `fox-control` binary manages the full lifecycle:\n\n- **Provision** — allocate a port, inject config and credentials, start a container, health-check until ready.\n- **Monitor** — browser panel with per-instance health status, logs, and image metadata.\n- **Update** — rolling image rollout with automatic health-gating and one-command rollback.\n- **Destroy** — stop the container, optionally remove data, clean up the registry.\n\nEvery managed instance is an unmodified Fox container. Fleet wraps instances with management infrastructure — it never modifies them. Remove Fleet, and every instance keeps running on its last-injected config.\n\n---\n\n## Install\n\nPick your platform. Each guide covers every available install channel and verification steps.\n\n| Platform | Recommended channel | Guide |\n|----------|-------------------|-------|\n| **Linux** | Install script | [docs/install/linux.md](docs/install/linux.md) |\n| **macOS** | Homebrew | [docs/install/macos.md](docs/install/macos.md) |\n| **Windows** | Docker Compose | [docs/install/windows.md](docs/install/windows.md) |\n| **Kubernetes** | Helm chart | [docs/install/kubernetes.md](docs/install/kubernetes.md) |\n\n### Verify installation\n\n```bash\nfox-control version\n# fox-control v1.6.0 (commit abc1234, built 2026-06-18)\n```\n\nFor container deployments:\n\n```bash\ncurl -s http://localhost:9090/healthz\n# {\"status\":\"ok\"}\n```\n\nRelease artifacts are signed with [Sigstore cosign](https://docs.sigstore.dev/cosign/overview/) and include an SBOM. See [docs/security/signing.md](docs/security/signing.md) for verification commands.\n\n---\n\n## Quickstart\n\nEnd-to-end guides — from zero to a running Fleet with one provisioned Fox assistant, under 15 minutes.\n\n| Platform | Guide |\n|----------|-------|\n| **Linux** | [docs/quickstart/linux.md](docs/quickstart/linux.md) |\n| **macOS** | [docs/quickstart/macos.md](docs/quickstart/macos.md) |\n| **Windows** | [docs/quickstart/windows.md](docs/quickstart/windows.md) |\n| **Kubernetes** | [docs/quickstart/kubernetes.md](docs/quickstart/kubernetes.md) |\n\nFor a detailed step-by-step walkthrough (12 scenes from first launch to fleet management), see [docs/WALKTHROUGH.md](docs/WALKTHROUGH.md).\n\n---\n\n## What end users see\n\nFox Fleet is the management plane — operators install and run it. End users interact with **Fox**, the AI assistant, through their browser.\n\nOnce an operator provisions a Fox instance, end users open it at the instance URL (default `http://localhost:8787`) and follow the onboarding wizard to configure their AI provider. From there, Fox provides a chat interface with memory, multi-profile support, and skills.\n\nFox is a separate project with its own documentation:\n\n- **Fox in the Box** — [github.com/fox-in-the-box-ai/fox-in-the-box](https://github.com/fox-in-the-box-ai/fox-in-the-box)\n\nOperators: point your team members to the Fox project README for end-user setup and usage guidance.\n\n---\n\n## Operator handbook\n\nFor day-2 operations — instance lifecycle, secret rotation, skillset management, knowledge data plane, rolling updates, backup and recovery, monitoring, capacity, and security operations:\n\n[docs/operator/handbook.md](docs/operator/handbook.md)\n\nFor deployment method details (Docker Compose, Helm, systemd, binary):\n\n[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)\n\nFor full configuration reference:\n\n[docs/configuration.md](docs/configuration.md)\n\n---\n\n## Architecture\n\n```mermaid\ngraph TB\n    subgraph \"fox-control (single Go binary)\"\n        CLI[\"CLI\u003cbr/\u003e\u003ccode\u003efox-control serve\u003c/code\u003e\"]\n        Panel[\"Dashboard\u003cbr/\u003eAPI + SPA\u003cbr/\u003e:9090\"]\n        Provisioner[\"Provisioner\"]\n        Registry[\"Registry\u003cbr/\u003e(SQLite)\"]\n        Plugin[\"Docker Plugin\"]\n        Config[\"Config\u003cbr/\u003eInjection\"]\n        DataPlane[\"Data Plane\u003cbr/\u003e:9091\"]\n        SourceReg[\"Source\u003cbr/\u003eRegistry\"]\n    end\n\n    subgraph \"Sidecar\"\n        Qdrant[\"Qdrant\u003cbr/\u003eVector DB\"]\n    end\n\n    CLI --\u003e Panel\n    Panel --\u003e Provisioner\n    Panel --\u003e DataPlane\n    Provisioner --\u003e Registry\n    Provisioner --\u003e Plugin\n    Provisioner --\u003e Config\n\n    DataPlane --\u003e SourceReg\n    DataPlane --\u003e Qdrant\n\n    Plugin --\u003e InstanceA[\"Fox Instance A\u003cbr/\u003e:8787\"]\n    Plugin --\u003e InstanceB[\"Fox Instance B\u003cbr/\u003e:8788\"]\n    Config --\u003e InstanceA\n    Config --\u003e InstanceB\n    InstanceA -.-\u003e|\"knowledge_query\"| DataPlane\n    InstanceB -.-\u003e|\"knowledge_query\"| DataPlane\n\n    style InstanceA fill:#e8f5e9\n    style InstanceB fill:#e8f5e9\n    style Qdrant fill:#e3f2fd\n```\n\n**Key design decisions:**\n\n- **Plugin interface** — `DeploymentPlugin` is a 9-method Go interface (Provision, HealthCheck, Configure, Rollout, Rollback, Destroy, Logs, Restart, Stats). Docker is the built-in implementation. The interface accommodates Kubernetes and Compose plugins without changes.\n- **SQLite registry** — instance metadata in a single embedded database. CGO-free via `modernc.org/sqlite`. No external database dependency.\n- **Config injection** — each instance gets its own data directory with `config.yaml`, `settings.json`, `hermes.env`, and `tools.json` written before container start. When a data plane is configured, `tools.json` includes a `knowledge_query` tool manifest pointing instances at the query API. Credentials are injected as environment variables, never baked into images.\n- **Data plane** — optional organizational knowledge layer. File and REST ingestion connectors chunk documents, embed them via an OpenAI-compatible API, and store vectors in a shared Qdrant sidecar. Instances query the data plane through the `knowledge_query` tool injected by config injection.\n- **Shared-secret auth** — `admin_secret` authenticates the operator to the panel and is injected into each instance as `FOX_PLANE_AUTH_SECRET`. The instance's `check_auth` gate validates it. In cloud mode, each instance additionally receives unique CSPRNG-generated credentials at provision time, so compromising one instance does not expose others.\n- **Subdomain routing (cloud mode)** — when `cloud.domain` is configured, each user's Fox instance is served at `\u003cusername\u003e.\u003cdomain\u003e`. A host dispatcher routes by `Host` header: base domain to the admin panel, subdomains to the instance reverse proxy with session auth. Caddy `on_demand_tls` issues per-subdomain certificates validated by a loopback-restricted TLS check endpoint.\n\n### Architecture invariants\n\nThese hold across the entire Fox ecosystem. Fleet inherits all of them.\n\n1. **Wrap, don't fork** — Fleet wraps fleets of Fox instances the same way the Fox overlay wraps Hermes. Additive behavior via HTTP contracts and config injection, never source modification.\n2. **Additive and removable** — every Fleet-managed surface can be removed. Instances keep running. The panel disappearing doesn't affect containers. Data plane disappearing doesn't break chat.\n3. **Fail loud** — missing secrets, missing config, unreachable dependencies produce explicit errors. `fox-control` refuses to start if `admin_secret` or `instance_password` is empty.\n4. **Single-tenant instance** — one isolated assistant per person. Fleet is multi-instance management; instances themselves are single-tenant.\n5. **Runtime-agnostic** — HTTP contracts only. Fox (Hermes) is the reference runtime. The `DeploymentPlugin` interface and instance contract support any conformant runtime.\n\n### Known limitations\n\nFox Fleet has intentional architectural boundaries: single-host only (no multi-node), no HA (single SQLite), single admin token (no RBAC), Docker socket is root-equivalent. See [docs/LIMITATIONS.md](docs/LIMITATIONS.md) for the full list.\n\n---\n\n## The Fox ecosystem\n\nFox Fleet is the middle layer of a four-repo open-core architecture:\n\n```\nfox-in-the-box (MIT)           The assistant runtime\n        ▲\n        │ contract schemas, HTTP client\n        │\nfox-fleet (Apache 2.0)         This repo — management plane for fleets\n        ▲\n        │ Go module import\n        │\nfox-fleet-enterprise           Enterprise overlay (RBAC, audit, LLM proxy,\n(Commercial)                   OIDC edge gateway, K8s plugin)\n        ▲\n        │\nfox-cloud (Commercial)         Hosted product\n```\n\n**Dependency direction is one-way.** Fox never imports Fleet. Fleet never imports Enterprise. Removing any layer leaves the layer below fully operational.\n\n| Product | License | Default cap | What it adds |\n|---------|---------|-------------|-------------|\n| **Fox in the Box** | MIT | 1 (single-user) | The assistant itself — container image, desktop app, overlay |\n| **Fox Fleet** | Apache 2.0 | 2 (configurable) | Provisioning, monitoring, updates, knowledge data plane, skillsets |\n| **Fox Fleet Enterprise** | Commercial | Unlimited | RBAC, audit logs, LLM proxy, SSO/OIDC, K8s plugin |\n| **Fox Cloud** | Commercial | Unlimited | Hosted runtime, billing, multi-tenant |\n\n---\n\n## Status and roadmap\n\n| Milestone | Theme | Status |\n|-----------|-------|--------|\n| **v0.1** | Management plane MVP — provision, monitor, update, destroy through CLI and panel | Shipped (0.1.0-alpha) |\n| **v0.2** | Data plane — organizational knowledge (ingestion, vector search, query API, skillsets) | Shipped (0.2.0-alpha) |\n| **v0.3** | Product polish — branded UI, i18n, dark mode, mobile, SSE, deployment infra, docs | Shipped (0.3.0-alpha) |\n| **v1.0** | Apache GA — conformance suite, cosign + SBOM, full deployment paths, all PRODUCTS.md promises | Shipped (1.0.0) |\n| **v1.0.1** | SSE auth hardened (session tokens), data plane query auth | Shipped (1.0.1) |\n| **v1.1** | Security hardening — file permissions, SSRF, path traversal, WriteTimeout, env blocklist, security headers, persistent events | Shipped (1.1.0) |\n| **v1.2** | Operations — Prometheus metrics, built-in TLS, backup CLI, diagnostics, webhooks, structured logging, rate limiting | Shipped (1.2.0) |\n| **v1.3** | Data plane hardening — embedding retry, Qdrant timeouts/batching/health, incremental ingestion, auto-restart, conformance | Shipped (1.3.0) |\n| **v1.4** | Panel \u0026 docs — health timeline, resource gauges, i18n (en/es/fr), skillset picker, operator/developer handbooks, OpenAPI spec, examples | Shipped (1.4.0) |\n| **v1.5** | Cloud mode — multi-user provisioning with login sessions, cloud login page, CSP hardening, data dir permissions, .deb packaging fixes | Shipped (1.5.3) |\n| **v1.6** | Subdomain-per-instance routing — each user's Fox served at `\u003cusername\u003e.\u003cdomain\u003e`, per-instance secrets, on-demand TLS, host-based dispatch | Shipped (1.6.0) |\n| **v1.7** | Cloud mode hardening — user-instance binding enforcement (slug = username invariant), admin API auto-bind, provision endpoint validation | Shipped (1.7.2) |\n\nFull roadmap: [FLEET_BASE_ROADMAP.md](https://github.com/fox-in-the-box-ai/fox-in-the-box/blob/main/docs/architecture/FLEET_BASE_ROADMAP.md)\n\n---\n\n## Development\n\n### Prerequisites\n\n- Go 1.25+\n- Docker (for integration tests and the Docker plugin)\n- [golangci-lint](https://golangci-lint.run/) (for `make lint`)\n\n### Quality gate\n\n```bash\nmake lint          # golangci-lint run\nmake test          # go test ./...\nmake build         # go build with ldflags\nmake conformance   # runtime + plugin conformance suites\n```\n\nAll four commands must pass before opening a PR.\n\n### Repository layout\n\n```\ncmd/fox-control/       CLI entry point, TOML config parsing, cobra subcommands\ninternal/\n  config/              Config injection (writes instance data dirs incl. tools.json)\n  events/              Persistent event log (SQLite) + webhook dispatcher\n  output/              CLI output formatting (table, JSON, quiet)\n  provisioner/         Provisioning loop orchestrator (mutex, port alloc, skillset copy, rollback)\n  registry/            Instance registry (SQLite, CRUD, status + skillset tracking)\n  safedialer/          SSRF-safe net.Dialer (blocks private/loopback/link-local IPs)\n  sessiontoken/        HMAC-SHA256 session token signing and validation\nplugins/\n  plugin.go            DeploymentPlugin interface + shared types\n  docker/              Docker plugin implementation (9 methods)\npanel/\n  api/                 Dashboard HTTP API + health poller + source listing\n  spa/                 Embedded single-page dashboard (instances + sources tabs)\nconformance/\n  runtime/             Runtime conformance test suite (24 checks)\n  plugin/              Plugin conformance test suite (8 checks)\n  dataplane/           Data plane conformance test suite (10 checks)\nrollout/               Fleet rollout orchestration (rolling update + health-gated rollback)\ndata-plane/            Data plane server, Qdrant client, ingestion connectors, query API, source registry\nskillsets/             Skillset manifest spec, YAML parser + validator\ndocs/                  Product-specific documentation\n```\n\n---\n\n## Security\n\nSee [SECURITY.md](SECURITY.md) for vulnerability reporting policy.\n\nFox Fleet's auth model uses shared secrets (not OIDC/mTLS — those are Fleet Enterprise features). The `admin_secret` authenticates operator-to-panel and panel-to-instance communication via `X-Fox-Auth` headers with constant-time comparison. In cloud mode, each instance receives unique CSPRNG-generated credentials at provision time — compromising one instance's secrets does not expose others. Credentials are injected at provision time and never logged.\n\n**Release signing:** every release artifact (binaries, checksums, container images) is signed with [Sigstore cosign](https://docs.sigstore.dev/cosign/overview/) via GitHub Actions OIDC — no long-lived keys. Verify with `fox-control verify \u003ctarball\u003e` or cosign directly. See [docs/security/signing.md](docs/security/signing.md).\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n**Short version:** branch from `main`, one logical change per PR, all checks green, squash-merge. Commit messages in imperative present tense, referencing ticket IDs.\n\n---\n\n## License\n\n[Apache License 2.0](LICENSE)\n\nCopyright 2026 Vulpy, Inc.\n\n---\n\n\u003csub\u003eFox Fleet is part of the [Fox in the Box](https://github.com/fox-in-the-box-ai) ecosystem.\u003c/sub\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffox-in-the-box-ai%2Ffox-fleet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffox-in-the-box-ai%2Ffox-fleet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffox-in-the-box-ai%2Ffox-fleet/lists"}