A kernel connection file is a small JSON file Jupyter gives a kernel at startup. It lists the ports to use and a key for signing messages, so other users on the machine cannot send code to that kernel. Treat it as a credential: anyone who can read it can talk to the kernel.
Definition
The Jupyter client documentation defines a kernel as a program that runs and introspects the user's code. IPython includes a kernel for Python, and others exist for other languages. When a kernel starts, it receives either a connection file or a registration file, a newer handshake based approach.
The classic connection file holds a JSON dictionary with the transport, the IP address, five ports for the ZeroMQ channels, a signature scheme and a key. New ports are chosen at random for each kernel started. The documentation notes that the file is accessible only to the current user.
What the key is for
The signature scheme, such as hmac-sha256, and the key are used to sign messages. The documentation states the purpose directly: so that other users on the system cannot send code to run in this kernel.
That is the core of the design. The ports are local network sockets, and on a shared machine other accounts could try to connect to them. Without a valid signature, their messages are not accepted.
When transport encryption is on
The documentation says that when transport encryption is enabled, two extra fields hold CurveZMQ keys, a public and a secret one. The kernel applies them to its sockets before binding. Those too are sensitive.
Practical consequences
| Situation | What to do |
|---|---|
| Shared login node or lab server | Keep runtime directories private to each user |
| Copying a connection file into a ticket or chat | Do not, it is a credential for a live kernel |
| Port forwarding a kernel for remote work | Forward only over an authenticated tunnel, and stop the kernel afterwards |
| Containers with a mounted runtime directory | Mount only what is needed, with correct permissions |
| Debug logs | Check they do not print the file contents |
A short check on a shared host
- Find where your Jupyter runtime files live and list their permissions.
- Confirm other users cannot read them.
- List running kernels and stop ones you no longer need.
- Make sure backup and sync tools do not copy runtime folders to shared storage.
The same lesson shows up elsewhere in the stack. See /resources/blog/jupyter-execute-permission-means-arbitrary-code-authorizer-explained for why a connection to a kernel counts as code execution.
Safeguard does not scan for secrets. Use another tool for files like these. For project dependencies, try the free scan at gold.safeguard.sh/scan.
Quick check
Why do kernels choose random ports?
New ports are chosen at random for each kernel started, as the client documentation describes.
Is the connection file safe to share for debugging?
No. It contains the signing key and endpoints for a live kernel.
Sources
- Making kernels for Jupyter, jupyter_client documentation, fetched 19 October 2026.
Last reviewed: 19 October 2026.
