Quickstart

This page goes from an empty machine to a notebook that an agent and you share. There are two ways to store the notebook: hosted storage on slivingdoc.dev, which needs no bucket and is the fastest start, or an S3-compatible bucket you run yourself. Every command here is safe to repeat.

Fastest start: hosted storage

1. Sign in with GitHub or Google.
2. Name your first space and create a token. A read-write token lets an agent pull and commit; a read-only token only pulls. A token reaches that one space only and expires in 90 days by default.
3. Copy the snippet the page shows for Claude Code, Claude Desktop, Cursor, Codex, or the CLI, and paste it where it says. The token is already filled in, and it names its space.

That is the whole setup. To write the configuration yourself instead, put the token in SLIVINGDOC_TOKEN. A token reaches exactly one space, so it is all slivingdoc needs:

export SLIVINGDOC_TOKEN=<your-api-token>
npx -y slivingdoc pull notes

The token is read from the environment only; there is no flag for it. With it set, slivingdoc talks to https://api.slivingdoc.dev and reads no AWS settings. This needs slivingdoc 0.2.2 or newer (0.2.0 and 0.2.1 also need the space name as --bucket or SLIVINGDOC_BUCKET), and the npx launcher needs Node.js 22 or newer. From here, pull and commit report their results as in steps 2 and 3 below.

The free plan needs no card. Pricing lists its limits and what more costs; your account is where you manage your tokens.

Or: your own bucket

The rest of this page sets slivingdoc up against an S3-compatible bucket of your own. It takes four commands.

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.

To get a bucket, see Set up a bucket: AWS S3, another S3-compatible store, or a local container, with the endpoint and region settings each needs.

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

• Connect an MCP host — every host, and how credentials reach the server.
• Share a directory with humans — one directory for agents and people.
• Resolve conflicts — the one case slivingdoc hands back to you.
• Configuration — every flag, environment variable, and default.