HybridS3
by psyb0t
README.md
# HybridS3
[](https://github.com/psyb0t/docker-hybrids3/actions/workflows/pipeline.yml)
[](https://github.com/psyb0t/docker-hybrids3/releases)
[](https://github.com/psyb0t/docker-hybrids3/blob/main/LICENSE)
[](https://hub.docker.com/r/psyb0t/hybrids3)
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](#why)
- [Quick start](#quick-start)
- [Three ways in](#three-ways-in)
- [Documentation](#documentation)
- [Development](#development)
- [Limitations](#limitations)
- [Sponsor](#sponsor)
- [License](#license)
## 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
```bash
# 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](https://psyb0t.github.io/docker-hybrids3/deployment/) covers Compose, upgrades and backups, and [Configuration](https://psyb0t.github.io/docker-hybrids3/configuration/) lists every setting.
## Three ways in
Plain HTTP with a Bearer token. Public buckets need no token to read:
```bash
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:
```python
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:
```json
{
"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](https://psyb0t.github.io/docker-hybrids3/agent-integrations/).
## Documentation
The full documentation lives at **https://psyb0t.github.io/docker-hybrids3/**.
| Page | What it covers |
| --- | --- |
| [Running the container](https://psyb0t.github.io/docker-hybrids3/deployment/) | Tags, mounts, Compose, file ownership, upgrades, backups |
| [Configuration](https://psyb0t.github.io/docker-hybrids3/configuration/) | Every `config.yaml` setting with defaults and formats |
| [Keys and access](https://psyb0t.github.io/docker-hybrids3/keys-and-access/) | Bucket key pairs, the master key, public and private buckets |
| [HTTP API](https://psyb0t.github.io/docker-hybrids3/http-api/) | Routes, headers, status codes and error codes |
| [S3 API](https://psyb0t.github.io/docker-hybrids3/s3-api/) | Signature V4, boto3, aws-cli and supported operations |
| [MCP server](https://psyb0t.github.io/docker-hybrids3/mcp/) | Client setup, auth layers and every tool |
| [Presigned URLs](https://psyb0t.github.io/docker-hybrids3/presigned-urls/) | Time-limited GET and PUT links |
| [Storage, expiry and locking](https://psyb0t.github.io/docker-hybrids3/storage/) | MIME detection, TTL, cleanup and per-object locks |
| [Behind a reverse proxy](https://psyb0t.github.io/docker-hybrids3/reverse-proxy/) | `path_prefix`, nginx and https presigned URLs |
| [Agent integrations](https://psyb0t.github.io/docker-hybrids3/agent-integrations/) | Skill and plugins for Claude Code, Codex and OpenClaw |
| [Security](https://psyb0t.github.io/docker-hybrids3/security/) | What is protected, known gaps, checklist before exposing it |
| [Troubleshooting](https://psyb0t.github.io/docker-hybrids3/troubleshooting/) | Log format, startup errors and common failures |
| [Architecture](https://psyb0t.github.io/docker-hybrids3/architecture/) | Modules and the path of a request |
| [Development](https://psyb0t.github.io/docker-hybrids3/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.
```bash
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`](https://github.com/psyb0t/docker-hybrids3/blob/main/pyproject.toml) together with the lockfile. [Development](https://psyb0t.github.io/docker-hybrids3/development/) has the details, and [`AGENTS.md`](https://github.com/psyb0t/docker-hybrids3/blob/main/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
<a href="https://www.buymeacoffee.com/psyb0t"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-blue.png" alt="Buy Me a Coffee" height="60" width="217"></a>
## License
[WTFPL](https://github.com/psyb0t/docker-hybrids3/blob/main/LICENSE)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data