# Argos: a ninety-word readme, and the documentation lives in the compose file comments

> Argos is an open-source visual testing platform, and its readme is three links and a contributing note. Everything a new contributor needs is in the files instead: two environment files with around two dozen variables, four local services whose versions are chosen to match production, and a container image whose default build target produces nothing.

**argos-ci/argos** — The open source visual testing platform for teams and AI agents. Review the product, not just the code.

- Repository: https://github.com/argos-ci/argos
- Website: https://argos-ci.com
- Stars: 637 · Forks: 65
- Language: TypeScript
- License: MIT
- Published: 2026-09-13 · Updated: 2026-09-13 · Language: en
- Canonical page: https://hysenlabs.com/projects/argos-ci-argos

## The readme is three links, and the rest is in the files

The documentation surface is unusual and worth calibrating before you start. The readme is a title, one sentence saying this is an open-source visual testing platform for teams and agents, five links, a badge pointing at a hosted reference project, and a contributing note asking for a branch and a pull request against the main branch. There is no architecture overview, no install step, no configuration reference. All of that lives elsewhere: two environment example files at the root, comments inside the compose file explaining why each service version is what it is, and comments inside the Dockerfile explaining why its final stage exists. The example projects are not in this repository either; the readme sends you to a separate JavaScript repository for them. So the readme is a signpost and the files are the manual, which is fine for maintainers and slow for newcomers.

## Three committed scripts disable certificate checking and name public relay channels

The development scripts are where the security posture is easiest to misread. Three of them exist to receive webhooks from third-party services during local development, and each one disables TLS certificate verification for the process by setting that environment variable to zero before running a webhook relay, then forwards to a local address. The relay channel identifiers for three services are written directly into the script names' arguments in the repository. A fourth script does the same job with a tunnel service and a fixed free subdomain, and a fifth uses a payments CLI's built-in listener. The practical consequence is that anyone who reads the repository knows the public address to post to, and any developer running these scripts has turned off certificate checking for that process to receive the event. Useful for a webhook you control, unwise as a committed default.

## The container image builds to nothing unless you name the target

The Dockerfile ends with a stage that copies the built front-end output into an empty base image, and the comment above it is a warning rather than an explanation of a feature. Because that stage is last, it becomes the default target for a plain image build, so building without a target produces an empty artefact that looks like a successful build. The image build has to name the build stage explicitly, and the comment points at the workflow file where that flag is set. The same stage exists so continuous integration can extract the front-end output from the same cached build and upload it to an asset host rather than building it twice. Two other details in that file are worth noting: the base image is a very recent Node release on Debian, and a token needed by the build is mounted as a build secret rather than passed as an argument, which keeps it out of the image layers.

## Local versions run ahead of production on purpose, twice

The compose file carries two comments that are really release notes. The first says production runs a managed Postgres at a specific minor version while development and continuous integration are deliberately ahead on the next major, in order to validate an upgrade before it reaches the managed service. The second says the message broker is pinned to a specific version because the managed broker only offers that version, and because the floating tag has since resolved to a newer one that changes redelivery accounting. That second comment is the most useful line in the file: a queue version bump that changes how redeliveries are counted is exactly the kind of change that silently alters test results, and someone hit it and wrote it down. The cache service has no such pin, and its comment admits uncertainty about the exact patch level running in production, which is a fair thing to write and a fair thing for a reader to notice.

## Development Postgres trusts every connection, and the cache sits on an odd port

The four local services and their port mappings tell you what the application expects to talk to. Postgres is published on its default port and configured to trust any connection method, which removes authentication entirely for local work and is the right default for a development database nobody else can reach. The cache is mapped to a host port that is not its default, with the container port on the default and the host side a thousand higher, which is the kind of thing that breaks a copy-pasted connection string. A local DynamoDB image takes the next default port, and it runs entirely in memory with a shared database flag, so nothing survives a restart. Each service has a health check with a start period, and the broker mounts its enabled-plugins file from the repository rather than configuring plugins inline.

## One lint and format toolchain, four test entry points

The root manifest shows a repository that has consolidated rather than accumulated. Linting runs through one Rust-based linter with warnings promoted to errors, and formatting runs through its companion tool, which means there is no second linter or formatter configuration to reconcile. Dead dependency checking has its own configuration file, and type checking and static checks are delegated to the task runner across the workspace packages. Tests have four entry points rather than one: the default runner, a unit configuration, an integration configuration that points at a second file, and a browser automation suite with its own config file at the root. Two more files describe the project's own conventions, one for agent instructions and one for a skills lock, which tells you this repository is set up to be worked on by more than one kind of contributor.

## Two GitHub applications and two sets of webhook secrets

The environment example file is the closest thing this project has to a configuration reference, and its shape is a map of what the platform integrates with. The first surprise is two GitHub applications rather than one: a main development application and a second, lighter application, each with its own identifier, private key, webhook secret and a fallback webhook secret, which matches the two separate GitHub webhook relay scripts in the root manifest. After that come the credentials a hosted version of this platform needs rather than a contributor's laptop: a payments provider with a webhook secret and an API key, a second forge's application credentials plus an extra secret for tunnel authentication, a transactional email provider with its own webhook secret, a chat webhook, single sign-on product identifiers for two identity providers, Google, four values for a chat platform including its signing and state secrets, and a deployment token secret that the comment says must match a specific edge function alias.

## Conclusion

Argos suits a team that wants visual regression review that a person and an agent can both look at, and that is prepared to run a service-heavy local stack rather than a single binary. Before you contribute, read the compose file and the Dockerfile rather than the readme, because the version choices and the build traps are documented there and nowhere else. Expect to configure two GitHub applications and a dozen provider credentials for local work. And if you build the image yourself, pass the build target explicitly, or you will get an empty artefact and a confusing success.

## FAQ

### What is Argos used for?

Visual testing: comparing how a product renders so a reviewer looks at the result rather than only at the code. The readme describes it as an open-source visual testing platform for teams and AI agents, and links to a hosted reference project.

### Where are the Argos example projects?

In a separate JavaScript repository rather than in this one. The readme links to that repository's examples directory, so the examples are versioned independently of the platform code.

### Why does the Argos Dockerfile warn about the default build target?

The last stage copies the front-end output into an empty base image so continuous integration can lift it out of one cached build. Being last, it becomes the default, so an image build without an explicit target produces an empty artefact instead of the app.

### Why are the Argos development service versions pinned?

The compose comments explain both pins: development runs Postgres one major ahead of the managed production version to validate an upgrade early, and the broker is held at the version the managed service offers because a newer one changes redelivery accounting.

## Sources

- [argos-ci/argos on GitHub](https://github.com/argos-ci/argos)
- [Issues](https://github.com/argos-ci/argos/issues)
- [License: MIT](https://github.com/argos-ci/argos/blob/main/LICENSE)
- [Project website](https://argos-ci.com)
- [README](https://github.com/argos-ci/argos/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/argos-ci-argos