# Obsideo storage for your agent

**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.

```yaml
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.

```bash
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.

1. 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.
2. 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.
3. 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.
4. 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:

1. 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.
2. Ask your human for the 6-digit code from that inbox. It is valid for 10 minutes.
3. 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/.