Ship Replicated SDK for license enforcement with existing Helm charts

[jpshackelford]

Summary

We can start shipping the Replicated SDK as part of our existing Helm charts today, without waiting for the full Replicated Helm install migration. This enables license enforcement immediately for all customers.

Background

Currently we have two deployment paths:

1. Regular Helm Install - Customer downloads chart, runs helm install
2. Replicated Helm Install (in progress) - Customer uses helm install oci://registry.replicated.com/openhands/...

The assumption was that license enforcement requires the Replicated Helm install flow. This is incorrect.

Key Insight

The Replicated SDK is a standalone Helm subchart that:

• Deploys a small service at http://replicated:3000
• Authenticates with Replicated's backend using a license ID
• Caches license data locally
• Exposes license/entitlement APIs

The "Replicated Helm install" is just a convenience that auto-injects the license ID. We can achieve the same result by having customers manually provide their license ID.

Proposed Approach

1. Add Replicated SDK as Subchart

# charts/openhands/Chart.yaml
dependencies:
- name: replicated
  repository: oci://registry.replicated.com/library
  version: 1.9.0
  condition: replicated.enabled

2. Configure for Manual License ID

# charts/openhands/values.yaml
replicated:
  enabled: true
  integration:
    enabled: true      # SDK fetches license from Replicated backend
    licenseID: ""      # Customer MUST provide this

3. Customer Installation Flow

# Customer receives license ID from sales process (via Vendor Portal email)

# Install with license ID
helm install openhands ./openhands-chart \
  --set replicated.integration.licenseID=abc123def456 \
  --set replicated.integration.enabled=true

Migration Path

Phase	Install Method	License Enforcement
Phase 1 (Now)	Regular Helm + SDK subchart	✅ Customer provides license ID
Phase 2 (Future)	Replicated Helm install	✅ License auto-injected

Both phases use the same SDK API (http://replicated:3000), so application code doesn't change.

Benefits

1. Immediate enforcement - Don't wait for Replicated Helm migration
2. Same codebase - No special handling for "Replicated vs non-Replicated"
3. Smooth migration - Phase 2 is just removing --set flags
4. Full SDK features - Custom metrics, instance tracking, entitlements all work

Open Questions

Q1: How do customers get their license ID?

• Vendor Portal sends email with license ID when customer is created (already supported)

Q2: What happens if customer doesn't provide license ID?

• SDK should start, app should check and enforce at runtime

Q3: What about airgapped/offline customers?

• SDK has airgap mode where license is provided as a file

Q4: Does this expose our license enforcement to bypass?

• No more than full Replicated install. With signature verification using our vendor public key, customers cannot forge license data.

Implementation Tasks

OpenHands-Cloud (Helm Charts)

• Add replicated subchart dependency to Chart.yaml
• Add replicated.* values to values.yaml with sensible defaults
• Add validation hook to check replicated.integration.licenseID is provided
• Document license ID requirement in install instructions
• Embed vendor public key as Secret for signature verification

OpenHands/OpenHands (Enterprise Server)

• Add license enforcement module (query SDK API)
• Add decorators for protecting premium features
• Add /api/license-status endpoint for UI
• Add startup check for SDK availability

Related

• Telemetry Design Doc
• Replicated SDK API Reference
• SDK Installation Docs

---

This issue was created by an AI agent (OpenHands) on behalf of the user.

[jlav]

If we just want to go to the "Replicated Helm install", it's just a matter of pointing to the replicated registry.

So instead of:

helm install openhands ghcr.io/all-hands-ai/helm-charts/openhands \
  --set replicated.integration.licenseID=abc123def456 \
  --set replicated.integration.enabled=true

They log into the registry and run the install command but point at registry.replicated.com

helm install openhands oci://registry.replicated.com/openhands/stable/openhands

I'm not sure I see the point in jumping only half way?

[jpshackelford]

I'm not holding in my head everything we have to do to support replicated helm install and may not have an accurate picture. I am thinking about this from the perspective of, this is something we could do to start referencing license file next week instead of four to six weeks from now. May not be an accurate picture, but seeing a window opportunity for a process change that I could execute with a customer now before we have a new batch helm installs from POCs start. Counter proposals welcome.

[jlav]

My proposal is that instead of telling a customer to manually wire up their license key via replicated.integration.licenseID=abc123def456, we have the customer download the charts directly from replicated's private registry. It's the exact same chart underneath the hood, except replicated injects the customer's license information for us.

The customer's page in Replicated will give them a login command for the private registry:

helm registry login charts.r9.all-hands.dev --username customer@acmecorp.dev --password ...

Then they can install the charts with

helm install openhands oci://charts.r9.all-hands.dev/openhands/stable/openhands --version 0.4.8

If a customer goes from executing this

helm upgrade openhands ghcr.io/all-hands-ai/helm-charts/openhands --version 0.4.8

to this instead

helm upgrade openhands oci://charts.r9.all-hands.dev/openhands/stable/openhands --version 0.4.8

it's fine. Helm releases are identified by their name, not the chart source, so the migration to replicated's registry isn't anymore difficult than that.

This doesn't take any additional time than your proposal.

[jlav]

I checked off Add replicated subchart dependency to Chart.yaml since that's already true today.

With my proposal, the new chart task list becomes

- [] Default to `enabled` for the replicated SDK
- [] Enable helm install on the Stable release channel (this is just a checkbox in replicated's admin console)
- [] Document private registry login