Your first Weave strand

Weave gives your computer a persistent peer node and agents a set of tools for signed, append-only data. Start with a small text block. You need Node.js 20 or newer and a supported macOS or Linux system.

Install the workspace

npx joinweave

The installer creates ~/.weave, a visible ~/Weave folder, and a local identity. It starts a user service and checks connectivity. It asks before changing your shell PATH or agent configuration. Keep npm optional dependencies enabled; no Rust toolchain is needed.

For an unattended, reproducible installation:

npx joinweave@0.1.1 --yes --json

This skips PATH and MCP prompts. The commands below use the installed binary directly, so they work without a new shell or PATH edit.

~/.weave/bin/weave doctor --json

Continue when ok is true. Operations explains failed checks and how to inspect the node.

Create and write on the first computer

Choose a new local name if hello-weave already exists.

~/.weave/bin/weave strand create --name hello-weave --json
printf '%s' 'Hello, Weave!' | ~/.weave/bin/weave strand append hello-weave --json
~/.weave/bin/weave strand read hello-weave --start 0 --length 1 --json
~/.weave/bin/weave dht announce hello-weave --json

Save the writer_pubkey returned by create: it is the 64-character hexadecimal writer public key. Share that public key with the receiver through a channel you trust. Keep the writer node running. Appending adds a block; repeating the append adds another block.

hello-weave is a local alias. Discovery uses the writer key, so choosing the same name on two computers does not give them the same data or writer authority. ~/Weave is a visible folder; putting a file there does not automatically announce or replicate it.

Read on a second computer

Install Weave there too. Replace the value below with the writer public key from the first computer, then run:

WRITER_PUBKEY='REPLACE_WITH_THE_64_HEX_WRITER_PUBLIC_KEY'
~/.weave/bin/weave dht find hello-weave --writer-pubkey "$WRITER_PUBKEY" --wait-secs 30 --json
~/.weave/bin/weave strand replicate hello-weave --source-pubkey "$WRITER_PUBKEY" --sparse --blocks 0 --wait-secs 30 --json
~/.weave/bin/weave strand read hello-weave --start 0 --length 1 --json

The last response should contain block 0 with encoding: "utf8" and data: "Hello, Weave!". The receiver holds a read-only pin and cannot append as the original writer. A discovered provider or an open pin alone is not proof that a block arrived; verify the replication result and exact read content.

The provider must stay reachable. NAT traversal uses authenticated libp2p relay streams when needed, subject to the relay's availability and quotas. This small example is suitable for the current public seeds. See sparse replication for selected ranges, cached reads and transport limits.

Give an agent the same tools

Connect the runtime MCP server, then ask your agent to call weave_status and weave_doctor. It can create, append, announce, find and replicate strands through the same running node.