Merge pull request #53 from chiruu12/feat/agentos-deploy

AgentOS Phase 5: Docker deployment

Author: chiruu12

.dockerignore

@@ -0,0 +1,20 @@
+.git
+.github
+.context
+.venv
+venv
+__pycache__
+*.pyc
+.pytest_cache
+.mypy_cache
+.ruff_cache
+site
+dist
+build
+*.egg-info
+.hive
+logs
+tests
+docs
+.env
+.DS_Store

Dockerfile

@@ -0,0 +1,49 @@
+# Hive AgentOS -- containerized REST API + control plane.
+#
+# Build:  docker build -t hive-agentos .
+# Run:    docker run -p 8000:8000 -e ANTHROPIC_API_KEY=sk-... -v hive_state:/data hive-agentos
+# Then open http://localhost:8000/ (control plane) or /docs (API).
+
+FROM python:3.12-slim AS build
+
+# uv for a fast, reproducible install. Pinned so builds don't drift with uv releases
+# (keep in sync with the uv that resolved uv.lock).
+COPY --from=ghcr.io/astral-sh/uv:0.9.3 /uv /usr/local/bin/uv
+
+WORKDIR /app
+COPY pyproject.toml uv.lock README.md ./
+COPY src ./src
+COPY profiles ./profiles
+COPY skills ./skills
+COPY models.yaml ./models.yaml
+
+# Install the package (with the API extra) into a self-contained venv.
+# --no-editable copies hive into site-packages (an editable install would leave a
+# .pth pointing at /app/src, which the runtime stage does not carry).
+ENV UV_PROJECT_ENVIRONMENT=/opt/venv
+RUN uv sync --frozen --extra api --no-dev --no-editable
+
+
+FROM python:3.12-slim AS runtime
+
+# Non-root user; agent workspaces and state live under /data.
+RUN useradd --create-home --uid 1000 hive \
+    && mkdir -p /data && chown hive:hive /data
+COPY --from=build /opt/venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+USER hive
+WORKDIR /data
+
+EXPOSE 8000
+
+# Report container health via the API's readiness endpoint (urllib ships with the
+# slim base, so no extra dependency). Enables `docker ps` health + service_healthy.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/healthz')" \
+    || exit 1
+
+# The API server, with the heartbeat loop in-process. `hive init` is idempotent and
+# scaffolds .hive/ in the mounted /data volume on first run. Its stderr is kept (not
+# silenced) so a real init failure -- bad /data permissions, disk full -- is visible.
+ENTRYPOINT ["sh", "-c", "hive init 2>&1 || true; exec hive serve --host 0.0.0.0 --port 8000 --with-daemon"]

docker-compose.yml

@@ -0,0 +1,27 @@
+# Hive AgentOS -- one-command local deployment.
+#
+#   ANTHROPIC_API_KEY=sk-... docker compose up --build
+#
+# Control plane: http://localhost:8000/   API docs: http://localhost:8000/docs
+
+services:
+  hive:
+    build: .
+    image: hive-agentos
+    ports:
+      # Bind to loopback only -- matches the local-dev / reverse-proxy posture. Use
+      # "8000:8000" (or put a proxy in front) to expose it on the network.
+      - "127.0.0.1:8000:8000"
+    environment:
+      # Pass through provider keys from your shell / .env (only what you use).
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
+      - OPENAI_API_KEY=${OPENAI_API_KEY:-}
+      - GROQ_API_KEY=${GROQ_API_KEY:-}
+      - HIVE_DEFAULT_MODEL=${HIVE_DEFAULT_MODEL:-claude-haiku-4-5}
+    volumes:
+      # Persist agent state, logs, and workspaces across restarts.
+      - hive_state:/data
+    restart: unless-stopped
+
+volumes:
+  hive_state:

docs/changelog.md

@@ -34,6 +34,9 @@
   `hive serve` (no build step, no data egress) -- the pending-approval queue with
   approve/deny, a live agents list, and sessions, auto-refreshing. Tenant-aware via
   an `X-Hive-User` field.
+- **Docker deployment**: a multi-stage `Dockerfile` and `docker-compose.yml` run the
+  REST API + control plane and the heartbeat daemon in one non-root container with a
+  persistent `/data` volume. `ANTHROPIC_API_KEY=sk-... docker compose up --build`.
 
 ## [0.6.1] -- 2026-06-03
 

docs/guide/deployment.md

@@ -0,0 +1,56 @@
+# Deployment
+
+Hive ships a `Dockerfile` and `docker-compose.yml` that run the REST API and the
+heartbeat daemon together in one container -- the agent OS in your own infrastructure.
+
+## Docker Compose (one command)
+
+```bash
+ANTHROPIC_API_KEY=sk-... docker compose up --build
+```
+
+- Control plane: <http://localhost:8000/>
+- API docs: <http://localhost:8000/docs>
+
+Provider keys are read from your shell (or a `.env` file) and passed through; set only
+the ones you use (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GROQ_API_KEY`,
+`HIVE_DEFAULT_MODEL`). Agent state, logs, and workspaces persist in the `hive_state`
+volume across restarts.
+
+## Plain Docker
+
+```bash
+docker build -t hive-agentos .
+docker run -p 8000:8000 \
+  -e ANTHROPIC_API_KEY=sk-... \
+  -v hive_state:/data \
+  hive-agentos
+```
+
+## How the image is built
+
+- **Multi-stage**: a build stage installs the package (with the `[api]` extra) into a
+  self-contained venv via `uv sync --no-editable`; the slim runtime stage copies only
+  that venv.
+- Runs as a **non-root** user; all writable state lives under `/data` (the working
+  directory and the mount point), so the container filesystem stays read-only-friendly.
+- The entrypoint runs the idempotent `hive init` then
+  `hive serve --host 0.0.0.0 --port 8000 --with-daemon`, so a single process serves
+  HTTP and drives agents.
+
+## Scaling notes
+
+`hive serve` (without `--with-daemon`) is **stateless** and can run behind a load
+balancer with several replicas, all reading/writing one shared `.hive/hive.db` (SQLite
+WAL handles concurrent access). Run **one** `--with-daemon` instance (or a standalone
+`hive start`) to drive the heartbeat, and scale the API replicas separately. For
+heavier multi-writer loads, point the daemon and API at shared storage for `/data`.
+
+## Production checklist
+
+- Set real provider API keys via secrets, not in the image.
+- Put the API behind TLS and authentication (the server binds `0.0.0.0` in the
+  container; restrict exposure at the proxy/ingress).
+- Back up the `/data` volume (it holds the SQLite DB, event logs, and workspaces).
+- Tune `.hive/config.yaml` (`daemon.heartbeat`, `daemon.max_concurrent_agents`) for
+  your workload; enable `approval` and `guardrails` for untrusted use.

mkdocs.yml

@@ -66,6 +66,7 @@ nav:
     - CLI Reference: guide/cli-reference.md
     - REST API: guide/rest-api.md
     - Evals: guide/evals.md
+    - Deployment: guide/deployment.md
     - Architecture: guide/architecture.md
   - Extending:
     - Extension Points: extending/index.md