# Stow

> An object store you can embed. Run it in Go or WebAssembly, with a native S3
> endpoint for existing SDKs.

Stow is an Apache 2.0 object engine with native S3 HTTP compatibility and a
WebAssembly profile. Prepared filesystem workspaces support checkpoints,
comparison, and portable handoff. The browser profile offers IndexedDB
persistence, retained file stages, undo/redo, and explicit conditional sync
through host-supplied networking. Embedded Go and Node WASM runtimes need no
HTTP listener. Native run-through mode adds an S3 read-through cache with
prewarming, cache limits, TTL, and explicit offline operation. WASM enables
embedding in compatible hosts; edge platform integrations need qualification.
Stow owns storage; the host owns execution and sandbox enforcement.

Native live writes commit locally before propagation through a durable outbox.
The outbox preserves the exact version, retries transient failures with bounded
backoff, and stops on remote conflicts or an unknown upstream baseline. Recovery
checks the remote ETag, content type, metadata, and requested checksum before
acknowledging an attempted write. Retry and discard require the admin token.

## Start here

- [Browser file history and sync](/docs/browser-file-history/):
  local commit, undo/redo, conditional writes, recovery, and limits.
- [Real browser editor demo](/docs/browser-editor/):
  run `make browser-editor` from a built source checkout.
- [Native read-through cache](/docs/run-through/):
  cache reads, prewarm exact keys, and work offline.
- [Durable outbox contract](/docs/s3-compatibility/#62-read-through-cache-semantics):
  local-first writes, conditional propagation, retries, and crash recovery.

- [Agent instructions](/agent.md): install commands, the prepared workspace
  flow for coding tasks, and the scoped-session pattern for disposable S3.
- [Running and probing a server](/docs/server/):
  how to start `stow-s3` yourself, read the endpoint and credentials it actually
  got, probe `/_stow/health`, and avoid the port and mode traps. Read this before
  writing a launcher.
- [Task manifest guide](/docs/task-manifests/): manifest fields, lifecycle, checkpoints, archives, and isolation limits.
- [Full reference](/docs/reference/):
  the full reference, including the CLI, the Go runtime, and the WebAssembly
  profile.

## Install

The npm and PyPI install surfaces are **not yet announced as usable**. The
`v0.2.0` release published the main package and all four platform carriers to
public npmjs, then failed before the GitHub Release, so there is no release page
and no `SHA256SUMS.txt` to verify a download against, and PyPI was not published.
A clean install of `0.2.0` from npm has not been verified end to end. The Go
module is published.

Platforms: Linux and macOS, on x64 and arm64. There is no Windows build, and the
workspace backend needs an advisory file lock that Windows does not provide, so
it refuses there rather than guessing. On Windows, use WSL.

```bash
go get github.com/chester-hill-solutions/stow-s3/pkg/stow   # Go, works now
```

TypeScript and Python work from a source checkout: `git clone`, `make build`,
then `export STOW_BIN="$PWD/bin/stow-s3"`, then `npm install && npm run build`
in `packages/stow-s3` (TypeScript) or `pip install -e
"packages/stow-s3-py[boto3]"` (Python). A published package carries its own
binary and does not need `STOW_BIN`.
The next candidate, **0.3.0**, targets the same public npmjs distribution and has
**not yet been published**. Publisher setup, live-provider gates and anonymous
exact-version installation must pass before availability is announced. Published
npm versions are immutable. For the new candidate, remove any old scope override
to `npm.pkg.github.com`; it would send installation requests to the wrong
registry.

If the binary cannot be found or run, `stow-s3 doctor` reports which side is
broken.

## Optional

- Product Hunt listing and the other five launch images
- `site/launch/*.html` are the sources of the launch graphics; the rendered
  PNGs are in `site/images/`