# How it works

How Languid keeps agents on atproto, for developers who want to know what's underneath before trusting it or building on it. The full design is in [design.md](https://tangled.org/cameron.stream/languid/blob/main/docs/design.md), and the reasons behind it are in [decisions.md](https://tangled.org/cameron.stream/languid/blob/main/docs/decisions.md).

## The pieces

```
 you ── pi · browser · Discord ──▶ Languid service ──▶ model provider
                                    │           ▲
                      reads, writes │           │ long poll
                                    ▼           │
                         your space (PDS)    runner on your computer
```

- **The agent is an account.** Each agent has its own DID and handle (`scout.languid.ai`). It isn't a row in someone's database.
- **Its state is records in a Space.** Memory blocks, threads, messages, tool calls and results, and config are `ai.languid.*` records in a private [atproto Space](https://atproto.com/blog/atproto-spaces-alpha). The space is owned by your own account, and you and the agent are its only members. See [Records](/docs/records).
- **The service runs turns.** It's the only reader and writer of agent records. On every model request, it builds the context from the records, calls the model, and writes each turn back as records. Clients never call a model or assemble context themselves.
- **Tools run on your computers.** A runner on each computer connects out to the service, picks up the calls assigned to it, and sends back results. Each call runs on exactly one computer, at most once. See [Computers](/docs/computers).

[A turn, step by step](/docs/turn) follows one message through all of this, with a map of the machines.

## What that buys you

- **Every client is the same agent.** pi, the browser and Discord all read the same records, so a thread started in one can be picked up in another.
- **Records are the source of truth.** Anything else, including pi's session files and the service's memory, is a cache that can be rebuilt from the records.
- **Threads run in parallel.** Each thread has one turn at a time, and different threads run at the same time.
- **You can leave.** Your agents' data is in a space under your own DID, in a standard format. Languid is AGPL and [self-hostable](/docs/self-host) end to end: the PDS, the service, inference and runners.

## Privacy

To see where people get stuck, Languid notes the steps you reach while getting started, such as signing in and making your first agent, along with any errors on the way. Your agents can also send bug reports, which ask for your yes first. None of this includes your messages.

If you turn on **Share usage with Languid** under About you, Languid also notes which pages you open each day and any errors your browser hits. It stays off until you turn it on, and you can turn it off at any time.

## Where it's going

Spaces are still in alpha, so the service runs its own Spaces PDS at `pds.languid.ai`. When the Spaces beta arrives, you'll be able to use an existing atproto account, such as your Bluesky one. What's left to build is on the [roadmap](https://tangled.org/cameron.stream/languid/blob/main/ROADMAP.md).
