HybridS3
hybrids3 is object storage in one small container. The same process answers the S3 API (AWS Signature V4, so boto3 and the AWS SDKs work unchanged), a plain HTTP API you can drive with curl and a Bearer token, and an MCP server that AI agents call as typed tools. Metadata lives in SQLite, object bytes are plain files on disk.
Buckets are configuration, not state. You list them in a YAML file with their keys, visibility, expiry and size limit, and nothing can create or delete one at runtime. What the file says is what exists.
Quick start
Get the example configuration and change every key in it:
wget -O config.yaml \
https://raw.githubusercontent.com/psyb0t/docker-hybrids3/main/config.example.yaml
Run the container, bound to loopback:
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
Check it and store something. With the example configuration, uploads is a public bucket whose key is uploads-secret:
curl http://localhost:8080/health
curl -X PUT http://localhost:8080/uploads/hello.txt \
-H "Authorization: Bearer uploads-secret" \
--data-binary "hello"
curl http://localhost:8080/uploads/hello.txt
Running the container covers Compose, volumes, upgrades and backups.
What is on this site
| Page | What it covers |
|---|---|
| Running the container | Image tags, mounts, Compose, file ownership, upgrades, backups and what lives in /data |
| Configuration | Every setting in config.yaml, with defaults, formats and startup errors |
| Keys and access | Bucket keys, public keys, the master key and what public and private buckets allow |
| HTTP API | Every route, query parameter, header, status code and error code |
| S3 API | Signature V4, boto3 and aws-cli setup, and which S3 operations work |
| MCP server | Connecting a client, the two auth layers and the seven tools |
| Presigned URLs | Handing out time-limited GET and PUT links for one object |
| Storage, expiry and locking | MIME detection, TTL expiry, orphan cleanup and per-object locks |
| Behind a reverse proxy | Serving under a path prefix with nginx without breaking signatures |
| Agent integrations | The skill and plugins for Claude Code, Codex and OpenClaw |
| Security | What is protected, what is not, and what to set before exposing it |
| Troubleshooting | Log format, startup errors, 503 responses and signature mismatches |
| Architecture | Modules, the request path and the metadata table |
| Development | The dev container, tests, dependency changes, CI and releases |
Limitations
hybrids3 is built for a handful of services and agents sharing one store, not for a cloud. It has no multipart upload, no object versioning, no ACLs beyond public or private buckets, no CORS headers, no replication and no encryption at rest. Listings return at most 1000 objects with no continuation. Each limit is described on the page it affects.