HUB
Sign inSign up

psyb0t/hybrids3

By psyb0t

•Updated 9 days ago

Lightweight object storage that speaks S3 (boto3/AWS SDK compatible), plain HTTP, and MCP. SQLite...

Image
0

6.0K

psyb0t/hybrids3 repository overview

Source⁠ | Project page⁠

⁠HybridS3

CI version license Docker Pulls

Lightweight object storage that speaks S3 (boto3/AWS SDK compatible), plain HTTP, and MCP. SQLite for metadata, flat files on disk.

Documentation: https://psyb0t.github.io/docker-hybrids3/⁠

⁠Table of contents

⁠Why

Most self-hosted S3-compatible storage is built for large deployments. Distributed erasure coding, IAM policies, WORM compliance, full web consoles. Useful if you run a cloud, overkill if you just want a place to put files that a few services and AI agents can read and write.

AWS Sig V4 breaks behind reverse proxy path prefixes. Put most implementations behind nginx at /storage/, nginx strips the prefix, the server sees /bucket/key while the client signed /storage/bucket/key, and every signature check fails. hybrids3 has a path_prefix setting: set it to /storage, every route moves under it, the proxy forwards the path untouched and the signatures match.

Three interfaces, one service. boto3 works out of the box. curl with a Bearer token works. AI agents connect over MCP and get typed tools. One container, one port.

Buckets are configuration, not state. There is no API to create or delete a bucket. Buckets live in the YAML config, so you always know exactly what exists, it's version-controlled, and no surprise buckets pile up garbage.

TTL expiry is built in. Set ttl: 24h on a bucket and objects expire 24 hours after their last write. No lifecycle policies, no cron jobs.

Small enough to read in an afternoon. Thirteen Python modules.

⁠Quick start

# get the example config, then change every key in it
wget -O config.yaml \
  https://raw.githubusercontent.com/psyb0t/docker-hybrids3/main/config.example.yaml

docker run -d --name hybrids3 \
  -p 127.0.0.1:8080:8080 \
  -v ./config.yaml:/config/config.yaml:ro \
  -v hybrids3-data:/data \
  psyb0t/hybrids3

curl http://localhost:8080/health

The container reads /config/config.yaml, keeps everything in /data and runs as UID 1000. Running the container⁠ covers Compose, upgrades and backups, and Configuration⁠ lists every setting.

⁠Three ways in

Plain HTTP with a Bearer token. Public buckets need no token to read:

curl -X PUT http://localhost:8080/uploads/file.txt \
  -H "Authorization: Bearer uploads-secret" \
  --data-binary "hello"

curl http://localhost:8080/uploads/file.txt

boto3, with the bucket's public_key as access key ID and its key as secret:

import boto3
from botocore.config import Config

s3 = boto3.client(
    "s3",
    endpoint_url="http://localhost:8080",
    aws_access_key_id="uploads-id",
    aws_secret_access_key="uploads-secret",
    region_name="us-east-1",
    config=Config(signature_version="s3v4"),
)
s3.put_object(Bucket="uploads", Key="file.txt", Body=b"hello")

MCP, Streamable HTTP at /mcp/, with seven tools for uploading, downloading, listing, deleting and presigning:

{
  "mcpServers": {
    "hybrids3": {
      "type": "streamable-http",
      "url": "http://localhost:8080/mcp/"
    }
  }
}

There is also an agent skill and plugin for Claude Code, Codex and OpenClaw; see Agent integrations⁠.

⁠Documentation

The full documentation lives at https://psyb0t.github.io/docker-hybrids3/⁠.

PageWhat it covers
Running the container⁠Tags, mounts, Compose, file ownership, upgrades, backups
Configuration⁠Every config.yaml setting with defaults and formats
Keys and access⁠Bucket key pairs, the master key, public and private buckets
HTTP API⁠Routes, headers, status codes and error codes
S3 API⁠Signature V4, boto3, aws-cli and supported operations
MCP server⁠Client setup, auth layers and every tool
Presigned URLs⁠Time-limited GET and PUT links
Storage, expiry and locking⁠MIME detection, TTL, cleanup and per-object locks
Behind a reverse proxy⁠path_prefix, nginx and https presigned URLs
Agent integrations⁠Skill and plugins for Claude Code, Codex and OpenClaw
Security⁠What is protected, known gaps, checklist before exposing it
Troubleshooting⁠Log format, startup errors and common failures
Architecture⁠Modules and the path of a request
Development⁠Dev container, tests, dependencies, CI and releases

⁠Development

All tooling runs in a sandboxed dev container, so the host needs only Docker, Make, Bash and curl.

make help       # every target
make lint       # flake8 + mypy
make test       # production image, unit tests and the integration suite
make build      # production image
make docs       # build the documentation site locally

Dependency changes go through make pkg-add, pkg-remove, pkg-update and pkg-upgrade, which move the supply-chain age gate in pyproject.toml⁠ together with the lockfile. Development⁠ has the details, and AGENTS.md⁠ is the guide for coding agents.

⁠Limitations

No multipart upload, no object versioning, no ACLs beyond bucket-level public/private, no bucket creation or deletion through the API, no CORS headers, no replication and no encryption at rest. Listings stop at 1000 objects.

⁠Sponsor

Buy Me a Coffee

⁠License

WTFPL⁠

Tag summary

Content type

Image

Digest

sha256:a4ce651b9…

Size

93.6 MB

Last updated

9 days ago

docker pull psyb0t/hybrids3