Docs / Start

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

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.

PlatformArchive
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:

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#

Found something out of date? Open an issue or edit this page.