Hey everyone! I am sharing some feedback after spending 13 hours debugging why OTP via SMS wasn't working on a self-hosted Ory Kratos setup. I followed the official docs for passwordless login via OTP, used the same config and identity schema, and set my custom SMS provider webhook (via webhook.site), but no SMS messages were being sent. After trying everything I could think of (config variations, schema tweaks, courier configs), I finally found an old Slack thread that mentioned I needed to start Kratos with the

--watch-courier

flag. Once I did that, it started working immediately. 👉 The thing is, the documentation around this is really not clear, especially when it comes to SMS. The courier documentation focuses heavily on email, and the SMS use case is never clearly tied to the courier requirement. Suggestions: 1. Please update the SMS OTP setup guide to explicitly mention that

--watch-courier

is required to dispatch messages (SMS included). 2. Also, update the Kratos production deployment guide to include

--watch-courier

as a necessary step or flag, especially for setups that depend on message delivery. 3. Clarify in the docs what the courier is and what it does — this is a key part of message delivery (email/SMS), and it’s easy to miss its importance when self-hosting. Thanks for the awesome tool, and I hope this helps others avoid the same rabbit hole I went down 🙏

Hey - since you struggled with this and know what needs fixing- we would appreciate a PR!

Sure, I will work on that!