Compare commits

..

16 Commits

Author SHA1 Message Date
Molecule AI App & Docs Lead c02acce869 fix(changelog): remove CWE-78 + OFFSEC-003 duplicates (docs#49 is canonical)
Both entries are in docs#49's changelog.mdx (workspace-abilities-
broadcast-changelog-2026-05-15). Removes duplicates to avoid
merge conflicts. Bug fixes and internal entries remain.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-16 13:44:03 +00:00
documentation-specialist 3df74aa87a docs(security/changelog): remove CWE-78 entry — already covered by docs#49
CI / build (pull_request) Waiting to run
Secret scan / secret-scan (pull_request) Waiting to run
The CWE-78 expandWithEnv POSIX-identifier guard regression entry is
authoritatively covered in docs#49's security/changelog.md. Removes the
duplicate from this PR to avoid merge conflicts.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-16 13:40:53 +00:00
documentation-specialist 151ae5543a docs(changelog): fix blank-line concatenation bug and remove duplicate CWE-78 entry
- Add blank line between CWE-78 and OFFSEC-003 Security entries (fixes
  MDX rendering concatenation bug)
- Remove duplicate expandWithEnv guard entry from Bug fixes section
  (CWE-78 is already covered in the Security section above)
- security/changelog.md change removed — CWE-78 is covered by docs#49

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-16 13:40:39 +00:00
app-lead 7f0bbcd97f fix(docs): remove OFFSEC-006 changelog bullet (set -f not in promote-tenant-image.sh; authoritative entry in docs#41)
Secret scan / secret-scan (pull_request) Successful in 42s
CI / build (pull_request) Successful in 2m56s
2026-05-15 09:10:39 +00:00
app-lead 65f417b3c0 fix(docs): remove OFFSEC-006 changelog bullet (set -f not in promote-tenant-image.sh; authoritative entry in docs#41)
Secret scan / secret-scan (pull_request) Successful in 14s
CI / build (pull_request) Successful in 3m11s
2026-05-15 09:10:12 +00:00
app-lead f0d2a5b960 fix(docs): remove OFFSEC-006 entry from changelog.mdx per hongming-pc2 review (set -f not in script; docs#41 has authoritative entry)
Secret scan / secret-scan (pull_request) Successful in 8s
CI / build (pull_request) Successful in 1m2s
2026-05-15 09:09:06 +00:00
app-fe c24bd9cd98 fix(docs): remove duplicate OFFSEC-006 and 2026-05-15 entries per hongming-pc2 review
Secret scan / secret-scan (pull_request) Successful in 53s
CI / build (pull_request) Successful in 2m53s
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-15 09:01:31 +00:00
app-lead edca18e875 fix(docs): remove duplicate OFFSEC-006/SSRF section per hongming-pc2 review (docs#41 has authoritative entry)
Secret scan / secret-scan (pull_request) Successful in 1s
CI / build (pull_request) Successful in 4m0s
2026-05-15 08:57:40 +00:00
app-lead e1e54e976c fix(docs): remove duplicate 2026-05-15 section per hongming-pc2 review (docs#49 has authoritative entry)
Secret scan / secret-scan (pull_request) Successful in 32s
CI / build (pull_request) Successful in 3m20s
2026-05-15 08:56:27 +00:00
documentation-specialist 7579152414 docs(changelog): update docs#40 → docs#46 for self-hosted Docker guide entry
Secret scan / secret-scan (pull_request) Successful in 0s
CI / build (pull_request) Successful in 3m21s
docs#40 is closed; the tutorial file is now on docs#46's branch.
Updated the entry to reference docs#46 and mention the Kubernetes
terminationGracePeriodSeconds fix.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-15 05:16:50 +00:00
documentation-specialist a491773cd7 docs(changelog): replace 2026-05-15 placeholder with full daily entry
CI / build (pull_request) Failing after 14m17s
Secret scan / secret-scan (pull_request) Failing after 14m11s
Covers all docs PRs merged 2026-05-15:
- docs#44: MCP HTTP/SSE transport gap-fill
- docs#41: OFFSEC-006 SSRF advisory published
- docs#40: self-hosted Docker deployment guide
- docs#30: dev-channels flag requirement page
- docs#29: remote-workspaces graceful shutdown
- docs#32: PLATFORM_URL defaults fix
- docs#31: CWE-22 regression advisory added
- docs#27: SOP checklist gate
- docs#28/37/36/33: changelog structural fixes

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-15 04:53:17 +00:00
documentation-specialist 65942ab786 docs(changelog): add OFFSEC-006 tenant-slug SSRF advisory to 2026-05-14 + security changelog
CI / build (pull_request) Failing after 12m0s
Secret scan / secret-scan (pull_request) Failing after 11m57s
Adds molecule-core#933 (OFFSEC-006, CWE-918 SSRF + token exfiltration)
to the 2026-05-14 Security section in changelog.mdx.

Also adds OFFSEC-006 to the Security Changelog (security/changelog.md)
with full vulnerability + fix details, cross-referencing docs#41
(offsec-006-slug-ssrf-advisory.mdx) which will add the full
advisory page when it merges.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-15 04:30:57 +00:00
documentation-specialist a8ae866ce1 docs(changelog): add 2026-05-15 placeholder section
Secret scan / secret-scan (pull_request) Successful in 1m36s
CI / build (pull_request) Successful in 5m21s
Day 2026-05-15 begins with no merged PRs (cron fired at 02:15 UTC;
entry will be populated at 23:50 UTC when the day is finalised).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-15 02:22:16 +00:00
documentation-specialist e409a67539 docs(changelog): add openclaw#4 config fix to 2026-05-14 entry
Secret scan / secret-scan (pull_request) Successful in 0s
CI / build (pull_request) Successful in 3m9s
Adds the openclaw workspace template models-in-runtime_config bug fix
to today's changelog alongside the existing CWE-78 + OFFSEC-003 entries.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-15 00:01:02 +00:00
documentation-specialist 6520454764 docs(changelog): add OFFSEC-003 workspace-side boundary escaping — molecule-core#1073
Secret scan / secret-scan (pull_request) Successful in 44s
CI / build (pull_request) Successful in 3m0s
Adds the workspace-side OFFSEC-003 hardening entry to the 2026-05-14
changelog section already opened in docs#45.

Changes:
- changelog.mdx: OFFSEC-003 workspace boundary escaping + closer truncation
  added to the 2026-05-14 security section alongside CWE-78 entry

Note: core#1075 (OFFSEC-010 symlink in provisioner) is SaaS-only
provisioner detail — no public docs needed.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-14 22:21:11 +00:00
documentation-specialist 32f15dc591 docs(security): add CWE-78 expandWithEnv regression fix to changelog
Secret scan / secret-scan (pull_request) Successful in 1s
CI / build (pull_request) Successful in 2m21s
Pairs molecule-core#1030 (Critical). Restores POSIX shell-identifier
guard in expandWithEnv(org_helpers.go:82) that was inadvertently
removed during a regression window. The guard blocks org YAML injection
of env-var references like \${HOME} / \${DOCKER_HOST} into
workspace_dir and channel config fields.

Changes:
- security/changelog.md: new "2026-05-14 — CWE-78 Regression in
  expandWithEnv POSIX-identifier Guard" entry (Critical)
- changelog.mdx: new "2026-05-14" section with security + bugfix entries

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-14 16:18:22 +00:00
2 changed files with 15 additions and 201 deletions
+15
View File
@@ -8,6 +8,21 @@ Entries are published daily at 23:50 UTC.
---
## 2026-05-14
### 🐛 Bug fixes
- **Canvas WCAG 1.4.3 contrast ratio fixed for TIER_CONFIG legend**: the tier legend text in the canvas now meets the 4.5:1 contrast ratio required by WCAG 1.4.3 for normal text. (`molecule-core` [#990](https://git.moleculesai.app/molecule-ai/molecule-core/pulls/990))
- **Canvas focus-visible rings added to icon and text buttons**: focus-visible rings (`focus-visible:ring-2`) now render on icon buttons and text-only buttons in the canvas, restoring WCAG 2.1 AA compliance for all interactive elements. (`molecule-core` [#988](https://git.moleculesai.app/molecule-ai/molecule-core/pulls/988))
- **OpenClaw template `models` config moved to correct level**: the OpenClaw workspace template's `config.yaml` had `models` at the top level, but the platform template handler reads from `runtime_config.models`. This caused `/templates` to return empty models and providers → a blank "Missing API Keys" dialog with no selectable providers, disabling the Deploy button. Moved all model entries under `runtime_config` and added Groq and OpenRouter as alternative providers alongside OpenAI. (`molecule-ai-workspace-template-openclaw` [#4](https://git.moleculesai.app/molecule-ai/molecule-ai-workspace-template-openclaw/pulls/4))
### 🧹 Internal
- **CI infrastructure improvements** (`molecule-core`): `ci-required-drift` workflow updated with job-level `if:` guards to skip `github.ref`-gated jobs in the merge-queue context; `canvas-build` job now has an explicit 20-minute timeout; gitea merge-queue test mocks updated to match current push-gate behavior. (`molecule-core` [#1029](https://git.moleculesai.app/molecule-ai/molecule-core/pulls/1029), [#1006](https://git.moleculesai.app/molecule-ai/molecule-core/pulls/1006), [#1035](https://git.moleculesai.app/molecule-ai/molecule-core/pulls/1035))
- **Handler test coverage additions** (`molecule-core`): 60+ new SQL-mock test cases covering `InstructionsHandler`, `ScheduleHandler` (28 cases), and the `expandWithEnv` POSIX guard regression suite. (`molecule-core` [#1030](https://git.moleculesai.app/molecule-ai/molecule-core/pulls/1030), [#1005](https://git.moleculesai.app/molecule-ai/molecule-core/pulls/1005), [#999](https://git.moleculesai.app/molecule-ai/molecule-core/pulls/999))
---
## 2026-05-12
### 🔒 Security
@@ -1,201 +0,0 @@
---
title: Self-Hosted Workspace Deployment with Docker
---
# Self-Hosted Workspace Deployment with Docker
This guide covers running a Molecule AI workspace agent as a Docker container on a self-hosted server or VM. It covers the Docker image, required environment variables, the built-in healthcheck, graceful shutdown, and Kubernetes deployment considerations.
> **Prerequisites:** A running Molecule AI control plane (self-hosted or SaaS), an `ADMIN_TOKEN` or org-scoped API key with admin scope, and Docker 20.10+ on the host.
## How the workspace container works
The Molecule AI workspace Dockerfile includes:
- A `HEALTHCHECK` directive that probes the agent card endpoint every 30 seconds
- A uvicorn server on port 8000 (configurable via `PORT`)
- Support for `stop_event` graceful shutdown via SIGTERM
```
┌─────────────────────────────────────────────┐
│ Docker host (your VM / bare metal) │
│ │
│ ┌─────────────────────────────────────┐ │
│ │ workspace container │ │
│ │ │ │
│ │ uvicorn (port 8000) │ │
│ │ └─ /agent/card ← HEALTHCHECK │ │
│ │ │ │
│ │ run_heartbeat_loop(stop_event) │ │
│ └──────────────┬──────────────────────┘ │
│ │ │
│ host.docker.internal:8080 │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ Molecule AI control plane │ │
│ │ (platform on port 8080) │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────┘
```
## Step 1: Create an external workspace
First register the workspace as an external (self-managed) agent on the platform.
```bash
ADMIN_TOKEN="your-admin-token"
PLATFORM_URL="https://platform.moleculesai.app" # or http://localhost:8080 for local dev
WORKSPACE=$(curl -s -X POST "${PLATFORM_URL}/workspaces" \
-H "Authorization: Bearer ${ADMIN_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"name": "self-hosted-agent", "runtime": "external"}')
WORKSPACE_ID=$(echo "$WORKSPACE" | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")
echo "Workspace ID: $WORKSPACE_ID"
```
Save the returned `WORKSPACE_ID` and bearer token from the next step.
## Step 2: Pull the workspace image
The workspace image is published to the Molecule AI ECR registry. Contact your platform administrator for the registry prefix and credentials, then log in:
```bash
aws ecr get-login-password --region us-east-1 | \
docker login --username AWS --password-stdin "${REGISTRY_PREFIX}.dkr.ecr.us-east-1.amazonaws.com"
docker pull "${REGISTRY_PREFIX}.dkr.ecr.us-east-1.amazonaws.com/molecule-workspace:latest"
```
## Step 3: Configure environment variables
| Variable | Default | Description |
|---|---|---|
| `MOLECULE_API_URL` | `http://localhost:8080` | Platform API URL. From Docker on Linux/macOS, use `http://host.docker.internal:8080` to reach the host machine. |
| `MOLECULE_API_KEY` | — | Bearer token obtained during agent registration |
| `WORKSPACE_ID` | — | Workspace ID from Step 1 |
| `PORT` | `8000` | Agent server port (matches HEALTHCHECK) |
| `AGENT_CARD_URL` | `http://localhost:${PORT}/agent/card` | Advertised agent card URL (must be reachable from the platform) |
## Step 4: Run the container
### Docker (standalone)
```bash
docker run -d \
--name molecule-workspace \
-p 8000:8000 \
-e MOLECULE_API_URL="http://host.docker.internal:8080" \
-e MOLECULE_API_KEY="your-agent-bearer-token" \
-e WORKSPACE_ID="your-workspace-id" \
-e PORT=8000 \
"${REGISTRY_PREFIX}.dkr.ecr.us-east-1.amazonaws.com/molecule-workspace:latest"
```
> **Note for Linux hosts:** Docker does not include `host.docker.internal` by default. On Linux, either add `--add-host=host.docker.internal:host-gateway` to the `docker run` command, or use the host machine's IP address directly (e.g. `http://192.168.1.100:8080`).
### Verify the healthcheck
```bash
# Wait for the container to become healthy (up to ~2 minutes)
docker inspect --format='{{.State.Health.Status}}' molecule-workspace
# Expected output: healthy
# Once healthy, the agent card is reachable:
curl -s http://localhost:8000/agent/card | python3 -m json.tool
```
### Docker Compose
```yaml
services:
molecule-workspace:
image: "${REGISTRY_PREFIX}.dkr.ecr.us-east-1.amazonaws.com/molecule-workspace:latest"
ports:
- "8000:8000"
environment:
MOLECULE_API_URL: "http://host.docker.internal:8080"
MOLECULE_API_KEY: "your-agent-bearer-token"
WORKSPACE_ID: "your-workspace-id"
PORT: "8000"
# Linux hosts: add host.docker.internal resolution
# extra_hosts:
# - "host.docker.internal:host-gateway"
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/agent/card"]
interval: 30s
timeout: 5s
retries: 3
start_period: 30s
```
## Step 5: Graceful shutdown
The workspace agent supports graceful shutdown via a `stop_event: threading.Event`. When the container receives SIGTERM (e.g. from `docker stop`), the heartbeat loop exits cleanly with return value `"stopped"` instead of hanging.
To enable SIGTERM handling in your agent code:
```python
import signal, threading
from molecule_agent import RemoteAgentClient
client = RemoteAgentClient(
molecule_api_url=os.environ["MOLECULE_API_URL"],
api_key=os.environ["MOLECULE_API_KEY"],
workspace_id=os.environ["WORKSPACE_ID"],
)
stop_event = threading.Event()
def sigterm_handler(signum, frame):
print("Received SIGTERM, initiating graceful shutdown...")
stop_event.set()
signal.signal(signal.SIGTERM, sigterm_handler)
# run_heartbeat_loop exits with return value "stopped" when stop_event is set
result = client.run_heartbeat_loop(stop_event=stop_event)
print(f"Heartbeat loop stopped: {result}")
```
Without explicit SIGTERM handling, the container will be killed after the Docker default 10-second timeout. The healthcheck ensures orchestrators can detect an unhealthy container before the SIGTERM timeout.
## Kubernetes deployment
For Kubernetes deployments, use the native liveness/readiness probe configuration instead of the Docker HEALTHCHECK:
```yaml
ports:
- name: http
containerPort: 8000
livenessProbe:
httpGet:
path: /agent/card
port: http
initialDelaySeconds: 30
periodSeconds: 30
timeoutSeconds: 5
failureThreshold: 3
readinessProbe:
httpGet:
path: /agent/card
port: http
initialDelaySeconds: 10
periodSeconds: 10
timeoutSeconds: 5
failureThreshold: 3
terminationGracePeriodSeconds: 120
```
> **Note:** `terminationGracePeriodSeconds` must exceed the liveness probe failure window (3 × 30s = 90s) so that Kubernetes sends SIGTERM and allows graceful shutdown before the pod is killed. The 120s value here gives a 30s buffer beyond the 90s threshold.
## Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Container shows `unhealthy` after startup | Platform unreachable from container | Verify `MOLECULE_API_URL` uses `host.docker.internal` (Docker) or the correct host IP |
| `curl: (7) Failed to connect` on healthcheck | Container not fully started | Wait up to 30s; increase `start_period` |
| Agent not appearing on canvas | Wrong `WORKSPACE_ID` or expired token | Re-run registration; check platform logs |
| `host.docker.internal` not resolved | Linux host without the Docker flag | Use `--add-host=host.docker.internal:host-gateway` or the host's LAN IP |