aviary

A webhook-driven document uploader that automatically downloads and sends PDFs to your reMarkable tablet through a web interface or API. Compatible with both reMarkable Cloud and self-hosted rmfakecloud via rmapi, with features like automatic PDF conversion, compression, and organized file management.

Why the Name?

Aviary is a place where birds are kept, chosen to evoke sending documents into the clouds using avian couriers.

Features

Frontend

• Send from URL
• Send from local filesystem
• Toggle for compression for supported filetypes
• Destination directory selector with cache for instant loadtimes
• Light and dark themes, with optional system theme detection
• Optional single-user auth via environment variables

Backend

• Webhook endpoint (/api/webhook) for SMS or HTTP integrations (e.g. Twilio)
• Optional API key
• Automatic PDF download with a realistic browser User-Agent
• Automatic conversion of PNG and JPEG images to PDF
• Optional Ghostscript compression
• Two upload modes:
  • Simple: upload the raw PDF
  • Managed: rename by date, upload, then append the year locally & clean up files older than 7 days

Screenshot

Environment Variable Configuration

Core Configuration

For more rmapi-specific configuration, see their documentation.

Authentication (Optional)

Authentication

Aviary supports optional authentication to protect your instance:

Web UI Authentication

Set both AUTH_USERNAME and AUTH_PASSWORD to enable login-protected web interface:

AUTH_USERNAME=myuser
AUTH_PASSWORD=mypassword

API Key Authentication

Set API_KEY to protect programmatic access to API endpoints:

API_KEY=your-secret-api-key-here

Use the API key in requests with either header:

• Authorization: Bearer your-api-key
• X-API-Key: your-api-key

Flexible Authentication

• No auth: If neither UI nor API auth is configured, all endpoints are open
• UI only: Set AUTH_USERNAME + AUTH_PASSWORD to protect web interface only
• API only: Set API_KEY to protect API endpoints only
• Both: Set all three to enable both authentication methods
• API endpoints accept either: Valid API key OR valid web login session

Webhook POST parameters

Example cURL

# Basic request
curl -X POST http://localhost:8000/api/webhook \
  -d "Body=https://pdfobject.com/pdf/sample.pdf" \
  -d "prefix=Reports" \
  -d "compress=true" \
  -d "manage=true" \
  -d "rm_dir=Books"

# With API key authentication
curl -X POST http://localhost:8000/api/webhook \
  -H "Authorization: Bearer your-api-key" \
  -d "Body=https://pdfobject.com/pdf/sample.pdf" \
  -d "compress=true"

# Alternative API key header
curl -X POST http://localhost:8000/api/webhook \
  -H "X-API-Key: your-api-key" \
  -d "Body=https://pdfobject.com/pdf/sample.pdf"

Integrations

• AWS SES - Lambda to provide emailed PDFs/ePubs to Aviary.

Examples

The following examples are provided as a way to get started. Some adjustments may be required before production use, particularly regarding secret management.

Set Up

1. Get your device and user token file (rmapi.conf) from the reMarkable cloud by running the following command and entering the one-time code: docker run -it -e RMAPI_HOST=remarkable.mydomain.com ghcr.io/rmitchellscott/aviary pair
2. Save the output as rmapi.conf, and this will get mounted into the container.

Docker

# Basic usage
docker run -d \
-p 8000:8000 \
-v ~/rmapi.conf:/root/.config/rmapi/rmapi.conf \
ghcr.io/rmitchellscott/aviary

# With authentication
docker run -d \
-p 8000:8000 \
-e AUTH_USERNAME=myuser \
-e AUTH_PASSWORD=mypassword \
-e API_KEY=your-secret-api-key \
-v ~/rmapi.conf:/root/.config/rmapi/rmapi.conf \
ghcr.io/rmitchellscott/aviary

Docker Compose

services:
  aviary:
    image: ghcr.io/rmitchellscott/aviary
    ports:
      - "8000:8000"
    environment:
      RMAPI_HOST: "${RMAPI_HOST}"
      # Optional authentication (uncomment to enable):
      # AUTH_USERNAME: "${AUTH_USERNAME}"
      # AUTH_PASSWORD: "${AUTH_PASSWORD}"
      # API_KEY: "${API_KEY}"
    volumes:
      - type: bind
        source: ~/rmapi.conf
        target: /root/.config/rmapi/rmapi.conf
    restart: unless-stopped

Building Locally

Requirements

• Ghostscript (gs CLI)
• ImageMagick
• npm
• rmapi (must be installed & in your $PATH)
• Access to your reMarkable credentials (rmapi setup)

Ensure the requirements are installed and available in your PATH.

go generate # Generate the Vite static front-end
go build -o aviary