Keep passwords and other sensitive information out of your inboxes and chat logs.

A onetime secret is a link that can be viewed only once. A single-use URL.

Try it out on OnetimeSecret.com

When you send sensitive info like passwords via email or chat, copies persist in many places. Onetime links self-destruct after viewing, ensuring only the intended recipient sees the information.

1. Start Redis:

docker run -p 6379:6379 -d redis:bookworm

2. Generate and store a persistent secret key:

# First, generate a persistent secret key and store it
openssl rand -hex 32 > .ots_secret
chmod 600 .ots_secret
echo "Secret key saved to .ots_secret (keep this file secure!)"

# Now run the container using the key
docker run -p 3000:3000 -d \
  -e REDIS_URL=redis://host.docker.internal:6379/0 \
  -e SECRET="$(cat .ots_secret)" \
  -e HOST=localhost:3000 \
  -e AUTH_REQUIRED=false \
  -e SSL=false \ # ⚠️ WARNING: Set SSL=true for production deployments
  onetimesecret/onetimesecret:v0.23.0

3. Access: http://localhost:3000

For existing installations: Your current setup will continue working without changes. Redis data migration is optional until v1.0.

Starting with v0.23, OneTime Secret uses Redis database 0 for all models by default (previously distributed across multiple databases). This improves compatibility with Redis-as-a-Service providers and support for connection pooling.

New installations: No action needed - automatically uses the optimized setup.

Existing installations: See the Redis Data Migration Guide for migration options and timeline.

Disable Web Interface (UI_ENABLED=false):

• Shows minimal explanation page instead of full interface
• Useful for maintenance or API-only deployments

Require Authentication (AUTH_REQUIRED=true):

• Homepage secret creation requires login
• Maintains site navigation while restricting access

Create ./etc/config.yaml from the example:

cp -p ./etc/defaults/config.defaults.yaml ./etc/config.yaml

Key configuration areas:

• Authentication: Two modes available - Simple (Redis-only, default) or Full (SQL database with MFA, WebAuthn, etc.)
• Email: SMTP, SES or SendGrid setup
• UI settings: Customize user experience

See docs/authentication/switching-to-full-mode.md for advanced authentication features

Common overrides:

HOST=your-domain.com
SSL=true
SECRET=your-secure-random-key
REDIS_URL=redis://host:6379/0
AUTH_REQUIRED=true
PASSPHRASE_REQUIRED=true
PASSWORD_GEN_LENGTH=8
TTL_OPTIONS='1800 43200 86400 259200'  # 30m, 12h, 24h, 3d

Important: Generate a secure SECRET key and back it up safely:

openssl rand -hex 32

Pre-built images:

# GitHub Container Registry
docker pull ghcr.io/onetimesecret/onetimesecret:latest

# Docker Hub
docker pull onetimesecret/onetimesecret:latest

# Lite version (smaller, optimized)
docker pull ghcr.io/onetimesecret/onetimesecret-lite:latest

Build locally:

git clone https://github.com/onetimesecret/onetimesecret.git
cd onetimesecret
docker build -t onetimesecret .

System Requirements:

• Ruby 3.4+
• Redis 5+
• Node.js 22+ (for development)
• 1GB RAM, 2 CPU cores minimum

Quick setup:

git clone https://github.com/onetimesecret/onetimesecret.git
cd onetimesecret
bundle install
cp ./etc/config.example.yaml ./etc/config.yaml
# Edit config.yaml as needed
RACK_ENV=production bundle exec thin -R config.ru -p 3000 start

For detailed installation instructions, including system setup, troubleshooting, and advanced configuration, see INSTALL.md.

Create your first admin (colonel) user via CLI:

bin/ots customers --create [email protected] --role colonel

Or promote an existing user:

bin/ots role promote [email protected] --role colonel

For active development with live reloading:

1. Enable development mode in etc/config.yaml:

:development:
  :enabled: true
  :frontend_host: 'http://localhost:5173'

2. Start servers:

# Terminal 1: Main server
RACK_ENV=development bundle exec thin -R config.ru -p 3000 start

# Terminal 2: Vite dev server
pnpm run dev

For complete setup with dependencies: Docker Compose repo

This repository uses a custom merge driver for locale JSON files to automatically resolve conflicts:

1. Install dependencies: pnpm install
2. Configure Git (one-time setup):

   git config merge.json.driver "npx git-json-merge %A %O %B"
   git config merge.json.name "Custom 3-way merge driver for JSON files"

The driver automatically resolves conflicts when multiple branches modify different keys in the same locale file. If a conflict cannot be resolved automatically (e.g., same key modified on both sides), Git falls back to standard conflict markers.

• Issues: GitHub Issues
• Documentation: Check docs/ directory for detailed guides
• Security: Review SECURITY.md for security considerations

See Dockerfile

This version of Familia was developed with assistance from AI tools. The following tools provided significant help with architecture design, code generation, and documentation:

• Claude (Desktop, Code Max plan, Sonnet 4, Opus 4.1) - Interactive development sessions, debugging, architecture design, code generation, and documentation
• Google Gemini - Refactoring suggestions, code generation, and documentation.
• GitHub Copilot - Code completion and refactoring assistance
• Qodo Merge Pro - Code review and QA improvements

I remain responsible for all design decisions and the final code. I believe in being transparent about development tools, especially as AI becomes more integrated into our workflows as developers.

This section provides an overview of services similar to our project, highlighting their unique features and how they compare. These alternatives may be useful for users looking for specific functionalities or wanting to explore different options in the same domain. By presenting this information, we aim to give our users a comprehensive view of the available options in the secure information sharing space.

Note: Our in-house legal counsel (codium-pr-agent-pro bot) suggested adding this introduction and the disclaimer at the end.

Summarized, fetched, and collated by Cohere Command R+, formatted by Claude 3.5 Sonnet, and proofread by GitHub Copilot.

This project is licensed under the MIT License - see the LICENSE file for details.

• Report Issues
• Security Issues (email)
• Try it Live