shard v0.1.4

Built by the release workflow from a06155a.

Changes since v0.1.3

New

• CLI: shard shell SANDBOX opens an interactive shell in a sandbox: bash, or sh when the image has no bash. It takes --workdir and --user, and exits with the shell's exit code. When the image has no shell at all, it says so. #590
• CLI: shard stop, shard remove, shard pause and shard resume take several sandboxes. A failure does not stop the others: the command prints each failure and exits non-zero. #598
• CLI: shard list -q (--quiet) prints only the ids. It does not go with --format. #598
• CLI: shard prune removes every stopped sandbox, and asks first. With no terminal, it needs --force. #598
• Setup: shard setup can set up the HTTP API (shard serve) as a background service. A first install asks, and a new "Set up the HTTP API" row adds it to an existing install. The flags are --http-api, --listen (default 127.0.0.1:7850) and --replace-api-key. Setup creates an API key and saves it in /etc/shard/api-key, which only root can read, or in /var/lib/shard/auth/api-key on a Mac. It never prints the key. A repeated setup keeps the key, and --replace-api-key replaces it. With no terminal, --http-api defaults to false. #603
• Setup: shard setup --storage-size <size> and shard daemon --storage-size <size> set how much space shard reserves for its data. They apply only to Firecracker on a filesystem that cannot clone files, such as ext4. Elsewhere the flag fails and says why. The default is half of the free space, at most 100 GiB. The minimum is 10 GiB, and 10 GiB always stays free for the host. Setup shows the size of an existing image and never resizes it. With no terminal and no flag, setup takes the default and prints it. #587
• Firecracker and vz: a sandbox created with no --memory, or with --memory 0, gets 512 MiB. Before, the create failed. A fork keeps the memory of its source, and a create from a snapshot keeps the memory of the snapshot. Under 128 MiB still fails, with --memory is 100 MiB, under the 128 MiB provider firecracker needs; set it to 128 MiB or more. #600
• CLI: shard inspect shows forked_from, the id of the sandbox that a fork came from. #607
• API: the sandbox record has a new forked_from field: the id of the sandbox a fork came from. #607
• SDKs: useshards 0.1.2 names the sandbox a fork came from, as forkedFrom in TypeScript and forked_from in Python. #607

Fixes

• Setup (Linux): when the daemon fails at start, setup and repair stop after about 6 seconds, not 2 minutes. They print The daemon failed to start: with the daemon's error, then Read its log with: sudo journalctl -u shard.service. #586
• Setup: when a daemon task keeps failing (3 or more restarts), setup stops its wait after about 3 seconds. It prints The daemon started, but these tasks keep failing:, then each task with its last error. #602
• Setup: when the GitHub API rate limit for your IP address is spent, setup says so and gives the local time when it resets, or says to try again within an hour. The installer prints the reset time too. Setup now downloads its files from the release download URLs, which have no rate limit, so only the check for a newer release uses the API. #605
• Setup: shard setup on an installation that setup did not make still changes nothing, and now exits 1, so a script can tell that refusal from a successful setup. Before, it exited 0. #611
• Uninstall: uninstall removes the shard-serve unit that setup wrote. A shard-serve unit that you installed yourself stays. Uninstall says that a new setup does not start it, and prints sudo systemctl start shard-serve and the commands that remove it. Before, the next setup after an uninstall could delete it. #597 #603
• Uninstall (Linux): uninstall also removes the iptables rules and the firewalld zone that shard added for its bridge. #589
• Network (Linux): on a host with ufw or firewalld, sandboxes got no DNS, no proxy and no routed traffic, because the host firewall dropped them first. shard now opens its bridge as Docker does: iptables rules with the comment managed-by-shard, and a firewalld zone shard. The daemon checks them every 5 seconds, so it repairs them after a ufw reload. The docs no longer tell you to run ufw allow. If firewalld already has a zone shard or a policy shard-forwarding that shard did not make, shard leaves that zone or policy unchanged and refuses to start a sandbox. Rename yours, or remove it if nothing uses it. #589
• API: when a firewalld zone shard or policy shard-forwarding that shard did not make refuses a create, the failed reason of the sandbox names that zone or policy, so a client of the HTTP API sees the cause. #615
• Daemon: a second daemon on another root no longer removes the network rules of the first daemon's sandboxes. It refuses to start: shard: another shard daemon, over the root /var/lib/shard, already serves this host's sandbox bridge and nft table: a host runs one daemon, so stop that one or use its root. #599
• CLI: errors name a sandbox by its name, or by its id when it has no name. #607
• CLI: when a file is missing, shard cp names the path and the sandbox: "/missing" in sandbox sb: no such file or directory. #608
• CLI: sudo shard cp from a sandbox leaves the copied files owned by the user who ran sudo, not by root. A directory that is already there keeps its owner and mode. #608
• CLI: a disk that the provider refuses names --disk and the fix. A fork cannot set its disk, so its refusal says to remove a sandbox. #585
• CLI: shard exec --workdir with a directory that does not exist exits 126 on every provider. On every provider but gVisor, the error says the work directory "/missing" does not exist. #588 #594
• API: a resume keeps started_at, so the uptime counts from the first start. #607
• API: errors and the in_use holder lists name a sandbox by its name, or by its id when it has none. #607
• API: a failed create names its network cause, such as set up the sandbox network on the host: nft failed: No such file or directory. Host paths and addresses stay in the daemon log. When no address is free, the error says no free address left: every sandbox holds one until it is removed, run shard list --all and remove the ones you no longer need. #607
• API: a disk that the provider refuses at create, fork or pause is a 400 invalid_request that names the fix, not a 500 internal. #585
• API: an exec with a work directory that does not exist is a 422. runc and Sysbox answered 500 before. #588
• API: a sandbox with a secret or a policy needs an image with a CA bundle. Without one, create, secret grant and policy attach answer 400 invalid_request, not 500: image index.docker.io/library/node:22-bookworm-slim has no CA bundle, which a sandbox with a secret or a policy needs: use an image with ca-certificates. #592
• API: when the host does not trust the certificate of an upstream, the 502 from the proxy has host and reason in its body, such as the upstream's certificate is signed by an authority the host does not trust. shard policy logs shows it as a deny of the rule certificate. To trust an internal CA, add it to the host's certificate store and restart the daemon. #596
• API: in shard policy logs, a drop by a host rule has rule_text, as long as the rule has not changed since. #596
• SDKs: every client and SDK gets the new text of the cp file errors. #608
• Sandboxes: under the UMask=0077 that setup gives the daemon, /etc and the work directory of a sandbox were 0700, so users other than root and apt failed. Directories that shard makes in a sandbox are 0755 now, and every exec runs with umask 0022. Mount points that Sysbox makes itself still take the daemon's umask. #592
• Firecracker and vz: after a resume or a fork, the guest clock matches the host clock. Before, it was behind by the length of the pause, so TLS checks failed. This also holds for Firecracker on arm64, so the limits page no longer lists it. #595
• Firecracker and vz: a fork whose disk copy cannot fit fails before shard captures the source. The source no longer freezes and pauses for it, which took 12 to 14 seconds on Firecracker. #606
• Firecracker and vz: a sandbox makes its work directory at start, so `shard c...

shard v0.1.3

Built by the release workflow from a8e1da0.

Changes since v0.1.2

New

• Docs: https://useshards.com/docs covers install and setup, a server and a client quickstart, the concepts, the security model, guides, the TypeScript and Python SDKs, a reference and help. The repository's docs/ guides moved there, and the README points at the site. #541
• Docs: the CLI reference pages are generated from cli/help.go (make cli-docs), and a unit test fails while they differ. #550
• Docs: the REST API reference pages are generated from the public route spec with docs/openapi.json (make openapi), and a unit test fails while either differs. #552
• Firecracker and vz: the kernel field of a sandbox record holds the tag of the guest kernel it booted, such as kernel-6.12.110-3, or local-<12 hex of its sha256> for a SHARD_KERNEL dev kernel. Create and start record it, resume keeps it, and a fork copies its source's. gVisor, runc and Sysbox leave it out. #539
• CLI: create, fork and run --detach print created sandbox <name> on stderr when the sandbox has a name. Stdout keeps the id alone. #553

Fixes

• Setup: with a saved remote connection, the first screen is that connection's menu (check, replace, remove, run sandboxes on this machine, exit). --local, --provider or --start-at-boot picks the local item, and --remote <url> still picks replace. #535
• Setup: the save prompt states that the connection stores the API key as plain text before it asks, and the note no longer follows the save. #535 #540
• Setup: a question with no terminal names the flag that answers it in plain words. A local setup with no terminal lists every missing flag in one error before any check, and exits 1. #535
• Setup: the review lists the removal of a saved connection, and the result for the saved connection prints before the next steps. #535
• Setup (Linux): the data check finds a Firecracker disk image in /var/lib/shard with no sandbox records. A refusal over another provider's data names the provider that keeps it and the commands that delete it. The delete steps first remove the sandboxes through shard daemon --provider <owner>, shard list --all and shard remove --force, so their netns, veth and cgroup go too. Then they run rm -r /var/lib/shard. With a disk image they first free it with the uninstall note's commands: umount, the sed of its /etc/fstab line and systemctl daemon-reload when there is one, and rm of the image. When /usr/local/bin/shard is missing, the steps first choose the owner's provider so setup installs shard and starts its daemon, then remove the sandboxes, uninstall with shard setup, and delete the data. Repair and upgrade stop with the same advice before any change, and exit 1. #540
• Setup (Linux): when only root can read the sandbox records, setup asks for administrator access before the checks and reads them with sudo. A record it cannot read is skipped, as the daemon does. #540
• Setup: the retry hint after a failed step names shard setup, or the full path of the running binary when shard is not on PATH. With no terminal, it repeats the run's flags. #540
• Setup: a menu or the step list that redraws shorter clears the rows the taller one left. #540
• Setup: a new local setup and a repair show download progress for runsc, firecracker and sysbox. A download that gets no data for 30 s fails with "no data for 30s". #540
• Setup: a local setup ends with "shard is set up." and a repair with "shard is repaired.". When the service starts at boot, both end with ", and the daemon is running." instead of the period. #537 #543
• Setup: host commands drop sudo for a root login, and hints for shard commands never show sudo on a Mac. #543
• Uninstall (Linux): the note ends with rm -r /var/lib/shard (with sudo unless root), plus the image's lock file when it exists, and adds systemctl daemon-reload after the sed of the /etc/fstab line. #553
• Uninstall (Linux): when the disk image is gone but its /etc/fstab line stays, the note names the line and gives the sed, the reload and the rm -r, with umount /var/lib/shard first while the data directory is still mounted. #553
• Uninstall (macOS): the note prints the command that deletes the saved data. #543
• CLI: with the daemon down on a host where setup installed a service that starts at boot, the error says "is the background service running? shard setup repairs it". A service installed by hand keeps its systemctl status or launchctl print hint. #537
• CLI: errors name the fix as a command or a flag. Errors and --help text say "API key" instead of "token", and write shard in lowercase. A command in a hint starts with sudo when the CLI runs under sudo against the local socket. #543
• API: a sandbox or snapshot name with the shape of a generated id gets 400 invalid_request on create, fork and snapshot create, not 500 internal. #537
• API: snapshot create on a sandbox whose image is gone names shard pull <image>, not shard image pull. #537
• API: error messages, failed_reason and stopped_reason use plain words. No code, status, field or route changes. #543
• SDKs: the TypeScript and Python errors use the same words and drop server internals. A patch changeset carries them to the next useshards release. #543
• vz: when the daemon loses its guest connection and cannot read the VM state from a shim that still runs, the sandbox no longer reads as stopped. The daemon retries within the grace period, then keeps the error. #533
• vz: a guest connection that times out after 5 s leaks no goroutine, handle or connection, and an answer that arrives at the timeout is used. #533
• vz: a status of a VM whose shim pid is gone waits for the follower to record the end, up to killGrace (10 s), then reads stopped, never running, both while the follower redials after a SIGTERM and after it lost the shim. A process in its exit counts as gone. #581 #582
• gVisor, runc, Sysbox: the restart count, ended and gave_up ride the exit record on fd 0, which the host holds, so a process in the sandbox cannot change them through /.shard/restarts.json. #529
• gVisor, runc, Sysbox: a link, a fifo or a large file in /.shard no longer fails stop, and a directory, a link or a link loop at the ready file no longer fails the next start. #529
• Remove: shard rm no longer fails when the egress log writes into the sandbox directory during the remove. #527
• Daemon: two log lines stop reading like faults: the socket line ends "for its owner only, as this host has no shard group", and a finished task logs "task completed and needs no restart". #553
• Site: the landing page has a new design, and the docs take its palette, fonts and logo. The installer's banner and the README show the new logo. #538 #577 #534 #576

VM proof, per docs/release.md:

• Mac: Mac mini (Mac14,3, Apple M2)
• macOS: 26.6 (25G72)
• head that passed: a8e1da0

useshards (TypeScript) 0.1.2

Patch Changes

• 03bcd2b: A sandbox record names the sandbox it was forked from, as forkedFrom in TypeScript and forked_from in Python.

useshards (TypeScript) 0.1.1

Patch Changes

• 2939f8d: Clearer wording in the README, the docstrings and the error messages.

useshards (Python) 0.1.2

Patch Changes

• 03bcd2b: A sandbox record names the sandbox it was forked from, as forkedFrom in TypeScript and forked_from in Python.

useshards (Python) 0.1.1

Patch Changes

• 2939f8d: Clearer wording in the README, the docstrings and the error messages.

shard v0.1.2

Built by the release workflow from b6da7f9.

Changes since v0.1.1

New

• One-line install: curl -fsSL https://useshards.com/install | sh downloads the newest release, checks it against that release's SHA256SUMS, installs it to ~/.local/bin/shard and offers to run shard setup. A failed or cut install keeps the old binary. The landing page and the Install docs page show the command. #514

Fixes

• Install: the PATH hint also prints the export line for the current shell, so shard works without a new shell. #520
• Setup: shard setup --help and the Install page list the setup exit codes. #520
• Setup: the administrator check now fails at once for a user that sudo does not allow, and names the reason. A user whose sudo needs a password passes only when setup can ask at a terminal. The apply step names the same cause. #520
• Setup (macOS): a Mac where no local provider runs now defaults to a remote connection, and the local choice says why vz is not available. #520
• Setup (macOS): the provider menu marks vz as Recommended. #518
• Setup: a local setup ends with next steps (list, create, exec and remove), with sudo where the socket needs it, and the foreground daemon command when the daemon does not start at boot. #519
• Setup: "Check or repair" finds a deleted provider file, and restarts a running daemon so it restores its own files. #519
• Setup: an upgrade checks that the restarted daemon answers before it reports the upgrade done, and ends with a closing line. #522
• Setup: a manual install (files setup did not make) now shows its version, the provider its sandboxes use, whether they keep running when its service stops, and the commands that move it to setup. Setup still changes none of its files. #522
• Setup: a failed download names its cause in plain words (timed out, refused, no such host), not a socket address. #521
• Setup: a progress line wider than the terminal no longer leaves pieces of old text on screen. #521
• Setup: a download that stalls for 30 s (no connection, no TLS handshake, no headers, or no new bytes) fails with "connection timed out", instead of a spinner for about 17 minutes. A slow download that still moves completes. #523
• Setup: with SHARD_REMOTE set beside a saved connection, local setup names the SHARD_REMOTE server as the one that commands use, and the unset hint names the saved connection that they use after it. #523
• Uninstall: a setup without a background service no longer lists a step to remove one. #518
• Uninstall: no longer says that a binary it just removed remains. #518
• Uninstall: removes the bridge and the nft tables when no sandbox and no proxy still use them, and says how to turn ip_forward off. It never changes ip_forward itself. #518
• Uninstall (Linux): the refusal that asks you to remove your sandboxes first now prints its commands with sudo. #521
• Uninstall (Linux): names the data disk image /var/lib/shard.xfs, its size, its /etc/fstab line, and the commands that free the disk. The data stays unless you run them. #522
• Uninstall (macOS): names the daemon logs in /var/log/shard, which it leaves, and the command that removes them. #522
• Remote: a refused API key names where the key came from (SHARD_API_KEY or the saved config file) and how to fix it. It never prints the key. #521
• Remote: a failed connection names its cause, such as no answer, a self-signed certificate, or a socket that needs sudo, instead of a local-daemon hint or a raw x509 error. #521
• Remote: setup prints one line per check, and the plain-text key warning shows only when the key is saved. #521
• Remote: Exit after a failed remote check prints a line. Edit prefills the saved URL, and Enter at the key prompt keeps the current key. #518
• Remote: removing a saved remote on a machine with no local setup points to shard setup. #519
• CLI: an error that says the daemon log has the cause now names that log on this host: /var/log/shard/daemon.log on macOS, journalctl -u shard with systemd, or the daemon's terminal. #519
• CLI: a create refusal names the flag you type (--memory, --vcpus, --disk), not the API field. #519
• CLI: shard list says on stderr how many stopped sandboxes it hides (1 stopped sandbox; shard list --all). #521
• CLI: shard exec on a stopped sandbox names it by the name you gave it, not its id. #521

VM proof, per docs/release.md:

• Mac: Mac mini (Mac14,3, Apple M2)
• macOS: 26.6 (25G72)
• head that passed: b6da7f9

shard v0.1.1

Built by the release workflow from 5ae8584.

Changes since v0.1.0

New

• shard setup sets up this host for local sandboxes (provider, tools, data directory, and a systemd or launchd service), or saves a connection to a remote daemon. See docs/setup.md. #516

Fixes

• Firecracker: a create, start, fork or restore that is cut after its VM came up now ends that VM, so the daemon no longer holds it. #511
• macOS and Firecracker: a tag that another provider already pulled now gets its missing disk format built offline, from its own layers, with no registry call. A pull streams building then pulled. A held image with missing blobs no longer heals from the registry: remove it and pull it again. #511
• macOS: stop cuts a reconnect to the guest that is in flight, so it no longer fails after 10 s with "the last events of sandbox ... still land". #515
• Sysbox: after a daemon restart, stop, rm -f and the liveness check no longer fail on a sandbox whose PID 1 has fd 0 on a file the daemon cannot open. #509
• Sysbox: stop no longer fails when the guest removes one of its own cgroups during the stop. #511
• runc, Sysbox and gVisor: a cgroup memory count that cannot be read now fails status, and is no longer read as "no OOM kill". #509
• Egress: each sandbox logs its dropped packets under its own rate limit, so one sandbox can no longer use up the shared limit and silence the drop records of the others. #507
• Egress: a request the proxy cannot judge gets a 502 with fixed text. It no longer shows the guest the host's nameserver. The daemon log keeps the cause. #507
• Images: the image cache refuses a cached manifest or config that no longer matches its digest, and shard image ls lists such an image as unreadable. #510
• Images (macOS): the VM disk now drops a whited-out link target and keeps the directory of an opaque marker, the same as the directory unpack does. #510

SDKs and release tooling

• The useshards SDKs 0.1.0 are on npm and PyPI. They have their own versions and their own GitHub releases. #513
• One Release SDKs pull request now releases the SDKs to npm and PyPI when it merges. #512
• Guest kernel releases are titled guest-kernel-<version>. The tags and the files stay the same. #517
• Tests: a killed test run no longer leaves fake guests and Firecracker VMs running. #515

VM proof, per docs/release.md:

• Mac: Mac mini (Mac14,3, Apple M2)
• macOS: 26.6 (25G72)
• head that passed: 5ae8584

shard v0.1.0

Built by the release workflow from 9e68bfa.

VM proof, per docs/release.md:

• Mac: Mac mini (Mac14,3, Apple M2)
• macOS: 26.6 (25G72)
• head that passed: 9e68bfa

useshards (TypeScript) 0.1.0

Built by sdk-release.yml from 9e68bfa. Install from these assets: the SDK is on neither npm nor PyPI.