Pages on CodeInstances.com

About

Mon, 01 Jan 0001 00:00:00 +0000

CodeInstances keeps runs of programs as instances and replays them. It’s an open source project under the Apache License 2.0, made by SoftDevStudio.com. The code is on GitHub.

The current release is v0.7.0, the seventh one. It’s early. What it does, it does well and it’s tested, and the reference lists plainly what it can’t do yet.

Why the Project Exists

Code gets a lot of care. It sits in version control, it’s reviewed, tagged, released and kept for years. Runs get none. A program runs, talks to a few servers, prints something and exits, and the run is gone. If it failed, you have a log line and a guess.

Contact

Mon, 01 Jan 0001 00:00:00 +0000

The project would like to hear from:

Developers who tried CodeInstances and hit something it didn’t capture or replay the way they expected.
Teams with flaky tests, hard-to-reproduce failures or AI agents whose runs they’d like to keep.
Anyone with a question about the tool, the instance format or the numbers on this site.

Write to info@codeinstances.com.

For a bug, it helps to mention your system, the CodeInstances version (codeinstances version prints it), the language and HTTP client of the program you recorded, and what the replay report said. An instance file that shows the problem is the best bug report of all, once you’ve checked it holds nothing private.

Download

Mon, 01 Jan 0001 00:00:00 +0000

CodeInstances is a single static binary with no dependencies. Pick the archive for your system. These links always fetch the latest release, which is v0.7.0 right now.

System	Archive
Linux, x86-64	codeinstances_linux_amd64.tar.gz
Linux, ARM64	codeinstances_linux_arm64.tar.gz
macOS, Apple silicon	codeinstances_darwin_arm64.tar.gz
macOS, Intel	codeinstances_darwin_amd64.tar.gz
Windows, x86-64	codeinstances_windows_amd64.zip

Each archive holds two programs: codeinstances itself, and codeinstances-demo, the self-checking demo described in how it was tested. The license files come with them.

Check the Download

The release page has a SHA256SUMS file with a checksum for every archive. On Linux or macOS:

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

This takes a couple of minutes. You need the codeinstances binary from the download page and any program that talks to the network. The examples use a Python script, but the language doesn’t matter.

1. Record a Run

Put codeinstances record and -- in front of the command you’d normally type:

codeinstances record -o weather.instance -- python3 fetch_weather.py

The program runs as usual and its output passes through. When it exits, the run is kept in weather.instance: the command, what it printed, how it ended, and every HTTP and HTTPS request it made with the answer it got. record exits with the program’s own exit code, so it drops into scripts and CI without changing anything around it.

Reference

Mon, 01 Jan 0001 00:00:00 +0000

Every command, flag and limit in CodeInstances v0.7.0. For a first run, the quick start is shorter.

Commands

Command	What it does
`codeinstances record [flags] -- command [args...]`	Run the command and keep the run as an instance file
`codeinstances replay [flags] file [-- command [args...]]`	Run the recorded command again, or the one given, with the network replaced by the recording, and compare
`codeinstances diff [flags] a b`	Compare two instances: how they ended, their output, their calls and values, and their speed
`codeinstances shrink [flags] -pass passing failing [-- command]`	Find the fewest of the failing run’s answers that keep the failure, and keep that instance
`codeinstances test [flags] file-or-dir... [-- command]`	Replay instances as regression tests
`codeinstances group [flags] file-or-dir...`	Fingerprint failing runs and group the ones that fail the same way
`codeinstances serve [flags]`	Run a store that keeps instances under their ids
`codeinstances push [-to url] file-or-dir...`	Upload instances to a store
`codeinstances pull [-from url] [-o file] id`	Download an instance by id or unique prefix
`codeinstances report [-url store] file`	Write a Markdown bug report for an instance
`codeinstances fork [flags] -at N parent [-- command]`	Run on from a step: the parent’s answers before it, then live, offline or given
`codeinstances keygen [-o name] [-label text]`	Make a key pair for signing: `name.key` and `name.pub`
`codeinstances sign -key file.key [-signer name] [-o out] file`	Sign an instance, in place unless `-o`
`codeinstances show [-json] file`	Describe an instance, or print it whole as JSON
`codeinstances verify [-trust keys] file...`	Check files haven’t been changed since they were recorded or signed, and with `-trust` that a key you trust signed them
`codeinstances version [-json]`	The version, the format version and the commit it was built from

Exit codes: record and fork exit as the program did. replay exits 0 when the run matched and 1 when it diverged. diff exits 0 when the runs are the same and 1 when they differ. shrink exits 0 when it kept an instance and 1 when the failure couldn’t be narrowed down. test exits 0 when every test passed and 1 when any failed. group, report, push and pull exit 0 when they worked. verify exits 1 for an edited file, a signature that doesn’t check out or, with -trust, no signature by a trusted key. Anything else is 2 on a usage or file error.