sgit-ai — git for encrypted vaults

Clone, commit, branch and merge files that are encrypted before they leave your machine.

sgit is a git-shaped command-line tool for version-controlling files the storage provider cannot read. Every object is encrypted client-side with AES-256-GCM and stored under an opaque, content-addressed id — the server never receives a key, and never sees a filename, a file's contents, or a commit message.

📖 Documentation: sgit.ai — quickstart, the git-to-sgit command mapping, the security model, and the honest page about when not to use this. 🤖 Reading this as an AI agent? sgit.ai/llms.txt is an annotated map of the whole site; sgit.ai/llms-full.txt is every page in one document. Every page is also available as markdown at the same path.

Not to be confused with SGit, the Android Git client, or SGIT, the engineering college. This is sgit-ai on PyPI — the encrypted-vault CLI, documented at https://sgit.ai.

Why this exists

You have files that need version control and collaboration, and the place they are stored must not be able to read them. git gives you the workflow and hands the host your content; encrypted sync tools give you privacy and no history worth the name. sgit is the two together — see sgit.ai/why/, including a straight comparison of where git is still better (performance at scale, ecosystem, bisect/blame/rebase) and where the vault model changes what is possible.

Install

pip install sgit-ai

This gives you two CLI commands: sgit-ai and the shorthand sgit.

Quick Start

# Create a new encrypted vault
sgit init my-vault

# Add files to the working directory
cp important-doc.pdf my-vault/

# Commit and push
sgit commit "initial upload" -d my-vault
sgit push my-vault

# Clone an existing vault on another machine
sgit clone <vault-key>

Features

Encrypted Vault Sync

Clone, commit, push, and pull encrypted vaults — just like git, but every object is AES-256-GCM encrypted before upload.

sgit clone <vault-key>          # Download and decrypt a vault
sgit status                     # Show uncommitted changes
sgit commit "my changes"        # Snapshot local changes
sgit pull                       # Fetch and merge remote changes
sgit push                       # Upload to remote
sgit branches                   # List all branches

Client-Side Encryption

All crypto runs locally. The server stores only ciphertext.

AES-256-GCM for file encryption with per-file HKDF-derived keys
PBKDF2-SHA256 (600k iterations) for vault key derivation
Content-addressable storage — encrypted objects stored by hash
Web Crypto API compatible — byte-for-byte interop with browser implementations

PKI and Digital Signatures

Built-in public key infrastructure for signing and encrypting files between users.

sgit pki keygen                             # Generate RSA-4096 + ECDSA P-256 key pair
sgit pki sign doc.pdf --fingerprint <fp>    # Create detached signature
sgit pki verify doc.pdf sig.json            # Verify signature
sgit pki encrypt doc.pdf --recipient <fp>   # Hybrid RSA-OAEP + AES-256-GCM encryption
sgit pki decrypt doc.pdf.enc --fingerprint <fp>

Vault Inspection

Debug and inspect the internals of any vault.

sgit inspect                    # Vault state overview
sgit log --oneline --graph      # Commit history
sgit inspect-tree               # Current tree entries
sgit inspect-stats              # Object store statistics
sgit cat-object <id>            # Decrypt and display an object
sgit fsck --repair              # Verify integrity and repair

Static Publishing — serve a vault with no server

Publish a vault as a plain folder of files that any static host (GitHub Pages, S3, a USB stick) can serve, and that sgit clone can read back over ordinary GETs. No server, no auth, no API.

sgit publish                          # write the plaintext surface to .sg_vault/publish/
sgit publish --visibility public      # ...including the read key (irreversible; confirms)
sgit publish --bundles --api-docs     # + head/delta zips + a Swagger UI docs page
sgit vault serve                      # read-only loopback server for the published folder

publish emits only a small plaintext surface — loader, cover.json, manifest.json and, at public, the read key. It never copies ciphertext: the encrypted store is the store, composed into the served root at deployment. Publishing twice from the same head produces byte-identical output, and it needs only the read key, so read-only clones and zero-secret CI can republish.

Reading back needs nothing special:

sgit clone <vault-key> ./dest --transport auto     # folder, static host, or live API

Custody, Attaching, and Ignore Rules

sgit vault mirror <url> ./copy      # keyless verifiable copy — custody without access
sgit vault attach --read-key <key>  # bind a key to an existing bare checkout (CI, git clone)
sgit vault ignore                   # show always-ignored folders
sgit vault ignore --apply .github   # untrack a now-ignored folder in one visible commit

mirror re-hashes every content-addressed object rather than trusting the manifest, so a hostile host cannot substitute content into a copy you are holding for someone else.

Machine-Readable Command Reference

sgit help --format json -o cli-reference.json   # diffable contract, for docs tooling
sgit help --format markdown                     # drop-in command reference page
sgit help --format llms                         # llms.txt-style index for agents

Generated by walking the CLI's own parser, so it cannot describe a command that does not exist or miss one that does — which is what keeps sgit.ai and llms.txt honest across releases.

Credential and Remote Management

# Store vault keys under friendly aliases
sgit vault add my-project --vault-key <key>
sgit vault list

# Configure multiple remotes
sgit remote add origin <url> <vault-id>
sgit remote list

Architecture

sgit_ai/
├── cli/           # CLI commands (sgit-ai / sgit)
├── crypto/        # AES-256-GCM, PBKDF2, HKDF, RSA-OAEP, ECDSA
├── sync/          # Clone, commit, push, pull, merge, branching
├── api/           # SGit-AI Transfer API client
├── pki/           # Key store and contact keyring
├── objects/       # Content-addressable encrypted object store
├── schemas/       # Type_Safe data models
├── safe_types/    # Domain-specific validated types (zero raw primitives)
└── secrets/       # Local encrypted secrets store

Built on osbot-utils Type_Safe framework — all data fields use validated domain types, never raw primitives.

Development

# Install in dev mode
pip install -e ".[dev]"

# Run tests
pytest tests/unit/

# Run with coverage
pytest --cov=sgit_ai --cov-report=term-missing

License

Apache-2.0

Documentation

Full documentation lives at sgit.ai — which is itself served from an encrypted vault, deployed by pushing that vault.


Quickstart	create, commit, push, clone in five minutes
sgit for git users	every git command mapped to its sgit equivalent
The two-branch model	private clone branches, shared named branches
Working with AI agents	`sgit write`, `--json` everywhere, the session pattern
Security model	the crypto stack, and what the server can still see
When NOT to use sgit	the honest page
Use cases	recipes with an evidence status and an agent brief each
llms.txt · llms-full.txt	machine-readable index for agents

Metadata

Release files for sgit-ai 0.21.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sgit-ai 0.21.0
File	Size	Uploaded
sgit_ai-0.21.0.tar.gz	429.7 kB	Oct 10, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for sgit-ai 0.21.0
File	Interpreter	ABI	Platform	Reset
sgit_ai-0.21.0-py3-none-any.whl 616.0 kB Oct 10, 2026	Python 3	none	any	Details

Total release size: 1.0 MB

Release files / sgit_ai-0.21.0.tar.gz

Download URL	sgit_ai-0.21.0.tar.gz
Size	429.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`9ba31d52bdbc23efe67b7bef0e930a0605c6c07ea69097cdb4c70887fe44c669`
BLAKE2b-256 checksum How to use checksums	`4a69ed475298f1efcf1c2caaf8f58f3047beb756e04d8f40e754385fdff96552`
Upload date	Oct 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.12.15`

Release files / sgit_ai-0.21.0-py3-none-any.whl

Download URL	sgit_ai-0.21.0-py3-none-any.whl
Size	616.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`359351c45bb9b63e887242bbeb5b1242f71137a704315ca6835bde723a5ac058`
BLAKE2b-256 checksum How to use checksums	`bed587622754f26d959dd0e89e77cd08da693f1c724532fafce600d4c48350cd`
Upload date	Oct 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.12.15`