slopbucket

A zero-dependency key-value store with 72-hour expiration, written in Rust.

Features

• HTTP API server for CRUD operations
• Web interface (HTML + CSS + vanilla JS)
• CLI commands for direct storage access
• All data expires after 72 hours
• No external dependencies

Installation

# Build from source
cargo build --release

# Or use make
make release

Usage

CLI Commands

# Set a key-value pair
slopbucket set <key> <value>

# Get a value by key
slopbucket get <key>

# Delete a key
slopbucket delete <key>

# List all keys
slopbucket list

HTTP API Server

# Start API server on port 8069
slopbucket serve --port 8069 --host 0.0.0.0

# Or use make
make serve

Endpoints:

• GET /<key> - Retrieve value
• GET / - List all keys
• POST /<key> - Set key-value (body is value)
• PUT /<key> - Set key-value (alias for POST)
• PATCH /<key> - Set key-value (alias for POST)
• DELETE /<key> - Delete key

Web Interface

# Start web interface on port 8070
slopbucket web --web-port 8070 --host 0.0.0.0

# Or use make
make web

Then open http://localhost:8070 in your browser.

Makefile Commands

make build      # Debug build
make release    # Release build
make serve      # Start API server
make web        # Start web interface
make install    # Install to ~/.local/bin
make clean      # Clean build artifacts
make test       # Run functionality tests

Storage Location

Data is stored in platform-specific directories:

Platform	Path
macOS	~/Library/Application Support/slopbucket/slopbucket_data.txt
Linux	~/.local/share/slopbucket/slopbucket_data.txt
Windows	%LOCALAPPDATA%\slopbucket\slopbucket_data.txt

Makefile Targets

Target	Description
build	Build debug binary
release	Build release binary
serve	Start API server (port 8069)
web	Start web interface (port 8070)
install	Install binary to ~/.local/bin
clean	Remove build artifacts
test	Run basic functionality tests
help	Show this help message

Examples

HTTP API with curl

# Set a key
curl -X POST -d "hello world" http://localhost:8069/mykey

# Get a key
curl http://localhost:8069/mykey

# Delete a key
curl -X DELETE http://localhost:8069/mykey

# List all keys
curl http://localhost:8069/

Bash Piping

# Store command output
date | curl -X POST --data-binary @- http://localhost:8069/lastrun

# Process stored value
curl -s http://localhost:8069/mykey | grep pattern

# Store file contents
curl -X POST --data-binary @file.txt http://localhost:8069/doc

# Save to file
curl -s http://localhost:8069/mykey > /tmp/saved.txt

CLI One-liners

# Store command output
date | xargs slopbucket set lastrun

# Get and process
slopbucket get mykey | grep pattern

# Store multiline text
slopbucket set notes "meeting at 3pm
todo: finish report"

# Conditional set (only if key doesn't exist)
slopbucket get mykey > /dev/null || slopbucket set mykey "default"

# Loop over keys
for key in $(slopbucket list | grep "^backup"); do
  slopbucket delete "$key"
done

# Idempotent script
if slopbucket get lock > /dev/null 2>&1; then
  echo "Already running"
else
  slopbucket set lock "1"
  # do work
  slopbucket delete lock
fi

# Persist state between script runs
count=$(slopbucket get counter 2>/dev/null || echo 0)
slopbucket set counter $((count + 1))

Power User One-liners

# Increment a counter
curl -s http://localhost:8069/count; \
  curl -X POST -d "$(($(curl -s http://localhost:8069/count) + 1))" \
  http://localhost:8069/count

# Watch a key (poll every 5s)
watch -n5 'curl -s http://localhost:8069/mykey'

# Store JSON
echo '{"foo":"bar"}' | curl -X POST -d @- http://localhost:8069/config

# Check-before-run (idempotent script)
if curl -s http://localhost:8069/myscript/lock | grep -q "1"; then
  echo "Already running"
else
  curl -X POST -d "1" http://localhost:8069/myscript/lock
  # do work
  curl -X DELETE http://localhost:8069/myscript/lock
fi

Cron Integration

# Track last run
0 * * * * curl -X POST -d "$(date)" http://localhost:8069/lastcron

# Run only if not already running
*/5 * * * * curl -s http://localhost:8069/job/lock || \
  (curl -X POST -d "1" http://localhost:8069/job/lock && \
   your-job-here && \
   curl -X DELETE http://localhost:8069/job/lock)

Web Interface

Open http://localhost:8070 in your browser to:

• Set key-value pairs via form
• View all stored data with timestamps
• Delete keys with a click

License

MIT License

Copyright (c) 2026 Aggressively Beige Holdings, LLC

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.