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 from Node, with the SDK 
npm install @obsideo/sdk

@obsideo/sdk is the TypeScript client. It handles chunking, merkle roots, upload tokens, replication polling and client-side proof verification, so you do not hand-roll the wire format against the coordinator.

On a self-serve account, encrypt before you call putObject. The SDK stores and proves exactly the bytes you hand it and adds no encryption of its own (step 03 shows the pattern). Accounts can also be set up so the SDK does the encrypting for you: it generates a key for each object on your machine and seals it to your own public key, so the only thing we ever store is a sealed key that your private key alone can open. There is no server-side key service, and we hold no key material in either case. Ask for that at account creation: regan@obsideo.io.

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")

05PostgreSQL backups with Databasus

Databasus is a self-hosted PostgreSQL backup tool. It encrypts each dump with AES-256-GCM before upload, so the key stays with you and Obsideo only ever holds ciphertext. Point it at Obsideo as an S3 storage:

Endpoint:              https://s3.obsideo.io
Bucket:                your bucket (from signup, or create one with any S3 client)
Region:                us-east-1
Access key / secret:   your Obsideo S3 credentials
Prefix:                optional, e.g. databasus
Virtual-hosted style:  off (path-style, the Databasus default)

Press Test connection. Databasus writes a probe object, reads it back, compares it and deletes it. Then enable backups on a database with Encryption: ENCRYPTED.

Verified 2026-09-19 with Databasus 3.57.0 against production: a 3.96 GB PostgreSQL 16 database backed up in 120 seconds and restored into an empty database in 325 seconds, row counts and checksums identical. A 311 MB database round-tripped in 20 and 9 seconds.

Each backup lands as one object per dump part plus two small sidecar objects. All of them are replicated to three providers and re-challenged with signed possession proofs on the usual cycle. Restores go through Databasus's own restore screen; nothing Obsideo-specific is needed.

06What 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.

07For 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, boto3 and Databasus (step 05) 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.