Docker-Backed Jupyter Kernel Operator

Operate containerized Jupyter kernels with enablement, smoke checks, cleanup, and failure handling baked into the runbook.

devops

Quality

👁️0 views

docs

>Payload Data

Editable Format

# 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

```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": {}}'
```

Source

https://github.com/mattmre/AGENT33/blob/main/docs/runbooks/jupyter-kernel-containers.md

SIMILAR_PROMPTS

SCANNING_SIMILARITY...