Metadata-Version: 2.4
Name: openchat-server
Version: 0.5.3
Summary: A tiny open-source TCP chat server with channels and roles for OpenChat.
Author: OpenChat
License: MIT
Keywords: chat,irc,terminal,server
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: certifi>=2023.0.0
Requires-Dist: prompt_toolkit>=3.0
Dynamic: license-file

# openchat-server

The open-source server behind [OpenChat](https://pypi.org/project/open-chat-client) — a
tiny terminal chat tool. Run one of these and anyone can join it from the
`chat` client.

It's deliberately small. Logins are verified against the registry website
(central accounts), and all state — roles, channels, messages, DMs, webhooks,
bans — lives in a single **SQLite** database.

## Manage servers the easy way

```bash
pip install open-chat-server
openchatserver
```

`openchatserver` opens a management screen where you can **create and name
servers, register them on the site, and start/stop them in the background** —
no long command to remember and no terminal to keep open. Servers you create are
remembered in `~/.openchat-server/`; each runs detached until you stop it from
the same screen.

## Or run one directly

```bash
openchat-server --name "my server" --port 6767
```

Or without installing:

```bash
python -m openchat_server --name "my server" --port 6767
```

Options:

| flag | default | meaning |
|------|---------|---------|
| `--host` | `0.0.0.0` | interface to bind |
| `--port` | `6767` | port to listen on |
| `--name` | `openchat` | display name shown to clients |
| `--data` | `~/.openchat-server/data.db` | SQLite database (stable path, survives restarts) |
| `--auth-url` | `https://chat.sushii.dev` | website that issues/verifies login tokens |
| `--webhook-port` | `6768` | HTTP port for bot webhooks (`0` disables) |
| `--registry` / `--registry-id` / `--registry-secret` | — | report member counts to a registry (see below) |

The machine's IP + port is the address people connect to — they enter it (e.g.
`203.0.113.5:6767`) in the client's **Join a community** screen. To let others
reach you across the internet you'll need to forward that port on your router
(or run it on a VPS). To share a friendly name instead of an IP, register the
address (the `openchatserver` manager does this) and people can join by that id.

## Roles

- The **first** account to connect becomes the **owner**.
- Everyone else joins as a **member**.
- Owners and admins can create/delete channels, assign roles, and kick users.

## History & direct messages

The server keeps the most recent messages for each channel and each DM thread
(200 each by default, see `MAX_HISTORY` in `store.py`) in the data file, so
clients get scrollback when they connect and DMs reach people who were offline.

## Bots (webhooks)

The server runs a small HTTP endpoint (default port `6768`) for incoming
webhooks. An admin creates one from the client with `/webhook create <name>`,
which prints a URL. Anyone can then post as a bot:

```bash
curl -X POST -H 'Content-Type: application/json' \
  -d '{"text":"hello","username":"mybot"}' \
  http://SERVER_HOST:6768/hooks/<id>/<token>
```

## Reporting member counts to a registry

If you registered your community on an OpenChat registry site, it gave you a
write secret. Pass it and the server will report live member/online counts every
30s (addresses stay private on the registry — only counts and description show):

```bash
openchat-server --name "my server" \
  --registry https://chat.sushii.dev --registry-id my-club \
  --registry-secret THE_SECRET
```

## Protocol

Newline-delimited JSON over TCP. See `openchat_server/protocol.py`. It's simple
enough to talk to with `nc` if you're curious.

## Publishing

Releases go to PyPI as `open-chat-server` automatically via
[`.github/workflows/publish.yml`](.github/workflows/publish.yml) (PyPI Trusted
Publishing). Bump `version` in `pyproject.toml`, then:

```bash
git tag v0.1.0
git push origin v0.1.0
```

See the comments at the top of the workflow for the one-time trusted-publisher
setup on PyPI.

MIT licensed.
