Metadata-Version: 2.5
Name: colloq
Version: 0.5.1
Summary: Colloq — a shared workspace for teaching: one link, one live notebook, one assistant
Project-URL: Homepage, https://colloq.ru
Project-URL: Documentation, https://colloq.ru/docs/en/
Project-URL: Source, https://github.com/colloq-edu/colloq
Project-URL: Issues, https://github.com/colloq-edu/colloq/issues
Project-URL: Changelog, https://github.com/colloq-edu/colloq/blob/main/CHANGELOG.md
Author: Aleksandr Kalashnikov
License: MIT
Keywords: classroom,collaborative,education,jupyter,notebook,seminar,teaching
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Natural Language :: Russian
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: JavaScript
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Education
Classifier: Topic :: Education :: Computer Aided Instruction (CAI)
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# colloq

A shared workspace for teaching: one link, one live notebook, one assistant.
Everything runs on the teacher's own machine — no cloud, no third-party server.

```
pip install colloq
colloq start
```

The first command installs the program, the second brings a class up and opens
your browser. `Ctrl+C` saves and stops it.

Bare `colloq` starts nothing: it prints three lines about what lives here. A
class takes a port and opens a window, and that should not happen because
somebody typed a word at a guess — which is exactly why `jupyter` on its own
prints help too, and `jupyter lab` is what starts a server.

## What the machine needs

- **Docker** — the room's Python lives in it. The kernel image is built here,
  from the Dockerfile that shipped with the package.

That is all on macOS 14+ and on Linux x64/arm64 (glibc 2.28+): pip installs a
wheel for the platform with Node.js and the server's dependencies inside.

Elsewhere (macOS 13, Alpine, other architectures) pip installs the universal
wheel, which also needs **Node.js 22 or newer**. `colloq` finds it on its own,
including under nvm, fnm, volta and asdf, and says so in words if Node is
missing. On the first run it installs the server's dependencies once
(`npm install --omit=dev` inside its own directory) and says so out loud.

## Where your things live

State lives in `~/.colloq`, never inside the package: `.env`, the database,
`workspace/`, and any environments you create. Reinstalling or upgrading the
package leaves all of it alone. Point `COLLOQ_HOME` elsewhere to move it.

```
colloq start            # a class on this machine
colloq start --share    # the same, plus one public link for your students
colloq host <name>      # publish a running class under your own name
colloq status           # what is running here, no network calls
colloq doctor           # check everything before the lecture
colloq env new <name>   # a Python environment of your own
colloq stop             # end the class
```

`colloq --help` lists the rest; `colloq <command> --help` explains one.

## One link for the class

```
colloq start --share
```

starts the class, opens a quick Cloudflare tunnel and prints one block: the
link to give your students (`https://….trycloudflare.com/s/<class>`), or — if
there is no class yet — where to create one; the class links in the panel's
list already use the public address. The link lives while this terminal is
open, and `Ctrl+C` closes it together with the class. A quick tunnel gets a new
address on every start, so send the new link each time. Never share a link
with `/admin/` in it: that is a key to the panel.

The first `--share` downloads `cloudflared` if it is not installed: a pinned
release from `github.com/cloudflare/cloudflared`, checked against a pinned
SHA-256 before it is ever run, kept in `~/.colloq/bin`. `COLLOQ_CLOUDFLARED=/path`
uses your own file instead; `COLLOQ_CLOUDFLARED_DOWNLOAD=0` forbids the
download. macOS and Linux only; on Windows, use WSL 2.

Cloudflare addresses do not open from Russia. For students there, publish
through your own relay instead: `colloq start --host <name>` with the `RELAY_*`
lines in `~/.colloq/.env`.

## Boundaries

A class runs **on this computer, for your own students**: the server listens on
the loopback interface, and only an explicit `--share`, `--host` or
`colloq host` lets an audience in from outside. Each room's Python runs in a
hardened container of its own, cut off from your home network — and a class is
published only when that is true: if the kernels do not run one container per
room in Docker, publishing refuses and the class stays local. What remains
true is that the link is a door: anyone who has it runs code in a sandbox on
this computer. Keep it for your class; for an open audience, run the server
installation on a machine of its own.

## Where this comes from

The package is built from the Colloq repository with `make wheel`. Inside it is
the built application — server, frontend, CLI, kernel Dockerfile; the Python
code here is packaging and nothing more, finding Node and handing over control.

MIT.
