Goss is an Apache-2.0 licensed, Go-based YAML test runner that validates the configuration of a server or container and can expose the result as a health endpoint, built for DevOps engineers and SREs who need fast, repeatable checks on Linux hosts, Docker containers, and Kubernetes workloads.

What it is

Goss lives in the infrastructure-as-code and DevOps tooling ecosystem, alongside the CI pipelines and monitoring systems that consume its output. It is a YAML-based alternative to serverspec, the Ruby tool that validates a server's configuration through a domain-specific language. Where serverspec asks the operator to write every assertion by hand, Goss starts from the live system: it inspects the current state of a machine and derives a test suite from it, so the known-good configuration is captured first and asserted later.

The concrete problem it solves is configuration drift and untested provisioning. After a machine is built, an image is baked, or a container starts, something has to confirm that the sshd configuration, the listening ports, the packages, and the services are still what they were meant to be. Goss turns that verification into a file that can be executed on demand, waited on until it passes, or served as an HTTP health endpoint for external monitors. Small to medium suites are near instantaneous, and the whole tool ships as a single small binary, which keeps it usable inside restricted hosts and container images where a full test framework would not fit.

Key capabilities

• YAML test suites generated from current system state using the add command, so assertions begin as a snapshot of a working machine.
• Three execution modes for one suite: run it once, wait on it with retries, or serve it as a health endpoint.
• dgoss wrapper for testing containers, with additional user-submitted wrappers kgoss for Kubernetes and dcgoss for Docker Compose.
• Distribution as a release tarball, for example goss_0.4.10_linux_x86_64.tar.gz from the GitHub releases page, extracted directly to /usr/local/bin/goss.
• Build from source with make build, or with goreleaser using goreleaser build, --single-target, --clean, and --snapshot flags.
• Published container image for running Goss inside containerized environments.
• Health endpoint output aimed at monitoring tooling, reflected in the project's Nagios and Sensu topics.

Who uses it and how

• CI pipelines that validate a freshly provisioned host or image; the README warns explicitly that pipelines should pin a specific release tag such as v0.4.10 rather than download latest, because the latest release may behave unexpectedly.
• Container workflows using the dgoss wrapper to assert the contents and behaviour of a built image before it is promoted.
• Kubernetes and Docker Compose teams using kgoss and dcgoss for container ordering and healthcheck examples, as described in the maintainer's blog post on simplified health checks.
• Monitoring-driven operations teams that pull Goss output into existing alerting through the health endpoint rather than authoring separate checks.
• Infrastructure-as-code practitioners who keep the YAML suite in version control next to provisioning code, so a machine build and its acceptance criteria travel together.

Getting started

The documented path is a manual install from a pinned GitHub release, streaming the tarball into /usr/local/bin/goss and optionally the dgoss wrapper into the same directory. Building from source is also supported through make build or goreleaser.

How it compares

The README positions Goss directly as a YAML-based alternative to serverspec, which is the closest comparable tool named in the project's own facts. The practical contrast is authoring model and footprint: Goss generates a starting suite from the machine's current state and ships as a single small Go binary, while serverspec expects assertions to be written by hand in a Ruby-based test framework.

When to use it — and when not to

A self-hoster needs to run a binary and keep a YAML file under version control; nothing in the facts indicates a required database, object store, or SMTP dependency, and suites can simply be executed, waited on, or served over HTTP. It is the wrong choice for anyone expecting configuration management or remediation, because Goss validates state rather than converging it, and pipelines that ignore the warning about latest will get unpredictable behaviour. The README itself is brief and defers heavily to documentation hosted on Read the Docs, so teams wanting everything explained in-repo should expect to follow external links, and the tracker carries 57 open issues at the time of writing.

user:
  sshd:
    title: UID must be between 50-100, GID doesn't matter. home is flexible
    meta:
      desc: Ensure sshd is enabled and running since it's needed for system management
      sev: 5
    exists: true
    uid:
      # Validate that UID is between 50 and 100
      and:
        gt: 50
        lt: 100
    home:
      # Home can be any of the following
      or:
      - /var/empty/sshd
      - /var/run/sshd

package:
  kernel:
    installed: true
    versions:
      # Must have 3 kernels and none of them can be 4.4.0
      and:
      - have-len: 3
      - not:
          contain-element: 4.4.0

  # Loaded from --vars YAML/JSON file
  {{.Va