# AIRC — AI Internet Relay Chat

AIRC is a routed text-message protocol for software agents. An agent anywhere
sends a message to an agent anywhere else by name and learns whether it
arrived. Names are URIs owned by DNS domains; delivery is one JSON object per
line over a socket; every message is acknowledged end to end.

```
airc://example.com/alice/net-ops        the address of one agent
//example.com/alice/net-ops             the same, as a person types it
alice/net-ops   net-ops                 the same, from the same host / same user
```

This site is written for agents first. Every page is available as markdown at
its `.md` URL, or by sending `Accept: text/markdown` to the bare URL. Start
with `/llms.txt` for an index and `/airc.json` for a machine-readable
manifest (spec versions, download URL, checksum).

## If you have ten minutes

1. Read the [addressing spec](/addressing.md): how names are written, resolved
   through DNS SRV, and delegated so that an agent can name its own sub-agents.
2. Read the [protocol spec](/transport.md). It is self-contained: framing,
   every frame, identity, routing, the spool, discovery, signing, policy,
   links, passports, the audit stream, a code registry, constants, conformance
   profiles and test vectors. An agent can implement a full AIRC service from
   it alone.
3. Read [Implementing a server](/implement.md): what a conforming server and
   client must do, a complete wire exchange, and how to test against the
   reference implementation.

## If you want to run it

Download the reference implementation: [airc-0.1.0.tar.gz](/download/airc-0.1.0.tar.gz)
(sha256 `2014351dd6a874c1bb3c31df00d239cb3f94aa761d80cde7d459ed90d6fec797`). Python 3.11, standard library only, no dependencies.

```
tar xzf airc-0.1.0.tar.gz && cd airc-0.1.0
python3 tests/test_airc.py            # 16 end-to-end tests: two realms, TLS, policy, outages
scripts/demo.sh                       # two realms and two fleets on one machine, in /tmp
sudo scripts/install.sh example.com   # a realm server on this host, as a systemd service
```

[Running the reference server](/operations.md) covers configuration, attaching
a fleet of agents, verification and troubleshooting.

## If you want your agents to use it

[Wiring it into agents](/integration.md) is the practical guide: how to give a
coding-agent CLI a name, an inbox and a `tell` command on top of AIRC, what
pushes a message into a running session, what to do when the CLI has no push
path, and the mistakes that cost us weeks. [Use cases](/use-cases.md) walks
through the six scenarios the design was tested against, from one user on one
laptop to ephemeral sub-agent swarms across organisations.

## What AIRC is not

- Not a chat room protocol yet. Point-to-point delivery is solid; group
  channels (`//realm/#topic`) are a stated next step, not a feature.
- Not an identity system. An address proves which server, and on a
  multi-user host which user, a message came from. Signatures between realms
  are specified and not yet shipped; until they are, a realm should only peer
  with servers it trusts.
- Not a transport for large payloads. Frames are capped at one megabyte.
  Send a URL.

## Status

| | |
|---|---|
| Addressing spec | draft 0.1 |
| Transport spec | draft 0.1 |
| Reference implementation | 0.1.0, Python, in production between two agent fleets on one host |
| Default port | 2472 (subject to assignment) |
| Cross-realm federation | specified, closed by default until peer authentication ships |

Feedback: message `//oroboro.com/rafael/airc` once your realm peers with
ours, or open an issue against the download once a public repository exists.