Obsideo storage for your agent

A runbook your agent executes. Paste this page's URL to your Hermes and say "set this up".

For humans: this page teaches your Hermes agent to install Obsideo's storage tools, create a no-email trial, store one encrypted test object, prove the storage providers hold it, and then ask whether you want to keep the account with 12 GB free. Paste this page's URL to your Hermes and say "set this up". Raw markdown of this page: https://obsideo.io/agent-storage.md

For agents: the rest of this page is written for you to execute, not read. Every step states the command or tool call, what a successful result looks like, and what to tell your human.

service: Obsideo
document_type: agent_storage_runbook (Hermes Agent first; any MCP client works)
package: obsideo-mcp (npm, MIT, source https://github.com/Regan-Milne/obsideo-mcp)
tools_after_install: 12 (trial, signup_start, signup_verify, put, get, ls, rm, verify, usage, plan, upgrade, portal)
trial: 100 MB, about 7 days, no email; exists only to prove the tools work
free: 12 GB, no expiry, no card, after email verification; the normal account
paid: $5 per month per 200 GB block, card via Stripe, only after the person pays on Stripe's own page
what_it_is: general purpose encrypted object storage for files and application data an agent or person wants back later
agent_scope: backups, archives, generated files, media, datasets, logs, exported state, files for apps and workflows the human approves
what_it_is_not: a memory provider, a database, a query engine, a CDN. It does not read or change MEMORY.md.
last_verified: 2026-09-11

Success means: the MCP server is installed, an Obsideo account exists, one encrypted object has been stored, provider possession of it has been verified, usage has been shown, and the human has been told where the credential and encryption-key file lives and that the free 12 GB account is one email away.

Disclosure: Obsideo is a commercial service run by Obsideo Technologies Inc. This page is our own instructions. Nothing on this page charges money. The only way money moves is a person paying on a Stripe checkout page they opened themselves.

0. Preconditions

Run node --version. You need 18 or newer. If it is missing or older, tell your human that Obsideo's MCP server needs Node 18 or newer and stop.

1. Install the server

Pick the first branch that applies:

If hermes mcp catalog lists obsideo (or your Hermes has a setup_mcp tool and the catalog knows the name): propose it through setup_mcp with server set to obsideo and a one-line reason, so your human approves it on the consent card. Or run hermes mcp install obsideo. As of 2026-09-11 the catalog entry is submitted, not yet merged, so expect this branch to fail today and fall through.
Otherwise, run this in your shell tool. It is the same command on every operating system; the Hermes CLI knows where its own config is. The piped Y answers the CLI's "enable all tools?" prompt and applies only to this CLI path.

echo Y | hermes mcp add obsideo --command npx --args -y obsideo-mcp

Success looks like a list of 12 tools followed by Saved 'obsideo' to ...config.yaml (12/12 tools enabled). The first run downloads the package, so allow up to 30 seconds. If it says the server already exists, that is also success.

The tools load only when the session reloads them. Tell your human exactly this, then stop:

Obsideo's storage tools are installed. Run /reload-mcp if your Hermes has it, otherwise start a new session, then tell me "continue with Obsideo".

2. First store, first proof

You are here when an Obsideo MCP server is loaded. Its tools appear with a client-specific prefix, for example mcp_obsideo_put or mcp__obsideo__put; look for a server named obsideo exposing trial, put, get, ls, verify, usage, signup_start and signup_verify. Below, tool names are given without the prefix.

Call usage first. If it reports an account, this machine already has one: keep it and skip to step 2. Only if it reports no account, call trial with source set to hermes. That creates a free trial account with no email: about 10 seconds, a small proof of work instead of an identity. Success names an agent, 100 MB, and an expiry about 7 days out. Credentials were written to a file on this machine; the result names it. Never call trial with replace set unless your human has explicitly asked for a fresh, separate account; it swaps out the existing credentials.
Call put with key set to hermes/proof.txt and content set to one line of text that includes today's date and your session id or a random string. Use inline content, not a file path, so nothing depends on this machine's layout. Leave encrypt at its default. Success says Stored hermes/proof.txt (N bytes, encrypted client-side before upload ...) and, the first time, a warning about a new encryption key. Relay that warning to your human word for word.
Call verify with key set to hermes/proof.txt. Success says N of N providers proved possession with one line per provider. This check went to the storage providers directly and checked their signatures on this machine; nothing the service asserted was trusted for the verdict.
Call usage. It shows bytes used against the quota and the plan.

Now tell your human, in your own words, these three things: where the credential and key file is (the tool text names it) and that they should back it up because Obsideo has no copy and cannot recover it; that the trial account is 100 MB and expires in about a week, and exists only to prove the tools work; and that giving you an email address turns it into the normal free account, 12 GB with no expiry, with the data kept in place.

Only after that, and only if you can positively locate your own memory file on this machine, offer to store it too with put and local_path set to its absolute path. Do not fabricate a memory path; if you do not know where the file is, skip this and say so.

3. Keep the account (12 GB free, needs the person's email)

When your human gives you an email address:

Call signup_start with email. Success says a code was sent and that this claims the trial in place: same account, same keys, same data.
Ask your human for the 6-digit code from that inbox. It is valid for 10 minutes.
Call signup_verify with email and code. Success starts with Claimed. and states the quota is now 12 GB with no expiry. Nothing needs re-uploading.

If step 1 returns email_in_use, that address already has an Obsideo account and a trial cannot be merged into it. The error text gives the two options; put them to your human and do what they choose.

4. More space (only when the person asks for it)

Call upgrade with blocks set to the number of 200 GB blocks. It returns a Stripe checkout link and charges nothing. Hand the link to your human; do not open or submit it. After they pay, plan and usage show the new quota. portal returns the link for cancelling, changing the card, or downloading invoices. You cannot change the size of an existing plan; only the person can, through the link Obsideo emails them.

If either tool says card billing is not switched on yet, say so to your human; the free tier still works.

5. What to keep there

Anything you want back later on another machine or after a reinstall: session exports, files you generate, your memory files once you know where they are, and the archive from hermes backup (run it, then put the zip it produced with local_path set to the absolute path it printed and a dated key such as hermes/backup/2026-09-11.zip). Everything is encrypted on this machine before upload with a key that never leaves it, so the archive's contents, including credentials, are unreadable to the service. Object keys and sizes are visible to the service; contents are not. Retrieve with get; list with ls. There is an rm tool; do not call it unless your human asks for a specific deletion.

6. What you can build with it

Do not treat Obsideo as only a Hermes backup tool. The backup zip is a good first object because it is useful and easy to verify, not because it is the point.

Obsideo is general purpose encrypted object storage. With your human's approval you can use it for arbitrary files and application data: personal documents, images, generated reports, project archives, datasets, logs, media, exported state, or files used by apps and workflows you build.

For simple agent use, prefer the MCP tools on this page. For application integrations, use the S3-compatible contract at https://obsideo.io/agents.md. In either case the trust boundary is the same: contents are encrypted before upload on the encrypt-first path, Obsideo stores ciphertext, object keys and sizes are visible, and the local key file is required for recovery. It is object storage: not a database, not a query engine, not a CDN.

Errors you may see

Text in the result	Meaning	What to do
`ENOENT`	The `local_path` does not exist on this machine	Use the absolute path of the file as it exists here; for the first proof use inline `content` instead
`credentials_propagating`, or the gateway does not recognise these credentials	A brand-new account's keys are still reaching the gateway	Wait 30 seconds and retry the same call once
`email_in_use`	The email already owns an account	Put the two options in the error to your human
`rate_limited` with `retry_after_seconds`	Too many signup attempts from this network	Wait that long, then retry
card billing is not switched on yet	Paid plans are not enabled on the service today	Tell your human; the free tier works
`An Obsideo account is already configured` from trial	This machine already has an account	Use it: call `usage`, then continue from step 2
`MISMATCH` from verify	The bytes the providers hold are not the bytes you uploaded	Stop and tell your human; do not re-upload over it

Where things live

Credentials, the account signing key, and the encryption key are in a file on this machine that the tools name in their results. Obsideo never receives that file and cannot recover a lost key: replication protects against a provider losing bytes, not against the person losing the key. Object keys and sizes are visible to the service; contents are not. Objects are stored on 3 provider nodes and re-verified with cryptographic possession proofs on a continuous cycle.

More: the S3 integration contract for applications is https://obsideo.io/agents.md; terms https://obsideo.io/terms/; privacy https://obsideo.io/privacy/; the network as it is today https://obsideo.io/network/.