Skip to main content
Glama
HybridS3
by psyb0t

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

Related MCP server: hive-mcp-agent-storage

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/.

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

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

License

WTFPL

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides persistent storage for AI agents via MCP and REST API, enabling saving and retrieving text, code, configs, and files with full-text search, tags, version history, and GitHub backup.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Agent-native object storage MCP server with per-agent DID isolation and x402 pay-per-byte metering in real Base USDC, enabling autonomous agents to store and retrieve objects with hot, warm, or cold retention classes.
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables LLM agents to interact with MinIO/S3 object storage, supporting bucket and object operations like listing, reading, writing, and generating presigned URLs.
      1
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables agents to interact with any S3-compatible storage (AWS S3, LocalStack, MinIO) via MCP, providing tools like list, read, write, delete objects and buckets.
      MIT