# Install the Bugstack Ruby SDK

The gem reports uncaught server errors to Bugstack, which starts a fix. Setup for Rails, Sinatra and plain Ruby, with the full config reference.

## Compatibility

Ruby 3.0+

Fixes for Ruby apps arrive as pull requests for your review. Bugstack’s verification sandbox does not run Ruby yet, so Autopilot does not merge Ruby fixes on its own.

## Install

Gemfile

```
gem 'bugstack', '~> 1.0'
```

Then run:

```
bundle install
```

Or install directly:

```
gem install bugstack
```

## Initialize

Call `Bugstack.init` once at startup with your API key and the Bugstack endpoint. Pass `endpoint` explicitly: the published gem does not default to it yet. Options can also be set in a block (`Bugstack.init { |config| config.endpoint = "..." }`).

```
require "bugstack"

Bugstack.init(
  api_key: ENV["BUGSTACK_API_KEY"],
  endpoint: ENV.fetch("BUGSTACK_ENDPOINT", "https://dashboard.bugstack.ai/api/ingest/sdk")
)

begin
  process_job(job)
rescue => e
  Bugstack.capture_exception(e, metadata: { job: job.id })
  raise
end
```

## Rails

One initializer loads the Rails integration, initializes Bugstack, and places its middleware inside Rails' own error pages. The gem's automatic placement sits outside them, where a production Rails app has already turned the exception into an error page, so nothing would be reported.

```
# config/initializers/bugstack.rb
require "bugstack/integrations/rails"

Bugstack.init(
  api_key: ENV["BUGSTACK_API_KEY"],
  endpoint: ENV.fetch("BUGSTACK_ENDPOINT", "https://dashboard.bugstack.ai/api/ingest/sdk")
)

# Inside Rails' own error pages, so bugstack sees the error before they answer it:
Rails.application.config.middleware.insert_after(
  ActionDispatch::DebugExceptions,
  Bugstack::Integrations::RackMiddleware
)
```

## Sinatra

The extension reports the error and re-raises it, so Sinatra's own handling still runs.

```
require "bugstack"
require "bugstack/integrations/sinatra"

Bugstack.init(
  api_key: ENV["BUGSTACK_API_KEY"],
  endpoint: ENV.fetch("BUGSTACK_ENDPOINT", "https://dashboard.bugstack.ai/api/ingest/sdk")
)

class App < Sinatra::Base
  register Bugstack::Integrations::Sinatra
  # ... your routes
end
```

## Plain Ruby

For workers, scripts or any other Ruby process, report errors where you handle them, as in Initialize above. The gem also has an at\_exit hook (`require "bugstack/integrations/generic"`, then `Bugstack::Integrations::Generic.install!`), but reports are sent from a background thread, so an exception that ends the process can exit before it is sent.

## Configuration Reference

Every option is a keyword argument to `Bugstack.init`, or a setter in its block.

Option

Type

Default

Description

`api_key`

String

—

Required. Your project API key (starts `bsk_`).

`endpoint`

String

a placeholder address

Where reports go. Set it to `https://dashboard.bugstack.ai/api/ingest/sdk`.

`project_id`

String

`""`

Explicit project identifier.

`environment`

String

`"production"`

Environment name sent with each report.

`enabled`

Boolean

`true`

Master switch for error capture.

`debug`

Boolean

`false`

Log SDK activity to STDERR.

`dry_run`

Boolean

`false`

Log errors instead of sending them.

`deduplication_window`

Float

`300.0`

Seconds during which the same error is sent only once. Bugstack also folds repeats within 24 hours.

`timeout`

Float

`5.0`

HTTP timeout in seconds.

`max_retries`

Integer

`3`

Attempts per report, with backoff (1s, 2s).

`ignored_errors`

Array

`[]`

Exception classes, or substrings of messages, not to report.

`before_send`

Proc

`nil`

Change an event before it is sent, or return `nil` to drop it.

`auto_fix`

Boolean

`false`

Sent with each report. What Bugstack does with a fix is set by the repository's autonomy level in Bugstack, not by this flag.

## Data Control

### before\_send hook example

Drop errors from a health check:

```
Bugstack.init(
  api_key: ENV.fetch("BUGSTACK_API_KEY"),
  endpoint: "https://dashboard.bugstack.ai/api/ingest/sdk",
  # Drop errors from the health check; send everything else.
  before_send: ->(event) {
    event.request && event.request[:route] == "/health" ? nil : event
  },
)
```

### dry\_run mode

Test your setup without sending anything:

```
Bugstack.init(
  api_key: ENV.fetch("BUGSTACK_API_KEY"),
  endpoint: "https://dashboard.bugstack.ai/api/ingest/sdk",
  dry_run: true, # log each event instead of sending it
  debug: true,
)
```

## Next Steps

-   [Ruby SDK Reference](/docs/sdk/ruby)
-   [Privacy & Data Handling](/docs/privacy)
-   [How Bugstack Works Under the Hood](/docs/how-it-works)
-   [Ruby SDK Overview](/for/ruby)

## Get started

Sign up with GitHub and start the 14-day trial, or book a demo and we set it up with you. Once the SDK is in, an uncaught server error starts a fix: specialist agents work out the cause and write a small change, it arrives as a pull request that runs through your CI, and what happens next depends on the autonomy level you set. Connecting the repository also starts repository scanning.

[Get started](https://dashboard.bugstack.ai/login) [Book a demo](/demo)