A Rails-inspired framework for building serverless Ruby applications on AWS Lambda.

Belt bundles everything you need to go from zero to production:

• BeltController — callbacks, strong parameters, error handling, CORS
• Belt::LambdaHandler — Lambda entry point with observability, CORS preflight, error wrapping
• Belt::ActionRouter — request routing to controllers from route manifests
• ActiveItem — DynamoDB ORM (queries, validations, associations, transactions)
• Lambda Loadout — structured logging, CloudWatch metrics (EMF), error alerting

Add to your Gemfile:

gem "belt"

Then:

bundle install

my-app/
├── infrastructure/
│   ├── routes.tf.rb        # Belt provider route definitions
│   └── schema.tf.rb        # DynamoDB table schemas
├── lambda/
│   ├── config/
│   │   └── environment.rb  # App boot file (used by console + Lambda)
│   ├── controllers/
│   │   └── posts_controller.rb
│   ├── models/
│   │   └── post.rb
│   ├── lib/
│   │   └── routes.rb
│   └── api.rb              # Lambda entry point
├── .irbrc                  # Console customization (optional)
├── Gemfile
└── Gemfile.lock

require "activeitem"

class Post < ActiveItem::Base
  self.primary_key = :id

  attr_accessor :id, :user_id, :title, :body, :created_at

  validates :title, presence: true
  before_create { self.id ||= SecureRandom.uuid }
end

require "belt"

class PostsController < BeltController::Base
  before_action :authenticate!

  # Implicit response: assigns become the JSON body
  # → { "posts": [ { "id": "...", "title": "..." }, ... ] }
  def index
    @posts = Post.where(user_id: current_user_id, index: "UserIndex")
  end

  def show
    @post = Post.find(params["id"])
  end

  # Implicit body + non-200 status
  def create
    attrs = params.require(:post).permit(:title, :body).to_h
    @post = Post.create!(attrs.merge(user_id: current_user_id))
    response_status :created
  end

  def destroy
    Post.find(params["id"]).destroy
    head :no_content
  end
end

Use Belt::LambdaHandler to get automatic observability, CORS preflight handling, and error wrapping:

require "belt"

include Belt::LambdaHandler

ROUTER = Belt::ActionRouter.new(routes: Routes::API, namespace: "api")

def execute(path:, body:, event:)
  ROUTER.route(event: event, body: body)
end

That's it. lambda_handler is automatically your Lambda function handler. It:

• Initializes structured logging and CloudWatch metrics
• Handles OPTIONS preflight requests
• Parses JSON request bodies
• Catches unhandled errors and returns proper CORS-enabled error responses
• Calls your execute method for routing

The Conveyor Belt Terraform provider (formerly Dispatcher) handles Lambda packaging, API Gateway routing, and IAM permissions.

Add the provider to your Terraform config:

terraform {
  required_providers {
    conveyor-belt = {
      source  = "stowzilla/conveyor-belt"
      version = "~> 0.0.1"
    }
  }
}

Define routes in infrastructure/routes.tf.rb:

Belt.application.routes.draw do
  namespace :api do
    resources :posts, only: [:index, :show, :create]
  end
end

Define tables in infrastructure/schema.tf.rb:

Belt.application.schema.define do
  model :post do
    partition_key :id, :string
    global_secondary_index :UserIndex, partition_key: :user_id
  end
end

Then deploy:

terraform init
terraform apply

The provider will:

• Package your Ruby code into Lambda functions
• Create API Gateway routes matching your DSL
• Generate IAM policies for DynamoDB table access
• Set up CloudWatch log groups

class AdminController < BeltController::Base
  before_action :authenticate!
  before_action :require_admin!, except: [:health]
  skip_before_action :authenticate!, only: [:health]
end

params.require(:user).permit(:name, :email, address: [:street, :city])

class ApiController < BeltController::Base
  rescue_from MyCustomError, with: :handle_custom

  private

  def handle_custom(exception, _context = {})
    error_response(exception.message, 422)
  end
end

success_response({ id: "123", name: "Example" })       # 200 JSON with CORS
success_response({ id: "123" }, :created)               # 201 Created (symbol or int)
error_response("Not found", :not_found)                 # 404 JSON error
error_response("Nope", :unprocessable_entity)           # 422
html_response("<h1>Hello</h1>")                         # 200 HTML with CORS
head :no_content                                        # 204 empty body
head :created                                           # 201 empty body

# App-wide — typically in lambda/config/environment.rb
Belt.configure do |config|
  config.default_format = :json   # default
end

# Per-controller override
class PagesController < ApplicationController
  self.default_format = :html
end

• :json (default): action assigns → success_response({ posts: [...] })
• :html: action assigns stay on the controller; Belt implicitly renders views/<controller>/<action>.html.erb. Missing template raises Belt::TemplateNotFound (no silent JSON fallback).
• Explicit helpers always win: success_response, error_response, html_response, render, head.

def create
  @post = Post.create!(...)
  response_status :created   # → 201 + { post: {...} }
end

Belt discovers controllers from the app's namespace module first, then searches Belt.all_controller_paths — which includes app-defined paths. No registration needed.

Belt provides global Belt::Observability::Logger and Belt::Observability::Metrics facades that are set automatically by Belt::LambdaHandler. Access them from anywhere:

Belt::Observability::Logger.info("Something happened", user_id: "123")
Belt::Observability::Metrics.track_event("OrderCreated", model: "Order")

Belt includes a command-line interface for project management.

Start an interactive Ruby console with your app loaded. Belt uses convention over configuration:

1. Loads lambda/config/environment.rb (your app's boot file — AWS setup, models, libs)
2. Starts IRB with reload! available
3. Reads .irbrc from the project root (console-specific customization)

belt console           # uses BELT_ENV or defaults to 'dev'
belt c prod            # specify environment explicitly
belt c dev02 --run "Customer.first"  # runner mode (execute and exit)

A production safety prompt is shown when the environment is prod.

Display route definitions from your infrastructure/routes.tf.rb. This is the primary way to inspect what endpoints your app exposes.

belt routes

Output (single namespace):

VERB    PATH                   CONTROLLER#ACTION
------------------------------------------------------------------
GET     /posts                 posts#index
GET     /posts/{post_id}       posts#show
POST    /posts                 posts#create
DELETE  /posts/{post_id}       posts#destroy

When multiple namespaces (API Gateways) exist, GATEWAY and LAMBDA columns are added automatically:

VERB    PATH              GATEWAY  LAMBDA  CONTROLLER#ACTION
---------------------------------------------------------------
GET     /posts            blog     blog    posts#index
POST    /posts            blog     blog    posts#create
GET     /posts            ops      ops     posts#index
POST    /posts            ops      ops     posts#create

# Filter routes by pattern
belt routes -g posts

# JSON output (for tooling/CI)
belt routes -f json

# Generate Ruby route constant for the "api" namespace
belt routes --namespace api

# Generate to a custom directory
belt routes --namespace api --output-dir lib/routes

# Include schema models in JSON output
belt routes -f json --schema infrastructure/schema.tf.rb

# Infer DynamoDB table access from Terraform
belt routes -f json --tables-file infrastructure/main.tf

With --format json, the output includes a routes array and optionally a models array (when a schema file is found):

{
  "routes": [
    {
      "name": "posts",
      "verb": "GET",
      "path": "/posts",
      "gateway": "api",
      "lambda": "api",
      "controller": "posts",
      "action": "index",
      "auth": "cognito",
      "tables": ["posts"],
      "request_model": "",
      "response_model": ""
    }
  ],
  "models": [
    {
      "name": "CreatePost",
      "kind": "request",
      "description": "Request model: CreatePost",
      "properties": {
        "title": { "type": "string" },
        "body": { "type": "string" }
      },
      "required": ["title"]
    }
  ]
}

With --namespace NAMESPACE, Belt generates a frozen Ruby constant file at lambda/lib/routes/<namespace>_routes.rb:

# frozen_string_literal: true

# Auto-generated by: belt routes --namespace api
# Do not edit manually

module Routes
  API = [
    {
      verb: "GET",
      path: "/posts",
      gateway: "api",
      lambda: "api",
      controller: "posts",
      action: "index",
      auth: "cognito",
      tables: ["posts"]
    }
  ].freeze
end

This is used by Belt::ActionRouter at runtime for request routing.

The command expects infrastructure/routes.tf.rb in the current working directory. Routes are defined using the same DSL as the Belt Terraform provider:

Belt.application.routes.draw do
  namespace :api do
    resources :posts, only: [:index, :show, :create, :destroy]
    resource :profile, only: [:show, :update]
    get "health", action: :health
  end
end

When --tables-file is provided, Belt parses aws_dynamodb_table resource blocks from your Terraform files and infers which tables each route accesses based on the resource name in the route path. Routes can also declare tables explicitly in the DSL via tables: [:posts, :comments].

Belt integrates automated pre-deploy backups directly into the deploy lifecycle. No standalone scripts, no generators — belt deploy handles everything.

This walks you through enabling backups for an existing Belt app from scratch.

Create infrastructure/<env>/belt.rb in your environment directory (e.g. infrastructure/prod/belt.rb):

# infrastructure/prod/belt.rb
Belt.configure do |config|
  config.backups do
    dynamodb :all
    retention snapshots: 90
  end
end

That's the minimum — every DynamoDB table in this environment will get an on-demand snapshot before each deploy, retained for 90 days. PITR (point-in-time recovery) will be verified as enabled.

belt deploy prod

Output:

━━━ pre-deploy backup ━━━
  📦 Creating backup bucket: my-app-backups-prod
  ✅ Backup bucket created and secured
  🔍 Verifying PITR: my-app-prod-posts → enabled ✓
  📸 Snapshot: my-app-prod-posts → my-app-prod-posts-20260723-170000 ✓
  🧹 Cleanup: 0 expired snapshots removed

━━━ terraform init ━━━
...

The backup bucket is created automatically on first run (versioned, public access blocked). Subsequent deploys reuse it.

As your app grows, add Cognito and S3 backups:

# infrastructure/prod/belt.rb
Belt.configure do |config|
  config.backups do
    dynamodb :all                    # On-demand snapshots + PITR verification
    cognito :users, :pool_config    # Export user list + pool settings to S3
    s3 :legal_documents             # Sync bucket contents to backup bucket
    retention snapshots: 90, cognito: 10, s3: 10
  end
end

Don't configure backups for dev environments — just omit the file or the backups block:

# infrastructure/dev01/belt.rb
Belt.configure do |config|
  # No backups block = no backups run during deploy
end

Or simply don't create infrastructure/dev01/belt.rb at all.

If you only need DynamoDB backups with all defaults:

# infrastructure/prod/belt.rb
Belt.configure do |config|
  config.backups = true
end

This enables DynamoDB snapshots for all tables with 90-day retention.

# Normal deploy (runs backups first if configured)
belt deploy prod

# Skip backups this time
belt deploy prod --skip-backup

# Just create a recovery point, don't deploy
belt deploy prod --backup-only

All DynamoDB tables generated by Belt include safety defaults:

point_in_time_recovery {
  enabled = var.enable_pitr  # true by default
}
deletion_protection_enabled = var.deletion_protection  # true in prod, false in dev

These are set via Terraform variables in each environment's terraform.tfvars. PITR gives you 35 days of continuous recovery regardless of the snapshot schedule.

1. Backup bucket — Belt creates <app-name>-backups-<env> on first run (versioned, public access blocked)
2. Table discovery — Table names are read from terraform output (requires at least one prior successful deploy)
3. DynamoDB — Verifies PITR is enabled, then creates an on-demand backup named <table>-<timestamp>
4. Cognito — Uses list-users (paginated) and describe-user-pool to export JSON to the backup bucket
5. S3 — Runs aws s3 sync from source bucket to s3://<backup-bucket>/s3/<bucket-name>/<timestamp>/
6. Cleanup — Removes snapshots/copies older than the configured retention

The backup phase reads table names from Terraform outputs. On a brand-new environment that has never been deployed, there are no outputs yet — Belt will warn and skip the backup phase gracefully. After the first successful deploy, backups run normally on subsequent deploys.

Belt is designed to stay lean. Optional capabilities ship as separate gems that plug into the CLI and runtime the same way Rails engines and generators do.

Install a plugin in a Belt app:

# Gemfile
gem "belt-messaging"
# gem "belt-pay"

bundle install
belt generate messaging   # or: belt g pay
belt generate --help      # lists built-ins + gem generators

No central registry file, no initializer hook. Belt discovers generators by scanning loaded gems:

1. Gem is in the app Gemfile and bundled
2. Gem ships a file at lib/belt/generators/<name>_generator.rb
3. Class lives in Belt::Generators, named <Name>Generator
4. Implements .run(args) (required), .destroy(args) and .description (optional)

That is the whole contract. After bundle install, belt generate <name> and belt destroy <name> just work.

See Belt::CLI::GeneratorRegistry and the CHANGELOG entry for 0.1.13 Generator Extension API.

belt-messaging/
├── belt-messaging.gemspec
├── lib/
│   ├── belt-messaging.rb              # require entrypoint
│   └── belt/
│       ├── messaging.rb               # Belt::Messaging API
│       ├── messaging/
│       │   ├── configuration.rb
│       │   ├── version.rb
│       │   ├── controllers/           # default controllers (optional)
│       │   └── templates/             # ERB templates for the generator
│       │       ├── terraform/
│       │       ├── lambda/
│       │       ├── config/
│       │       └── controllers/
│       └── generators/
│           └── messaging_generator.rb # ← auto-discovered
└── spec/

Runtime code stays in the gem. Generators copy only what the host app must own (Terraform modules, Lambda entrypoints, optional controller overrides). Prefer gem defaults + belt g <plugin> --controllers over dumping everything into the app (same idea as rails g devise:views).

Scaffold a ready-to-fill gem (Rails-style plugin new):

belt plugin new notifications
# → ./belt-notifications/

belt plugin new pay --path ~/Code --summary "Stripe payments for Belt"
# → ~/Code/belt-pay/

Then:

cd belt-notifications
bundle install
# implement lib/belt/notifications/* and the generator

Point a Belt app at it while developing:

# In the app Gemfile
gem "belt-notifications", path: "../belt-notifications"

bundle install
belt generate notifications

When packaging Lambdas, belt deploy vendors path gems into vendor/cache so conveyor-belt can package them.

A solid plugin generator typically:

1. Terraform module → infrastructure/modules/<name>/ (main.tf, variables.tf, outputs.tf)
2. Lambda config → config/lambda/<name>.yml (timeout, memory, env, triggers)
3. Lambda entrypoint → lambda/<name>.rb using Belt::LambdaHandler
4. Routes / schema → inject into config/routes.tf.rb or infrastructure/schema.tf.rb when needed
5. Optional overrides → --controllers flag for app-local subclasses
6. Destroy path → belt destroy <name> removes what generate created
7. Help text → .description + --help explaining what was installed and next steps

Copy from belt-messaging or belt-pay rather than inventing a new structure.

Bug reports and pull requests are welcome on GitHub.

git clone https://github.com/stowzilla/belt.git
cd belt
bundle install
bundle exec rspec
bundle exec rubocop

1. Branch from master — open a PR against master
2. Keep changes focused — one concern per PR when practical
3. Follow existing patterns — look at neighboring files and lib/belt/cli/ before inventing new ones
4. Tests + lint — run bundle exec rspec and bundle exec rubocop before opening (or updating) a PR. CI requires both (plus bundler-audit); failing checks block merge on master
5. Changelog — note user-facing changes in CHANGELOG.md under the next version / Unreleased
6. No secrets — never commit AWS keys, tokens, or real account IDs

AI / coding agents: start with AGENTS.md. Belt apps and plugins scaffolded by the CLI get their own AGENTS.md as well (belt new, belt plugin new).

# In a Belt app's Gemfile
gem "belt", path: "../belt"

belt deploy detects path: gems and materializes them into vendor/cache for Lambda packaging so you can iterate without publishing a gem for every try.

Plugins are separate repositories (not vendored into this repo). To add a new first-class capability:

1. belt plugin new <name> (or copy belt-messaging / belt-pay)
2. Implement the runtime API + generator contract above
3. Document install steps in the plugin README (gem … → belt generate …)
4. Open a PR on the plugin repo; optionally link it from this README's plugin table

Questions about plugin design or core changes: open a GitHub issue or discuss in the project Discord.

MIT