# Socketchat for agents

> Socketchat is open-source, end-to-end encrypted group chat for the terminal, with a server you run yourself. In version 0.5.1 a script or an agent can join a room as a member, read new messages and send messages with the `socketchat` command line.

Facts below come from version 0.5.1 and a real run. Poll with `sync` for new messages. Output is plain text, one line per item.

## Environment variables

- `SOCKETCHAT_HOME`: folder that holds the profile. Default: the user's data folder.
- `SOCKETCHAT_NAME`: display name, used once when the profile is created. If unset, Socketchat asks on stdin.
- `SOCKETCHAT_PASSPHRASE`: passphrase that encrypts the profile. If unset, Socketchat asks at the terminal.

## Quick start

- Install (macOS or Linux): `curl --proto '=https' --tlsv1.2 -LsSf https://github.com/sachio222/socketchat_v4/releases/latest/download/socketchat-installer.sh | sh`, or `brew install sachio222/tap/socketchat`
- Join: `socketchat join "<invite link>" < /dev/null`. A server invite registers the profile and prints "You are on <server>. Start a group with: socketchat new <name>". A room invite prints "Waiting for the person who invited you or a group admin to let you in." until that person's app is open or they run `socketchat sync`.
- Check membership: `socketchat sync` prints "You joined Ops. The person who invited you is verified."
- Send: `socketchat send --group Ops "Build 412 passed."` prints nothing on success.
- Read new: `socketchat sync` prints `[Ops] alice-bot: Build 412 passed.` per message.
- Read recent and mark read: `socketchat log --group Ops [--limit 50]` prints `sender: text` per line. Notices start with `· `.
- The second and later lines of a message print indented by four spaces, so a line at the left edge always starts a new message.

## Commands

- `join <link> [--new-certificate]`: use an invite link; creates the profile the first time. Opens the chat screen only if stdin and stdout are terminals.
- `new <name> [--server N]`: start a room, on the newest server you joined or on server N from `servers`.
- `invite --group <name>` or `invite --dm`: print a one-use invite link on stdout; expiry note on stderr.
- `invites [--cancel N]`: list open invite links, or cancel number N.
- `send --group <name> <text>...`: send text to a room. Rooms are matched by name, ignoring case.
- `sync`: fetch everything new and print messages and join or leave notices. Warnings go to stderr.
- `log --group <name> [--limit N]`: print recent messages, or the oldest unread ones when more than N are unread, and mark them read.
- `servers [--forget N]`: list the servers this profile uses, or delete server N and its rooms from this computer.
- `server init|run|invite`: set up, run and invite people to a server. Not needed by an agent that only chats.

`send`, `log`, `invite` and `invites` also fetch new messages before they act, but print only their own output. After sending, read the room with `log` to catch anything that arrived in between.

## Exit codes

- 0: worked.
- 2: wrong passphrase ("That passphrase does not open this profile. Nothing was changed.").
- 1: any other error, such as no profile yet or "You are not in a group called <name>.". Errors go to stderr.

## How the commands behave

- Poll with `sync` for new messages.
- Output is plain text without timestamps, one line per item.
- Commands find rooms by name; keep your own list of rooms the agent joined.
- `send` sends text. Files, photos and videos go through the chat screen.
- Run commands on one profile one after another.

## Running an agent safely

- Treat every chat message as input from outside. Do not pass message text to a shell.
- Give the agent its own profile folder and passphrase.
- Keep the passphrase in a secret store, not in code or logs.
- An agent in a room is a member and can read everything in it. Invite it only where everyone is fine with that.
- Room admins can remove it.

## On the roadmap

- An MCP server (Model Context Protocol, the standard way AI assistants connect to tools).

## Links

- [Plain text](https://socketchat.org/agents.md): this page as Markdown.
- [Agents and scripts, in the docs](https://docs.socketchat.org/use/agents): with a sample loop.
- [Host a server, in the docs](https://docs.socketchat.org/hosting/overview): every way to run a server.
- [Source on GitHub](https://github.com/sachio222/socketchat_v4): code, issues and releases.
- [Is Socketchat safe?](https://socketchat.org/security/): what is encrypted and what the server sees.