chore(rivetkit): remove legacy metrics & prometheus auth

Author: NathanFlurry

.agent/notes/inspector-security-audit.md

@@ -13,7 +13,7 @@ Audited the native Rust inspector HTTP/WebSocket surface in `rivetkit-rust/packa
 - Rust HTTP `/inspector/*` routes call `InspectorAuth::verify(...)` before route dispatch.
 - Rust inspector WebSocket `/inspector/connect` verifies the `rivet_inspector_token.*` websocket protocol token first, then falls back to `Authorization: Bearer ...`.
 - TypeScript native HTTP `/inspector/*` routes call `ctx.verifyInspectorAuth(...)`, which delegates to the same core `InspectorAuth`.
-- `InspectorAuth` prefers `RIVET_INSPECTOR_TOKEN` when configured. If absent, it falls back to the per-actor KV token at key `[3]`.
+- `InspectorAuth` prefers `_RIVET_TEST_INSPECTOR_TOKEN` (test-only override, not public) when configured. If absent, it falls back to the per-actor KV token at key `[3]`, which is the production auth path.
 - Fixed in US-094: Rust bearer parsing now matches TS more closely by accepting case-insensitive `Bearer` and arbitrary whitespace after the scheme.
 
 ## HTTP Endpoint Matrix

frontend/src/components/actors/guard-connectable-inspector.tsx

@@ -1101,6 +1101,8 @@ impl ActorTask {
 	}
 
 	async fn start_actor(&mut self) -> Result<()> {
+		let startup_started_at = Instant::now();
+		let actor_id = self.ctx.actor_id().to_owned();
 		if !self.ctx.started() {
 			self.ctx.configure_sleep(self.factory.config().clone());
 			self.ctx
@@ -1110,7 +1112,13 @@ impl ActorTask {
 		self.ctx.configure_actor_events(self.actor_event_tx.clone());
 		self.ctx.configure_queue_preload(self.preloaded_kv.clone());
 
+		let load_state_started_at = Instant::now();
 		let persisted = self.load_persisted_startup().await?;
+		tracing::debug!(
+			actor_id = %actor_id,
+			duration_ms = duration_ms_f64(load_state_started_at.elapsed()),
+			"perf internal: loadStateMs"
+		);
 		let is_new = !persisted.actor.has_initialized;
 		self.ctx.load_persisted_actor(persisted.actor);
 		self.ctx.load_last_pushed_alarm(persisted.last_pushed_alarm);
@@ -1119,9 +1127,15 @@ impl ActorTask {
 			.persist_state(SaveStateOpts { immediate: true })
 			.await
 			.context("persist actor initialization")?;
+		let init_inspector_token_started_at = Instant::now();
 		crate::inspector::init_inspector_token(&self.ctx)
 			.await
 			.context("initialize inspector token")?;
+		tracing::debug!(
+			actor_id = %actor_id,
+			duration_ms = duration_ms_f64(init_inspector_token_started_at.elapsed()),
+			"perf internal: initInspectorTokenMs"
+		);
 		self.ctx
 			.restore_hibernatable_connections_with_preload(self.preloaded_kv.as_ref())
 			.await
@@ -1135,6 +1149,12 @@ impl ActorTask {
 		self.spawn_run_handle(is_new).await?;
 		self.reset_sleep_deadline().await;
 		self.ctx.drain_overdue_scheduled_events().await?;
+		tracing::debug!(
+			actor_id = %actor_id,
+			duration_ms = duration_ms_f64(startup_started_at.elapsed()),
+			is_new,
+			"perf internal: startupTotalMs"
+		);
 		Ok(())
 	}
 
@@ -2041,3 +2061,7 @@ fn result_outcome<T>(result: &Result<T>) -> &'static str {
 fn state_delta_payload_bytes(deltas: &[StateDelta]) -> usize {
 	deltas.iter().map(StateDelta::payload_len).sum()
 }
+
+fn duration_ms_f64(duration: Duration) -> f64 {
+	duration.as_secs_f64() * 1000.0
+}

rivetkit-rust/packages/rivetkit-core/src/actor/task.rs

@@ -7,7 +7,9 @@ use serde::{Deserialize, Serialize};
 use crate::ActorContext;
 
 const INSPECTOR_TOKEN_KEY: [u8; 1] = [3];
-const INSPECTOR_TOKEN_ENV: &str = "RIVET_INSPECTOR_TOKEN";
+/// Test-only override. Not a public/production auth mechanism; production
+/// inspector auth goes through the per-actor KV token at key [3].
+const INSPECTOR_TOKEN_ENV: &str = "_RIVET_TEST_INSPECTOR_TOKEN";
 const INSPECTOR_TOKEN_BYTES: usize = 32;
 
 #[derive(Clone, Copy, Debug, Default)]
@@ -53,9 +55,9 @@ impl InspectorAuth {
 /// Ensures the actor has an inspector token persisted in KV at `[3]` so the
 /// engine-facing KV API can serve the token to the dashboard inspector.
 /// Skips the write when the token already exists. No-ops when the
-/// `RIVET_INSPECTOR_TOKEN` env override is set, since that takes precedence
-/// over any KV-stored token and we do not want to pin a per-actor token that
-/// will never be consulted.
+/// `_RIVET_TEST_INSPECTOR_TOKEN` env override is set, since that takes
+/// precedence over any KV-stored token and we do not want to pin a per-actor
+/// token that will never be consulted.
 pub async fn init_inspector_token(ctx: &ActorContext) -> Result<()> {
 	if std::env::var(INSPECTOR_TOKEN_ENV)
 		.ok()

rivetkit-rust/packages/rivetkit-core/src/inspector/auth.rs

@@ -77,6 +77,9 @@ impl RegistryDispatcher {
 			FrameworkHttpRoute::Queue(name) => {
 				self.handle_queue_fetch(instance, request, name).await
 			}
+			FrameworkHttpRoute::Metadata => handle_metadata_fetch(&request),
+			FrameworkHttpRoute::Health => handle_health_fetch(&request),
+			FrameworkHttpRoute::Root => handle_root_fetch(&request),
 		}
 	}
 
@@ -330,7 +333,7 @@ impl RegistryDispatcher {
 		instance: &ActorTaskHandle,
 		request: &HttpRequest,
 	) -> Result<HttpResponse> {
-		if !request_has_bearer_token(request, self.inspector_token.as_deref()) {
+		if !request_has_bearer_token(request, self.metrics_token.as_deref()) {
 			return Ok(unauthorized_response());
 		}
 
@@ -358,6 +361,9 @@ impl RegistryDispatcher {
 pub(super) enum FrameworkHttpRoute {
 	Action(String),
 	Queue(String),
+	Metadata,
+	Health,
+	Root,
 }
 
 pub(super) struct DecodedHttpQueueRequest {
@@ -377,7 +383,75 @@ pub(super) fn framework_http_route(path: &str) -> Result<Option<FrameworkHttpRou
 			percent_decode_path_segment(segment)?,
 		)));
 	}
-	Ok(None)
+	match path {
+		"/metadata" => Ok(Some(FrameworkHttpRoute::Metadata)),
+		"/health" => Ok(Some(FrameworkHttpRoute::Health)),
+		"/" => Ok(Some(FrameworkHttpRoute::Root)),
+		_ => Ok(None),
+	}
+}
+
+fn handle_metadata_fetch(request: &Request) -> Result<HttpResponse> {
+	if request.method() != http::Method::GET {
+		return method_not_allowed_response(request);
+	}
+	let runtime_type = if std::env::var("NODE_ENV").as_deref() == Ok("production") {
+		"deployed"
+	} else {
+		"local"
+	};
+	json_http_response(
+		StatusCode::OK,
+		&serde_json::json!({
+			"runtime": "rivetkit",
+			"version": env!("CARGO_PKG_VERSION"),
+			"type": runtime_type,
+		}),
+	)
+}
+
+fn handle_health_fetch(request: &Request) -> Result<HttpResponse> {
+	if request.method() != http::Method::GET {
+		return method_not_allowed_response(request);
+	}
+	text_response(StatusCode::OK, "ok")
+}
+
+fn handle_root_fetch(request: &Request) -> Result<HttpResponse> {
+	if request.method() != http::Method::GET {
+		return method_not_allowed_response(request);
+	}
+	text_response(
+		StatusCode::OK,
+		"This is an RivetKit actor.\n\nLearn more at https://rivetkit.org",
+	)
+}
+
+fn text_response(status: StatusCode, body: &str) -> Result<HttpResponse> {
+	let mut headers = HashMap::new();
+	headers.insert(
+		http::header::CONTENT_TYPE.to_string(),
+		"text/plain; charset=utf-8".to_owned(),
+	);
+	Ok(HttpResponse {
+		status: status.as_u16(),
+		headers,
+		body: Some(body.as_bytes().to_vec()),
+		body_stream: None,
+	})
+}
+
+fn method_not_allowed_response(request: &Request) -> Result<HttpResponse> {
+	let encoding = request_encoding(request.headers());
+	message_boundary_error_response(
+		encoding,
+		framework_error_status("actor", "method_not_allowed"),
+		MethodNotAllowed {
+			method: request.method().to_string(),
+			path: request.uri().path().to_owned(),
+		}
+		.build(),
+	)
 }
 
 pub(super) fn single_path_segment<'a>(path: &'a str, prefix: &str) -> Option<&'a str> {

rivetkit-rust/packages/rivetkit-core/src/registry/http.rs

@@ -121,7 +121,9 @@ pub(crate) struct RegistryDispatcher {
 	starting_instances: SccHashMap<String, Arc<Notify>>,
 	pending_stops: SccHashMap<String, PendingStop>,
 	region: String,
-	inspector_token: Option<String>,
+	/// Shared secret gating the Prometheus `/metrics` actor endpoint. When
+	/// unset, the endpoint fails closed and is effectively disabled.
+	metrics_token: Option<String>,
 	handle_inspector_http_in_runtime: bool,
 }
 
@@ -479,7 +481,7 @@ impl RegistryDispatcher {
 			starting_instances: SccHashMap::new(),
 			pending_stops: SccHashMap::new(),
 			region: env::var("RIVET_REGION").unwrap_or_default(),
-			inspector_token: env::var("RIVET_INSPECTOR_TOKEN")
+			metrics_token: env::var("_RIVET_METRICS_TOKEN")
 				.ok()
 				.filter(|token| !token.is_empty()),
 			handle_inspector_http_in_runtime,

rivetkit-rust/packages/rivetkit-core/src/registry/mod.rs

@@ -38,8 +38,6 @@ export const getRivetPublicToken = (): string | undefined =>
 // use different namespaces
 
 // RivetKit configuration
-export const getRivetkitInspectorToken = (): string | undefined =>
-	getEnvUniversal("RIVET_INSPECTOR_TOKEN");
 export const getRivetkitInspectorDisable = (): boolean =>
 	getEnvUniversal("RIVET_INSPECTOR_DISABLE") === "1";
 export const getRivetkitStoragePath = (): string | undefined =>

rivetkit-typescript/packages/rivetkit/src/utils/env-vars.ts

@@ -802,89 +802,5 @@ describeDriverMatrix("Actor Inspector", (driverTestConfig) => {
 			expect(response.status).toBe(401);
 		});
 
-		test("GET /inspector/metrics returns startup metrics", async (c) => {
-			const { client } = await setupDriverTest(c, driverTestConfig);
-			const handle = client.counter.getOrCreate(["inspector-metrics"]);
-
-			// Ensure actor exists
-			await handle.increment(0);
-
-			const gatewayUrl = await handle.getGatewayUrl();
-
-			const response = await fetch(
-				buildInspectorUrl(gatewayUrl, "/inspector/metrics"),
-				{
-					headers: { Authorization: "Bearer token" },
-				},
-			);
-			expect(response.status).toBe(200);
-			const data: any = await response.json();
-
-			// Verify startup metrics are present and have reasonable values
-			expect(data.startup_total_ms).toBeDefined();
-			expect(data.startup_total_ms.type).toBe("gauge");
-			expect(data.startup_total_ms.value).toBeGreaterThan(0);
-
-			expect(data.startup_kv_round_trips).toBeDefined();
-			expect(data.startup_kv_round_trips.type).toBe("gauge");
-			expect(data.startup_kv_round_trips.value).toBeGreaterThanOrEqual(0);
-
-			expect(data.startup_is_new).toBeDefined();
-			expect(data.startup_is_new.type).toBe("gauge");
-
-			// Verify internal metrics exist
-			expect(data.startup_internal_load_state_ms).toBeDefined();
-			expect(
-				data.startup_internal_load_state_ms.value,
-			).toBeGreaterThanOrEqual(0);
-			expect(data.startup_internal_init_queue_ms).toBeDefined();
-			expect(data.startup_internal_init_inspector_token_ms).toBeDefined();
-
-			// Verify user metrics exist
-			expect(data.startup_user_create_vars_ms).toBeDefined();
-			expect(data.startup_user_on_wake_ms).toBeDefined();
-			expect(data.startup_user_create_state_ms).toBeDefined();
-
-			// Verify existing KV metrics still present
-			expect(data.kv_operations).toBeDefined();
-			expect(data.kv_operations.type).toBe("labeled_timing");
-		});
-
-		test("GET /inspector/metrics returns sqlite commit phase metrics", async (c) => {
-			const { client } = await setupDriverTest(c, driverTestConfig);
-			const handle = client.dbActorRaw.getOrCreate([
-				`inspector-sqlite-metrics-${crypto.randomUUID()}`,
-			]);
-
-			await handle.insertValue("hello");
-
-			const gatewayUrl = await handle.getGatewayUrl();
-			const response = await fetch(
-				buildInspectorUrl(gatewayUrl, "/inspector/metrics"),
-				{
-					headers: { Authorization: "Bearer token" },
-				},
-			);
-			expect(response.status).toBe(200);
-			const data: any = await response.json();
-
-			expect(data.sqlite_commit_phases).toBeDefined();
-			expect(data.sqlite_commit_phases.type).toBe("labeled_timing");
-			expect(
-				data.sqlite_commit_phases.values.request_build.calls,
-			).toBeGreaterThan(0);
-			expect(
-				data.sqlite_commit_phases.values.request_build.totalMs,
-			).toBeGreaterThan(0);
-			expect(
-				data.sqlite_commit_phases.values.serialize.totalMs,
-			).toBeGreaterThan(0);
-			expect(
-				data.sqlite_commit_phases.values.transport.totalMs,
-			).toBeGreaterThan(0);
-			expect(
-				data.sqlite_commit_phases.values.state_update.totalMs,
-			).toBeGreaterThan(0);
-		});
 	});
 });

rivetkit-typescript/packages/rivetkit/tests/driver/actor-inspector.test.ts

@@ -269,11 +269,13 @@ Standard actor endpoints (health, actions, requests) and inspector endpoints hav
 
 #### Inspector Endpoints
 
+Each actor generates a unique inspector token on first start and persists it in its internal KV store at key `0x03` (base64 `Aw==`). Pass it as a bearer token in the `Authorization` header.
+
 | Environment | Authentication |
 |---|---|
-| **Local development** | No authentication required if `RIVET_INSPECTOR_TOKEN` is not set. A warning is logged. |
-| **Self-hosted engine** | Set the `RIVET_INSPECTOR_TOKEN` environment variable. Pass it as a bearer token in the `Authorization` header. The actor-specific inspector token used by the standalone Inspector UI is also accepted. |
-| **Rivet Cloud** | Token is required. Pass it as a bearer token in the `Authorization` header. The actor-specific inspector token used by the standalone Inspector UI is also accepted. |
+| **Local development** | No authentication required. |
+| **Self-hosted engine** | Bearer the actor's inspector token in the `Authorization` header. The Rivet dashboard fetches it automatically; for direct API access, fetch it through the management KV endpoint (see below). |
+| **Rivet Cloud** | Bearer the actor's inspector token in the `Authorization` header. The Rivet dashboard fetches it automatically; for direct API access, fetch it through the management KV endpoint (see below). |
 
 ```bash
 curl "$RIVET_API/gateway/{actor_id}/inspector/summary" \

website/src/content/docs/actors/debugging.mdx

@@ -41,9 +41,14 @@ These variables configure how clients connect to your actors.
 
 | Environment Variable | Description |
 |---------------------|-------------|
-| `RIVET_INSPECTOR_TOKEN` | Token for accessing the Rivet Inspector |
 | `RIVET_INSPECTOR_DISABLE` | Set to `1` to disable the inspector |
 
+## Metrics
+
+| Environment Variable | Description |
+|---------------------|-------------|
+| `_RIVET_METRICS_TOKEN` | Bearer token that gates the per-actor Prometheus `/metrics` endpoint. When unset, `/metrics` is disabled. |
+
 ## Experimental
 
 | Environment Variable | Description |