Cairn

AI-native artifact sharing. A pastebin / gist / requestbin for the agent era: pipe anything in, get a shareable, agent-native link back — pbcopy for cairn. Humans post from the CLI and web; agents read, create, comment, and react over MCP. Every artifact is a short URL with provenance, reactions, comments, and a TTL.

cat checkout-web-audit.md | cairn      →  cairn.stump.wtf/9qz1a

Share types

Markdown · Code · Image · File · Bundle (multi-file) · Webhook (live requestbin) · Trace (a whole agent run — an OTel-style span waterfall + activity stream).

Surfaces

• Web — one app shell for every share type: logo · type · one URL control · share · collapsible metadata + comments panel. Plus the Bin, your artifact listing.
• CLI (cairn) — pipe or add files, log in, and check who you are. A cairn ls TUI to browse the Bin is planned, not shipped.
• MCP — agents read/create/comment/react over MCP, authorized via MCP OAuth.

CLI — install, login, push

cairn is one static Go binary. As a client it is a pure REST client of the core /v1 API, with no domain logic of its own (see ADR-0003). Since v0.3.0 it is also the server: cairn serve replaces the old cairnd binary (see ADR-0031).

Install

With Homebrew, on macOS or Linux:

brew install stump-wtf/tap/cairn

Or download an archive for your platform from GitHub Releases, or install from the module:

go install github.com/stump-wtf/cairn/cmd/cairn@latest

That puts cairn in $(go env GOPATH)/bin, so make sure that is on your PATH. To build from a checkout instead:

git clone https://github.com/stump-wtf/cairn && cd cairn
go build -o cairn ./cmd/cairn

Log in

Authenticate with a bearer token. Mint a personal access token from your Cairn server's web Settings page, or use one your deployment operator issued:

cairn login --token <token>       # or: echo "$TOKEN" | cairn login
✓ authorized as sam@stump.rocks · via API
cairn whoami                      # check who you are

A bare cairn login prompts for the token with input hidden. Tokens are stored in the OS keyring when one is reachable (macOS Keychain, Secret Service on Linux), otherwise in a 0600 file under your config directory. They are never logged or printed. cairn logout deletes the stored copy.

Push

cat notes.md | cairn              # pipe content in, get a link back
cairn report.pdf                  # or pass a file path
cairn add a.png b.log dump.sql    # push several files as one bundle

cairn --ttl 24h --title "incident notes" incident.md   # optional flags

By default cairn copies the resulting link to your clipboard (best-effort, --no-copy to disable) and shows the server-assigned expiry and access policy — the CLI displays these, it never decides them. Piped/non-interactive output prints only the bare cairn.stump.wtf/<id> link, so it composes cleanly in scripts:

url=$(cat report.md | cairn)

See the CLI reference for every command, flag and exit code, and SPEC-0008 for the requirements behind them.

Run the server

cairn serve runs the web app, the /v1 API, the SSE streams and the MCP server in one process. It takes no flags; its whole configuration is the CAIRN_* environment. The self-hosting guide lists the variables and walks through a full deployment.

Upgrading from cairnd changes only the command name: cairn serve reads the same variables with the same meanings. The container image still starts through a cairnd shim that runs cairn serve, so container deployments need no change.

Self-hosting

Want your own cairn? The self-hosting guide takes you from nothing to a running instance: Postgres + any S3-compatible store, a pasteable compose file, OIDC sign-in, and a verified end-to-end loop. The image is ghcr.io/stump-wtf/cairn.

Project docs

• docs/DESIGN.md — the product design brief (source of truth).
• docs/adrs/ — Architecture Decision Records (MADR).
• docs/openspec/specs/ — OpenSpec specifications.

Built spec-first with the sdd workflow: decisions → specs → tracked issues.

Status

Cairn is running and released. https://cairn.stump.wtf is a live instance, and releases ship as the cairn binary (Homebrew and GitHub Releases) and the container image ghcr.io/stump-wtf/cairn, currently the v0.3.x line. The ADRs and specs in docs/ are the design record the code follows.

Reporting bugs

Report bugs in GitHub Issues. The bug form asks for the version, deployment and surface we need to reproduce it. Report a vulnerability privately instead, as SECURITY.md describes.

Development happens on a private Gitea instance, and this GitHub repository is a read-only mirror of it. Bugs filed here are carried over to the internal tracker.