Pithos

Warning

Beta Software: Pithos follows semantic versioning and is currently below v1.0.0. Breaking changes to the API, configuration format, or storage layout may occur between minor versions. Please review the changelog before upgrading. Pithos is not recommended for production use with important data.

Pithos is an S3-compatible object storage server designed for self-hosters, written in Go.

Features

• S3-compatible API with extensive operation support:
  • Bucket Operations: Create, Head, Delete, List buckets, CORS, lifecycle, website, and versioning
  • Object Operations: Head, Get, Put, Copy, Append, Delete, multi-delete, List objects, List object versions
  • Multipart Upload Operations: Initiate, Upload, Upload Part Copy, Complete, Abort, List
• Object metadata, object tagging, delete markers, and S3-style bucket versioning
• S3 Object Lock: governance/compliance retention, legal hold, synchronous replication recovery and audit
• Authentication using AWS Signature Version 4
• Authorization through Lua scripts or IAM-inspired JSON policies
• Configurable storage backends (local filesystem, S3, etc.)
• Prometheus metrics endpoint for monitoring
• Health monitoring endpoints
• Docker support for easy deployment

Note

Bucket tagging supports up to 50 user-defined tags. Configurations that use S3ClientStorage, including it as a replication target, support up to 45 user-defined bucket tags because five upstream tag slots are reserved for Pithos system metadata.

Quick Start

Create an authorizer.lua with your access rules before starting; the default authenticated mode requires an explicit script. See Getting Started for a minimal example and credential configuration.

git clone https://github.com/jdillenkofer/pithos.git
cd pithos
go build -o pithos ./cmd
./pithos serve

Or run the published multi-architecture image from GitHub Container Registry:

docker run -p 9000:9000 -v "$(pwd)/data:/data" \
  -v "$(pwd)/authorizer.lua:/app/authorizer.lua:ro" \
  ghcr.io/jdillenkofer/pithos:latest

The same release image is also published as jdillenkofer/pithos:latest on Docker Hub. See Verifying Releases for its Cosign signature and GitHub provenance verification instructions.

Documentation

For detailed documentation, see the docs directory:

• Getting Started – Installation, build, and Docker setup
• CLI Reference – All commands and options
• Configuration – Environment variables and authorization
• Account Ownership Update – One-time upgrade procedure for existing databases
• S3 API Behavior – Object metadata, versioning, and SDK-facing semantics
• Storage Backends – Storage types and configuration examples
• Audit Logging – Audit middleware and verification
• Verifying Releases – Cosign verification

License

Pithos is licensed under the MIT License.