Lightweight object storage that speaks S3 (boto3/AWS SDK compatible), plain HTTP, and MCP. SQLite...
6.0K
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/
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.
# 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.
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.
The full documentation lives at https://psyb0t.github.io/docker-hybrids3/.
| Page | What 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 |
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.
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.
Content type
Image
Digest
sha256:a4ce651b9…
Size
93.6 MB
Last updated
9 days ago
docker pull psyb0t/hybrids3