Verification against workspace/main.py (b49ccff submodule) and
workspace-runtime.md (molecule-core main):
- PLATFORM_URL: MOLECULE_API_URL does not exist in the workspace
runtime; correct env var is PLATFORM_URL (workspace/main.py line 85).
Updated all occurrences: env vars table, Docker run, Docker Compose,
Python example, troubleshooting table.
- MOLECULE_API_KEY: not a real workspace env var; removed from Docker
run and Compose examples. The workspace runtime obtains its bearer
token from the platform automatically during registration.
- AGENT_CARD_URL: not a real env var; removed from env vars table.
The workspace generates its URL internally from HOSTNAME+port.
- Healthcheck endpoint: /agent/card is the MCP HTTP/SSE transport
path (separate binary). The A2A workspace agent serves the Agent
Card at /.well-known/agent-card.json (confirmed in boot_routes.py
and agent-card.md). Updated all healthcheck targets accordingly.
- Kubernetes terminationGracePeriodSeconds: 30s is incompatible with
the liveness probe (initialDelay=30 + 3×30s = ~120–150s to
register a failure). Changed to 120s and corrected the note to
reflect the actual failure window.
- Python example: replaced non-existent RemoteAgentClient with correct
HeartbeatLoop class from heartbeat.py.
- Graceful shutdown description: corrected to reflect uvicorn's actual
shutdown behavior (heartbeat.stop() in finally block) rather than
the non-existent stop_event pattern.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-15 05:09:07 +00:00
2 changed files with 40 additions and 42 deletions
| `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. |
| `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) |
| `PLATFORM_URL` | `http://localhost:8080` | Platform API URL. Inside a Docker container, use `http://host.docker.internal:8080` to reach the platform on the host machine. |
| `WORKSPACE_ID` | — | Workspace ID from Step 1 (required; no default) |
| `PORT` | `8000` | Agent server port. Must match `containerPort` in Kubernetes and the port mapped with `-p` in Docker. |
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.
When the container receives SIGTERM (e.g. from `docker stop` or Kubernetes pod deletion), the workspace's uvicorn server initiates graceful shutdown: the heartbeat loop stops, active A2A tasks are given a grace period to complete, and any snapshotable state is persisted before the process exits.
To enable SIGTERM handling in your agent code:
To integrate the heartbeat loop into custom agent code:
# SIGTERM is handled by the Docker runtime, which sends the signal to the
# workspace process. The workspace (via uvicorn) initiates graceful shutdown:
# the heartbeat loop is stopped, any active adapter tasks are cancelled, and
# in-flight A2A requests are given a grace period to complete.
#
# For custom integration with the heartbeat loop directly:
asyncdefmain():
heartbeat=HeartbeatLoop(
platform_url=os.environ["PLATFORM_URL"],
workspace_id=os.environ["WORKSPACE_ID"],
)
heartbeat.start()
try:
awaitasyncio.Event().wait()# keep running
finally:
awaitheartbeat.stop()
print("Heartbeat loop stopped.")
```
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.
The Docker `stop` command sends SIGTERM and waits up to 10 seconds by default before sending SIGKILL. The healthcheck ensures orchestrators detect an unhealthy container before the SIGTERM timeout.
## Kubernetes deployment
@@ -172,7 +169,7 @@ ports:
containerPort:8000
livenessProbe:
httpGet:
path:/agent/card
path:/.well-known/agent-card.json
port:http
initialDelaySeconds:30
periodSeconds:30
@@ -180,7 +177,7 @@ livenessProbe:
failureThreshold:3
readinessProbe:
httpGet:
path:/agent/card
path:/.well-known/agent-card.json
port:http
initialDelaySeconds:10
periodSeconds:10
@@ -189,13 +186,13 @@ readinessProbe:
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.
> **Note:** The Kubernetes `terminationGracePeriodSeconds` should exceed the liveness probe failure threshold so that the probe can register a failure before the pod is killed. With `periodSeconds: 30` and `failureThreshold: 3`, the probe does not register a failure until approximately 120–150s after the container becomes unhealthy. Set `terminationGracePeriodSeconds: 120` or higher.
## 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 |
| Container shows `unhealthy` after startup | Platform unreachable from container | Verify `PLATFORM_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 |
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
documentation-specialist
technical-writer