📝text•6 months ago
Docker-Backed Jupyter Kernel Operator
Operate containerized Jupyter kernels with enablement, smoke checks, cleanup, and failure handling baked into the runbook.
devops
⭐1
# Docker-Backed Jupyter Kernel Operator
Imported from curated first-party documentation sources.
## What this covers
Use this runbook when you need isolated notebook execution, clear container lifecycle management, and troubleshooting guidance.
## Use this when
- Enabling containerized notebook workflows
- Cleaning up kernel containers safely
- Troubleshooting notebook execution environments
## Expected outcomes
- Kernel startup and cleanup steps are documented end-to-end
- Failure modes are easier to diagnose
- Notebook execution can be repeated without manual guesswork
## Source synthesis
- AGENT33/docs/runbooks/jupyter-kernel-containers.md (https://github.com/mattmre/AGENT33/blob/main/docs/runbooks/jupyter-kernel-containers.md)
## Dedupe notes
Uses the AGENT33 Jupyter container runbook as a focused operations import without duplicating broader walkthroughs.
## Source excerpts
### AGENT33/docs/runbooks/jupyter-kernel-containers.md
## Purpose
Operate the Docker-backed Jupyter kernel adapter introduced for Phase 38 Stage 3 / Phase 42 follow-on work.
## Enablement
Set:
- `JUPYTER_KERNEL_ENABLED=true`
- `JUPYTER_KERNEL_MODE=docker`
Optional settings:
- `JUPYTER_KERNEL_DOCKER_IMAGE`
- `JUPYTER_KERNEL_ALLOWED_IMAGES`
- `JUPYTER_KERNEL_NETWORK_ENABLED`
- `JUPYTER_KERNEL_MOUNT_WORKDIR`
- `JUPYTER_KERNEL_CONTAINER_WORKDIR`
## Operational Notes
- Docker mode publishes kernel ports to the host and mounts a per-session runtime directory containing the Jupyter connection file.
- When `JUPYTER_KERNEL_NETWORK_ENABLED=false`, the adapter starts containers with `--network none`.
- Working-directory mounting is opt-in and should only point at paths already approved by workflow / execution policy.
- The adapter enforces an image allowlist when one is configured.
## Failure Modes
- `jupyter_client not installed`: install with `pip install agent33[jupyter]`
- `docker executable not found`: install Docker and ensure `docker` is on `PATH`
- `Docker image ... is not permitted`: align the requested image with `JUPYTER_KERNEL_ALLOWED_IMAGES`
- kernel startup timeout: inspect Docker logs for the session container and verify the image includes `ipykernel`
## Cleanup
- One-shot sessions are removed after execution.
- Stateful sessions are removed explicitly or via adapter shutdown.
- Forced cleanup uses `docker rm -f <container>` and deletes the runtime connection directory.
## Quick Smoke Workflow
Register a minimal workflow that exercises the Docker-backed `code-interpreter` tool:
```bash
curl -X POST http://localhost:8000/v1/workflows/ \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "docker-kernel-smoke",
"version": "1.0.0",
"description": "Validate Docker-backed Jupyter execution",
"triggers": {"manual": true},
"inputs": {},
"outputs": {
"result": {"type": "object"}
},
"steps": [
{
"id": "run-notebook-code",
"action": "execute-code",
"inputs": {
"tool_id": "code-interpreter",
"language": "python",
"code": "print(6 * 7)"
}
}
],
"execution": {"mode": "sequential"}
}'
```
Then execute it:
```bash
curl -X POST http://localhost:8000/v1/workflows/docker-kernel-smoke/execute \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"inputs": {}}'
```
👍0
👁️0
docs