Getting started
Four commands to a working server: install, write a configuration, start it, and talk to it with nc. Install options, download verification and troubleshooting come after.
Quick start#
1. Install. With Go installed (the version in go.mod), this puts ghoti in $(go env GOPATH)/bin. Without Go, use a release archive.
$ go install github.com/dankomiocevic/ghoti/cmd/ghoti@latest
2. Declare two slots, a value and a counter, in a config.yaml in an empty directory:
$ mkdir ghoti-demo && cd ghoti-demo
$ printf 'slot_000:\n kind: simple_memory\nslot_001:\n kind: atomic\n' > config.yaml
3. Start the server from that directory. It listens on localhost:9090:
$ ghoti run
time=2026-11-20T06:48:59.858Z level=INFO msg="Starting server..."
4. Talk to it from a second terminal. Run nc localhost 9090 and type one command per line. Lines starting with > are what you type, and lines starting with < are the server's answers:
> w000hello
< v000hello
> r000
< v000hello
> r001
< v0011
> r001
< v0012
> r002
< e002005
> x000
< exxx001
w000hellowriteshelloto slot 000, and the server echoes the stored value.- Each read of the atomic slot 001 increments it.
- Slot 002 is not configured, so the answer is error
005(MISSING_SLOT). xis not a command, so the answer is001(PARSE_ERROR), withxxxin place of the slot number.
Send q to close the connection, and stop the server with Ctrl+C. Something different? See Troubleshooting.
Install options#
From a release archive#
Every release on the releases page has one archive per platform. The archive has the ghoti binary at its root, together with the README, the license and the changelog.
| Platform | Archive |
|---|---|
Linux (amd64, arm64, 386) | ghoti_<version>_linux_<arch>.tar.gz |
macOS (amd64, arm64) | ghoti_<version>_darwin_<arch>.tar.gz |
Windows (amd64, 386) | ghoti_<version>_windows_<arch>.zip |
Set VERSION to the release you want, without the leading v. The latest release is 0.3.0.
$ VERSION=0.3.0
$ curl -LO "https://github.com/dankomiocevic/ghoti/releases/download/v${VERSION}/ghoti_${VERSION}_linux_amd64.tar.gz"
$ tar -xzf "ghoti_${VERSION}_linux_amd64.tar.gz"
$ ./ghoti version
With go install#
Building from source needs the Go version listed in go.mod. The binary is installed into $(go env GOPATH)/bin, which must be on your PATH.
$ go install github.com/dankomiocevic/ghoti/cmd/ghoti@latest
Verifying a download#
Each release also ships:
- A
checksums.txtfile with the SHA-256 of every archive. - A Sigstore signature of the checksums file,
checksums.txt.sigstore.json. - An SPDX SBOM next to every archive,
<archive>.sbom.json. - A build provenance attestation for every archive.
Together they let you check that what you downloaded is what the Release workflow built from the tag.
Checksum#
The checksum catches a corrupted or tampered download:
$ curl -LO "https://github.com/dankomiocevic/ghoti/releases/download/v${VERSION}/checksums.txt"
$ sha256sum --ignore-missing -c checksums.txt
Signature#
The signature proves that checksums.txt itself was produced by this repository's Release workflow. It is a keyless Sigstore signature, so you check it against the workflow identity rather than against a key you have to trust. The signature, the certificate and the transparency log entry come together in one bundle file. The check needs cosign v3:
$ curl -LO "https://github.com/dankomiocevic/ghoti/releases/download/v${VERSION}/checksums.txt.sigstore.json"
$ cosign verify-blob \
--bundle checksums.txt.sigstore.json \
--certificate-identity-regexp '^https://github.com/dankomiocevic/ghoti/\.github/workflows/release\.yml@refs/tags/v' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
checksums.txt
Provenance#
The provenance attestation ties an archive to the exact commit and workflow run that built it. You check it with the GitHub CLI, and it doesn't need any other file:
$ gh attestation verify "ghoti_${VERSION}_linux_amd64.tar.gz" --repo dankomiocevic/ghoti
The SBOM lists the Go modules linked into the binary, for scanners like grype or for your own inventory.
Troubleshooting#
The server exits with Config File "config" Not Found#
Ghoti needs a configuration file. It looks for config.yaml in /etc/ghoti, then $HOME/.ghoti, then the current directory. If it finds none, it exits with status 1 rather than starting with defaults:
$ cd /tmp/demo && ghoti run
2026/11/20 06:49:31 ERROR Error loading config error="failed to load server config: Config File \"config\" Not Found in \"[/etc/ghoti /home/demo/.ghoti /tmp/demo]\""
$ echo $?
1
Run ghoti run from the directory that holds config.yaml, or put the file in one of the other two locations.
Every command answers exxx001#
You are probably connected with telnet. The default standard transport ends requests with a bare \n, but a telnet client sends \r\n, so reads fail with exxx001 and written values keep a trailing \r. Use nc, or set protocol: telnet in the configuration. See Transports.
A slot you configured answers e<slot>005#
Its definition is invalid, for example an unknown kind or a missing required option, and the server skipped it without a warning. Check the slot against the slot reference.
Next steps#
- Walk through coordination with two clients: build leader election on a lease slot.
- Read Concepts for how slots, connections and ownership behave.
- Pick slot kinds for your problem in the slot reference.
- Learn the exact rules your client must follow in Protocol.