Try Latchkey locally

Get a sign-in email into a local file, follow the link, and confirm that your Rails app created a session.

Before you start

• Use Ruby 3.3+ and a Rails 8.0+ app with Active Record.
• Have a development checkout of Latchkey containing the documented work.
• Use a disposable local app and test account. Review generated migrations before running them.

1. Add the gem

In your host app’s Gemfile, replace the example path with your checkout’s absolute path:

gem "latchkey", path: "/path/to/latchkey"

bundle install
# Run this only if the Rails authentication files do not exist yet.
bin/rails generate authentication
bin/rails generate latchkey:install
bin/rails generate latchkey:email_link
bin/rails db:migrate

The install generator writes configuration. The email-link generator enables email sign-in and adopts hardened sessions. See what each generator changes.

2. Configure the local trial

Add these values inside Latchkey.configure in config/initializers/latchkey.rb:

config.base_url = "http://localhost:3000"
config.mail_from = "Latchkey <sign-in@example.test>"
config.rate_limit_store = ActiveSupport::Cache::MemoryStore.new

Inside your existing development configuration block in config/environments/development.rb:

config.active_job.queue_adapter = :inline
config.action_mailer.delivery_method = :file
config.action_mailer.file_settings = {location: Rails.root.join("tmp/mail")}
config.action_mailer.perform_deliveries = true
config.action_mailer.raise_delivery_errors = true

These adapters are for a local trial. A deployed app needs a shared cache, durable jobs and a real mail transport.

3. Follow your first link

1. Open bin/rails console and create a test account using your app’s account model. A standard Rails-generated model accepts email_address, password and password_confirmation. Use your own test values.
2. Start bin/rails server and open http://localhost:3000/sign-in.
3. Request an email link for the account. Open the message written to tmp/mail.
4. Open its link and submit the confirmation form to sign in.

Verify the result

Open /sessions in the signed-in browser. Your active session should appear. Sign out, then try the email link again: a consumed link must not create another session. Request a fresh one to continue.

Local mail files contain live credentials until their links expire or are consumed. Delete the test messages when you finish. If no message appears, follow the missing-email checks.

Next, review the host deployment checklist before testing outside your laptop.