ByteStash

ByteStash is a self-hosted web application designed to store, organise, and manage your code snippets efficiently. With support for creating, editing, and filtering snippets, ByteStash helps you keep track of your code in one secure place.

!ByteStash App

Demo

Features

• Create and Edit Snippets: Easily add new code snippets or update existing ones with an intuitive interface.
• Filter by Language and Content: Quickly find the right snippet by filtering based on programming language or keywords in the content.
• Secure Storage: All snippets are securely stored in a sqlite database (or optionally PostgreSQL), ensuring your code remains safe and accessible only to you.
• AI Integration (MCP): Connect AI assistants such as Claude, OpenAI and Perplexity through a built-in Model Context Protocol endpoint to search and manage your snippets, authenticated with your existing API key. See MCP (AI assistants).

Howto

Unraid

PikaPods

Docker

services:
  bytestash:
    image: "ghcr.io/jordan-dalby/bytestash:latest"
    restart: always
    volumes:
      - /your/snippet/path:/data/snippets
    ports:
      - "5000:5000"
    environment:
      # See https://github.com/jordan-dalby/ByteStash/wiki/FAQ#environment-variables
      #ALLOWED_HOSTS: localhost,my.domain.com,my.domain.net
      BASE_PATH: ""
      TOKEN_EXPIRY: 24h
      ALLOW_NEW_ACCOUNTS: "true"
      DEBUG: "true"
      DISABLE_ACCOUNTS: "false"
      DISABLE_INTERNAL_ACCOUNTS: "false"
# See https://github.com/jordan-dalby/ByteStash/wiki/Single-Sign%E2%80%90on-Setup for more info
      OIDC_ENABLED: "false"
      OIDC_DISPLAY_NAME: ""
      OIDC_ISSUER_URL: ""
      OIDC_CLIENT_ID: ""
      OIDC_CLIENT_SECRET: ""
      OIDC_SCOPES: ""
      # The address you open ByteStash at, e.g. https://bytestash.example.com
      PUBLIC_URL: ""

Single sign-on (optional)

• Redirect / callback URL: https://bytestash.example.com/api/auth/oidc/callback
• Post-logout redirect URL: https://bytestash.example.com/auth/logout_callback

On startup ByteStash logs whether it could reach the provider, and failed logins log the reason (and show it on the login page). If your provider uses a certificate from your own CA, mount the CA certificate into the container and point NODE_EXTRA_CA_CERTS at it, e.g. NODE_EXTRA_CA_CERTS: /certs/my-ca.crt.

PostgreSQL (optional)

environment:
      DATABASE_URL: "postgres://bytestash:password@postgres:5432/bytestash"
      # or
      POSTGRES_HOST: postgres
      POSTGRES_PORT: "5432"
      POSTGRES_USER: bytestash
      POSTGRES_PASSWORD: password
      POSTGRES_DB: bytestash

| Variable | Description | | --- | --- | | DATABASE_URL / DATABASE_URL_FILE | PostgreSQL connection string, or a file containing it (Docker secrets). | | POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB | Used when DATABASE_URL is not set. Port defaults to 5432, user and database to bytestash. POSTGRES_PASSWORD_FILE is also supported. | | POSTGRES_SSL | true to require TLS, no-verify to skip certificate verification, false to disable. | | MIGRATE_SQLITE_TO_POSTGRES | true copies the existing SQLite data into PostgreSQL on startup. Only runs while PostgreSQL is empty, so it is safe to leave enabled. |

If neither DATABASE_URL nor POSTGRES_HOST is set, ByteStash keeps using SQLite. Keep the /data/snippets volume mounted either way: it holds the generated JWT secret (unless JWT_SECRET is set) and the SQLite file used by the migration.

Migrating from SQLite to PostgreSQL

1. Take a backup of your /data/snippets volume.
2. Add the PostgreSQL settings above together with MIGRATE_SQLITE_TO_POSTGRES: "true" and restart

The migration can also be run by hand once PostgreSQL is configured:

docker compose exec bytestash node src/scripts/migrateToPostgres.js
replace whatever is already in PostgreSQL with the SQLite data
docker compose exec bytestash node src/scripts/migrateToPostgres.js --force

Changes made while running on PostgreSQL are not copied back to SQLite.

Tech Stack

• Frontend: React, Tailwind CSS
• Backend: Node.js, Express
• Database: SQLite (default) or PostgreSQL
• Containerisation: Docker

API Documentation

MCP (AI assistants)

• Endpoint: https:///mcp (or https:///mcp when a

• Transport: Streamable HTTP.
• Auth: the same API key used by the REST API. Create one under

Available tools

Connecting clients

• Claude Desktop (claude_desktop_config.json):

{
    "mcpServers": {
      "bytestash": {
        "type": "http",
        "url": "https://your-host/mcp",
        "headers": { "Authorization": "Bearer YOUR_API_KEY" }
      }
    }
  }

• Claude.ai / web & other custom connectors: add a custom connector pointing at

• OpenAI Responses API: pass it as an MCP tool:

{
    "type": "mcp",
    "server_label": "bytestash",
    "server_url": "https://your-host/mcp",
    "headers": { "Authorization": "Bearer YOUR_API_KEY" }
  }

• Perplexity: add a remote MCP connector with the URL above and the same

The endpoint requires HTTPS for remote clients — terminate TLS at your reverse

proxy/ingress as you already do for the web UI.

Contributing

I18n

• Add the locale name to the Locale enum in the client/src/i18n/types.ts file
• Add the locale name to the locales array in the client/i18next.config.ts file
• Run translation synchronization: cd client && npm run i18n:extract
• Replace all __TRANSLATE_ME__ lines with the desired phrases
• Create new resources file as client/src/i18n/resources/fr.ts
• Update export resources in file client/src/i18n/resources/index.ts
• Run the server in development mode: npm run dev
• Run the client in development mode: cd client && npm run start