Hud self-hosted

With Hud self-hosted, Hud's data stays in your own OpenSearch stack. The Hud SDK sends function-level metrics and forensics over OpenTelemetry (OTLP) to your collector, and they're stored in OpenSearch and Prometheus, in your account. Hud runs only the control plane: your account, your API keys and the SDK's sessions.

When to choose self-hosted

Choose self-hosted when:

• Your data has to stay in your account, for compliance or because you want to own it.
• You already run OpenSearch and want Hud's data next to your logs and traces.

If neither applies, the Hud managed setup is simpler. Hud stores and analyzes the data for you, and you get the full Hud web app, including the pages that show your data.

How it works

1. Your service runs the Hud SDK, which measures every function and endpoint and captures forensics when a request fails or runs slow.
2. The SDK exports metrics and forensics over OTLP to your OpenTelemetry collector. You give it the collector's URL when you install it.
3. The collector writes forensics to OpenSearch and metrics to Prometheus.
4. Hud's dashboards show that data in OpenSearch Dashboards, inside your stack.
5. If you turn on the PR checks, Hud reads that data from your stack through a read-only IAM role in your AWS account.
6. The SDK contacts Hud only for the control plane: your account, your API keys and its session.

What stays in your account and what Hud handles

The SDK doesn't send your metrics or forensics to Hud. Forensics can include request details, so this is the part that matters for most security reviews.

If you turn on the PR checks, Hud also reads Hud's data in your stack, through a read-only role that you create and can revoke at any time. Step 5 of the setup below shows how. If your security team has questions about the PR checks, chat with our support team.

What you get

• Function-level metrics: a count of every function call, sampled durations and exceptions for every function, and requests, durations and status codes for every endpoint, in Prometheus.
• Forensics: when a request fails or runs slow, a record of the request, the exception and the code path that led to it, in OpenSearch.
• Dashboards: Hud's dashboards, in OpenSearch Dashboards.
• PR checks: Hud reviews your pull requests against how your code runs, with PR risk check. It can approve the safe ones with Policy approval and merge them with Merge when approved.

The web app in self-hosted mode

The web app doesn't show your data, because your data stays in your stack. After the install it shows only Settings. The OpenSearch page is where you finish the setup, GitHub is the only integration, and your AI provider and repository settings are under Agentic Workflows. You work with the data itself in OpenSearch Dashboards.

The prompt on the Self-hosted tab sets the SDK up to export to your collector.

Before you start

• A Hud account. You create it in step 1.
• OpenSearch for forensics and Prometheus for metrics, with an OpenTelemetry collector that accepts OTLP, at a URL your service can reach. The SDK exports metrics with delta temporality and Prometheus doesn't accept delta, so the collector needs the deltatocumulative processor before the Prometheus exporter. Hud doesn't change how you run them. To set up OpenSearch, see OpenSearch's installation guide. ClickHouse support is coming soon.
• A service written in Node.js, Python or Java that you can run on your machine, and a coding agent that can read your repository and run commands, such as Claude Code, Cursor or Codex.
• For the PR checks: OpenSearch running on AWS, in Amazon OpenSearch Service with an OpenSearch UI application, because Hud reaches it through an IAM role; an AWS account where you can create that role; a GitHub repository; and an account with an AI provider, Anthropic or Amazon Bedrock.

Set up in seven steps

1. Sign up and choose Self-hosted. Go to app.hud.io and sign up. On the install page, choose the Self-hosted tab. The other tab is Hud managed.

2. Set your collector's URL and your key. The page shows a prompt for your coding agent. It includes the line OTEL_EXPORTER_OTLP_ENDPOINT=<your-collector-url>. Replace <your-collector-url> with the URL of your OpenTelemetry collector, so the SDK knows where to send its data. The page also shows three API keys: local, staging and production, one for each environment. For your first install, use the local key. In the terminal where you start your agent, run:

   Bash

   export HUD_KEY=<your local key>

3. Paste the prompt into your agent. Paste it in the repository of the service you want to cover. The agent checks the repository, installs the SDK and points it at your collector. The install page moves on by itself once Hud detects the SDK, and a progress page then follows the SDK as it reports in.

4. Explore Hud's data in OpenSearch Dashboards. When the install is complete, choose Set up Hud with OpenSearch. It opens Settings → OpenSearch, which stays in Settings after the install. Under Explore Hud runtime data in OpenSearch dashboard, copy the command and run it in the OpenSearch CLI.

   Steps 5 to 7 turn on the PR checks. Skip them if you only want Hud's data in your stack.

5. Give Hud read-only access. Under IAM role, select Configure and follow the steps on the card. You create the role in your AWS account with Hud's CloudFormation stack, then enter its Role ARN, your AWS Region and the URL of your OpenSearch UI application, which starts with application- and ends with .opensearch.amazonaws.com. Test the connection and save. The test runs one read-only search on your forensics. Hud uses the role with short-lived credentials, and you can revoke it at any time.

6. Connect GitHub and your AI provider. The third section on the page, Connect to catch risky PRs and unlock safe auto-merge, lists GitHub integration and AI Provider. Connect both. PR risk check and AI provider have the steps for each.

7. Turn on the PR checks. In Settings → Agentic Workflows, link your services to the repository and turn on the review, as in PR risk check. Then turn on Auto approve PRs (Policy approval) and Merge when approved (Merge when approved) if you want Hud to approve and merge the safe PRs for you.

If something doesn't work

• The install page keeps waiting for the SDK. Check that the service is running and that HUD_KEY is set in the terminal where it runs.
• The progress page stops. Check that the service is still running and can reach your collector's URL.
• The role test can't assume the role. Check that the role's trust policy requires your account's External ID.
• OpenSearch refuses the request. Hud assumed the role, but OpenSearch said no. Check the role mapping and the access policy on your OpenSearch domain.
• Hud can't reach the endpoint. Check the URL of your OpenSearch UI application.
• Anything else. Chat with our support team or email [email protected].