# Sausage

You can see how the sausage is made.

Sausage is a world of small programs ("actors") that you grow by talking to
it. Each actor is a WASI program with stdin and stdout. Actors send each other
JSON messages, one per line, through a broker. The agent is an actor too: it
writes new actors in Rust, builds them, tests them, starts them, and can
change its own code.

## Start

You need [Nix](https://nixos.org/download) with flakes.

```sh
nix run -- init     # creates ./world and builds the agent (a few minutes)
nix run -- run      # starts the world and a console
```

`init` asks for the API shape (`openai-responses` or `anthropic-messages`),
the base URL, the model, and the token. It reads `SAUSAGE_API`,
`SAUSAGE_BASE_URL`, `SAUSAGE_MODEL`, and `SAUSAGE_API_TOKEN` first. The
values go to `world/actor/agent/data/config.json`. Both commands take another
folder as an argument, for example `nix run -- run my-world`.

To keep a world on the newest version, run it in a loop:

```sh
nix run .#loop -- my-world            # or .#loop-internal (Gitea on the LAN)
```

The loop runs `nix run --refresh git+ssh://…/surma/sausage -- run my-world`.
When the host crashes or an actor sends `@broker {"type":"exit"}`, the loop
fetches the newest commit and starts it again. `/quit` ends the loop.

In the console:

```text
write an actor "notes" that stores notes, and start it   → text to the agent
@notes {"type":"add","text":"milk"}                      → a JSON message to an actor
@agent hello                                             → text to an actor
/quit
```

## The world folder

The folder is the source of truth. Every actor lives in `world/actor/<id>/`:

```text
actor.wasm     the current version
actor.json     installed version, running, subscriptions
source/        the source of the current version
public/        files that the actor publishes
data/          the actor's state
stderr.log     what the actor and the broker write about it
versions/<n>/  every installed version: actor.wasm, source/, meta.json
```

To add or replace an actor by hand, put an `actor.wasm` (and its `source/`,
with the tests in `source/tests/`) into its folder. Then restart the world or
send `@broker {"type":"scan"}`. The broker tests the file before it uses it.
If the tests fail, the old version keeps running, and `stderr.log` says why.

## More

- [PROTOCOL.md](PROTOCOL.md): messages, the filesystem, the broker, `cargo`.
  Read this to write an actor in any language.
- [`sdk/`](sdk/): `sausage-actor`, the SDK for Rust actors.
- [`examples/notes`](examples/notes): a small actor with a test.
- [AGENTS.md](AGENTS.md): how to work on Sausage itself.