knockbox

mcp
Guvenlik Denetimi
Uyari
Health Uyari
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 7 GitHub stars
Code Uyari
  • network request — Outbound network request in admin/src/api.js
Permissions Gecti
  • Permissions — No dangerous permissions requested

Bu listing icin henuz AI raporu yok.

SUMMARY

Self-hosted push notification server for iOS. Send with one curl, read it on your phone, and send an answer back.

README.md

Knockbox

Self-hosted push notifications for iOS.
Send a message with one curl, get it on your phone — and get an answer back.

English · 简体中文

CI Latest release GitHub Container Registry Docker Hub Licence: MIT

Download on the App Store

Your script sends one curl to your own server, which pushes through Apple's APNs to your iPhone. There is no relay in between.

Knockbox is one Go binary and one SQLite file. It stores your messages, pushes them
straight to Apple's servers, and serves the history to the iOS app. There is no relay
in between and no account to sign up for — the server is yours.

A channel list, one line per thing being watched A message rendered with a table, code and an image The server and the push key both belong to you

Try it in a minute

There is a public instance at https://knockbox.miramiao.com/. Open it on your iPhone
with the app installed and you have your own inbox: no sign-up, no password. It runs
the same image as below, with quotas and a 30-day retention.

To keep your messages on your own hardware, run the server yourself.

Run your own

docker run -d --name knockbox -p 8080:8080 -v knockbox-data:/app/data \
  -e IGO_SERVER_EXTERNAL_URL=http://localhost:8080 \
  ghcr.io/aichy126/knockbox
docker logs knockbox

The first start creates the database and an admin account, and prints that account's
username and password in the log — once, and nowhere else. Open
http://localhost:8080/login, sign in, and the pairing page shows a QR code to scan
with the iOS app.

Set IGO_SERVER_EXTERNAL_URL to the address your phone will actually reach, for
example https://push.example.com. It goes into pairing links and attachment URLs, so
localhost works only while you are testing on the same machine.

Then send something:

curl -d "build failed" https://push.example.com/api/v1/send/<channel-token>

There is a compose.yaml for anything longer-lived, and prebuilt
binaries for Linux, macOS, Windows and FreeBSD on every tagged release.
No database server, no Redis — the whole thing is a binary and a .db file.
→ Running your own server

What it does

Send however you like Plain body, query string, multipart or JSON — every field also works from the query string, so a one-line curl is enough. →
Bodies without a length limit The body is not in the push payload, so it can be far longer than a notification allows. Markdown, tables, code, images. →
Ask for an answer Buttons to tap, checkboxes, a slider, or a field to type in. The answer is POSTed to a URL you provide, signed. →
One call, many people send/batch takes a list of tokens and reports per-token results — no broadcast credential needed. →
An endpoint for agents The same credential is an MCP endpoint over streamable HTTP, exposing one tool. →
A channel per thing Sound, interruption level and mute live on the server, so a script never has to decide what counts as urgent. →
Every device, the whole history A new device pairs by scanning a code and pulls everything.

It comes with its own pages

The server serves a sending guide at /docs — with your address already filled in and
a "send this one" button on every example. The public instance's copy is at
https://knockbox.miramiao.com/docs.

The built-in sending guide, showing a send address and ready-to-run curl examples

Behind /login there is an admin interface: an overview, message search, members and
their devices, pairing, and the settings that take effect without a restart.

The admin overview: counters for messages, push success rate, reachable devices and channels, with a list of recent messages

Every page, this interface included, is English and Chinese, switchable from the top
right; the admin interface remembers the choice. Adding a language is adding one JSON
file to internal/api/web/locales/ — the server and the admin interface read the same
one, so there is no second copy to keep in step.

Documentation

Running your own server Compose, Docker, binaries, source · reverse proxy · upgrades · backups · every setting
Sending and integrating Fields · attachments · answers and callbacks · batch · MCP · limits · CLI
Security What the embedded APNs key can and cannot reach, and how to report a problem
Contributing How to build, test and propose a change

Trade-offs you should know about

These are choices, not omissions. Read them before you deploy.

  • No end-to-end encryption. There is no relay, so messages only ever touch your own
    server — which also has to store them and generate push summaries, both of which need
    the plaintext. E2E here would mainly protect you from your own administrator.
  • Everything is kept in plaintext, forever by default. Full archive is the point:
    new devices pull the whole history. Set retention.days for a limit. The security
    boundary is that machine. →
  • A public APNs key is embedded in this repository, so that you can self-host
    without an Apple developer account. It is topic-specific — it can only push to this
    app — but it is public, and the honest consequence is that anyone who also obtains a
    device's APNs token could push to that device. Use your own key to remove that
    exposure. → · SECURITY.md
  • Channel tokens are stored in plaintext, because the app shows you a
    ready-to-paste curl line and hashing would make that impossible. They are
    write-only, scoped to one channel, rate-limited, and can be rotated at any time.
  • /admin/api/* is not a public contract. /api/v1 is. Everything under
    /admin/api/ serves the admin interface that ships here and will change whenever it
    does. →

Deleting is real deleting. Clearing a channel physically removes the rows: the
server runs with secure_delete, then checkpoints the WAL and vacuums. Attachments are
reference-counted and the blob goes when the last message referencing it does. What
this does not promise is that the bytes are gone from an SSD — wear levelling is below
the application layer.

Licence

MIT. See LICENSE.

Yorumlar (0)

Sonuc bulunamadi