GitHub

Quickstart

From nothing to a shared notebook: point slivingdoc at a bucket, prove it from the command line, then add it to an MCP host.

This page goes from an empty machine to a notebook that an agent and you share. It takes four commands. Every command here is safe to repeat.

Before you start

  • Node.js 22 or newer. The npx launcher downloads the native binary for your platform, verifies its checksum, and runs it. No Git and no toolchain are needed. See Installation for the direct download instead.
  • An S3-compatible bucket that already exists. slivingdoc never creates or configures one.
  • Credentials for that bucket, in your shell. They come from the normal AWS chain, so an exported AWS_PROFILE or an active SSO session works too.

Tip: No bucket yet? Tigris gives you one with a single global endpoint, and a local SeaweedFS container gives you one with no account at all. Both are in Set up a bucket, with the endpoint and region settings each of them needs. Come back here afterwards.

The examples use a bucket called my-notes in us-east-1. Substitute your own.

export AWS_ACCESS_KEY_ID=<your-access-key-id>
export AWS_SECRET_ACCESS_KEY=<your-secret-access-key>
export AWS_REGION=us-east-1
export SLIVINGDOC_BUCKET=my-notes

1. Check the launcher

npx -y slivingdoc version

It prints slivingdoc and a version number, and touches nothing else — no bucket, no configuration. If this fails, the problem is Node.js or the platform, not your storage.

2. Pull the notebook

npx -y slivingdoc pull notes

This is the first contact with the bucket. Before anything else, slivingdoc runs a compatibility probe that proves the store does conditional writes the way the publication protocol needs; a store that fails it is refused here, at startup, rather than halfway through a commit.

On an empty notebook the report is short:

OK  generation 0  /home/you/work/notes
0 files changed, 0 insertions(+), 0 deletions(-)

OK is the status token, the generation is the accepted remote state you are now looking at, and the path is the notebook directory — every result names it. The directory notes/ now exists and holds the notebook.

Warning: A refusal here is almost always the bucket or the credentials. The diagnostic names the reason with every secret redacted — an INCOMPATIBLE_STORE category means the store itself is not suitable; an access error means the key or the policy is. See S3 requirements.

3. Write something and commit it

Create a file under notes/. It must be UTF-8 text; empty files are fine.

echo "Standup: shipped the cache fix." > notes/today.md

Publish it:

npx -y slivingdoc commit notes -m "first note"
OK  generation 1  /home/you/work/notes
  today.md  +1
1 files changed, 1 insertions(+), 0 deletions(-)

The generation moved, and the per-file line says what the publication added. That is the whole write path: edit files with any tool, then commit.

Run npx -y slivingdoc pull notes again from a second machine, or a second directory, and the same note comes back.

4. Give it to an agent

Now register the same command in your MCP host. In Claude Code:

claude mcp add slivingdoc \
  --env SLIVINGDOC_BUCKET=my-notes \
  --env AWS_ACCESS_KEY_ID=<your-access-key-id> \
  --env AWS_SECRET_ACCESS_KEY=<your-secret-access-key> \
  -- npx -y slivingdoc serve

Verify it with claude mcp list, or /mcp inside a session. Other hosts take the same command in their own syntax, or a JSON block — Connect an MCP host has all of them, and the credential choices that beat pasting keys into a configuration file.

The agent now has two tools, notes_pull and notes_commit. Ask it to read the notebook and add to it. It needs no path: each server takes its own notebook directory and names it in every result.

That directory is private to the server process, so it is not the notes/ you just used. To share one directory between the agent and yourself, add --workspace-root to the arguments — see Share a directory with humans.

Where to go next

Last updated September 21, 2026

Menu

Type to search the documentation.