obsideo

docs · quickstart

Encrypted backups to Obsideo in five commands.

An API key and an S3 endpoint. That is the whole integration. Every command on this page has been verified end to end against the production gateway.

01Get credentials (self-serve, 12 GB free, no card)

No card, no CAPTCHA, no phone. Accounts run in external-encryption mode: you encrypt, Obsideo stores ciphertext and proves it is still there.

Pointing an agent at this page? Give it the MCP server. No Python, no dependencies to install, no key handling, no shell quoting. Add this to your MCP client config:

{
  "mcpServers": {
    "obsideo": { "command": "npx", "args": ["-y", "obsideo-mcp"] }
  }
}

Then: signup_start with an email address, signup_verify with the 6-digit code that arrives. That creates the account, generates the Ed25519 signing key locally, and saves credentials to ~/.obsideo. put, get, ls, rm and usage work immediately. The server runs on your machine and credentials never reach us. Full tool contract with per-step postconditions: obsideo.io/agents.md.

Or call the API directly (three steps, no MCP)

Two API calls plus a key you generate yourself. Shell quoting differs by platform, so pick the matching block.

macOS / Linux

curl -X POST https://signup.obsideo.io/v1/auth/start \
  -H 'Content-Type: application/json' \
  -d '{"email":"YOUR_EMAIL","source":"YOUR_TOOL_NAME"}'

Windows: cmd.exe and PowerShell need double quotes with the inner ones escaped. Single quotes will fail, and PowerShell's curl alias is not curl, so use curl.exe.

curl.exe -X POST https://signup.obsideo.io/v1/auth/start -H "Content-Type: application/json" -d "{\"email\":\"YOUR_EMAIL\",\"source\":\"YOUR_TOOL_NAME\"}"

Generate your account signing key (needs pip install cryptography). The private key stays on your machine; the public half is registered at signup as your account identity. It does not authorize your uploads or deletes today: agents.md section 1b states precisely what it does and does not do.

python -c "from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey; from cryptography.hazmat.primitives import serialization; import base64; k=Ed25519PrivateKey.generate(); open('obsideo-signing.pem','wb').write(k.private_bytes(serialization.Encoding.PEM, serialization.PrivateFormat.PKCS8, serialization.NoEncryption())); print('obk_sig_'+base64.urlsafe_b64encode(k.public_key().public_bytes(serialization.Encoding.Raw, serialization.PublicFormat.Raw)).decode().rstrip('='))"

Then verify, swapping in the 6-digit code from your inbox and the obk_sig_ key just printed:

curl.exe -X POST https://signup.obsideo.io/v1/auth/verify -H "Content-Type: application/json" -d "{\"email\":\"YOUR_EMAIL\",\"code\":\"123456\",\"customer_signing_public_key\":\"obk_sig_...\"}"
Or at a terminal, as a human 
pip install obsideo-cli
obsideo login

Prompts for your email, then for the code. Generates the signing key and saves credentials for you.

However you arrive, you end up with an access_key and secret_key (shown once: store them now), the endpoint, your bucket name, and quota_gb: 12. Your bucket is created during signup, so your first write just works, with no CreateBucket call. Credentials go live on the gateway within seconds; a 403 on a very fast first write means wait a moment and retry. Enterprise or bespoke needs: regan@obsideo.io still works.

02Configure rclone

[obsideo]
type = s3
provider = Other
access_key_id = YOUR_ACCESS_KEY
secret_access_key = YOUR_SECRET_KEY
endpoint = https://s3.obsideo.io

This is the exact stanza used in production verification.

03Encrypted backup in one line

pg_dump $DB | zstd | age -r $BACKUP_KEY | rclone rcat obsideo:backups/db-$(date +%F).sql.zst.age

Encrypted with your key before a single byte leaves the machine. The same pattern works for any file or stream: tar archives, snapshots, exports.

04Restore

rclone cat obsideo:backups/db-2026-07-18.sql.zst.age | age -d -i key.txt | zstd -d > restored.sql

Verified byte-identical round trip. boto3 works too, including ranged multi-part downloads (2.6 GB restored in 70 seconds, hash-exact):

import boto3
s3 = boto3.client("s3", endpoint_url="https://s3.obsideo.io",
                  aws_access_key_id=KEY, aws_secret_access_key=SECRET)
s3.download_file("backups", "db-2026-07-18.sql.zst.age", "restore.bin")

05What happens after upload

  1. Your ciphertext is chunked and placed on 3 distinct storage provider nodes. Operator and facility independence is not guaranteed; some nodes currently share a datacenter.
  2. Every object is challenged with chunk-level merkle proofs on a continuous cycle, targeting roughly every 4 hours.
  3. Providers earn only for proofs they pass. Failed proof, no pay, and the network heals the replica.

You do not have to take retrievability on trust. GET any object and compare its sha256 to what you uploaded: that check is yours, and it needs nothing from us but the bytes back. The network also re-challenges every object continuously, though those proof records are issued by our own coordinator, so your own hash check is the part that never depends on believing us.

06For AI agents

Obsideo is agent-friendly by policy: no bot blocking, no humanness checks, and this page plus /llms.txt are written to be read by you. If a person asked you to give their app or prototype durable storage, the integration is:

  1. Sign up self-serve in step 01: 12 GB free, no card, credentials in about a minute.
  2. Point any S3 client at https://s3.obsideo.io; rclone and boto3 are the verified paths. Keep keys in environment variables, never in code.
  3. If the data should be unreadable by anyone but your user, encrypt before upload (step 03). The platform stores bytes exactly as sent and cryptographically proves possession on a continuous cycle either way.

Comparing options first? The sourced provider directory at /compare/ covers 25 providers, machine-readable at /compare/providers.json.