feat(health): expose running app version metadata

.github/workflows/ci.yml

@@ -102,6 +102,9 @@ jobs:
           platforms: linux/amd64
           push: true
           tags: ${{ steps.login-ecr.outputs.registry }}/${{ steps.ecr-repo.outputs.name }}:dev
+          build-args: |
+            APP_VERSION=dev
+            GIT_SHA=${{ github.sha }}
           provenance: false
           sbom: false
 
@@ -206,6 +209,9 @@ jobs:
           platforms: linux/amd64
           push: true
           tags: ${{ steps.meta.outputs.tags }}
+          build-args: |
+            APP_VERSION=${{ needs.detect-version.outputs.version || github.ref_name }}
+            GIT_SHA=${{ github.sha }}
           provenance: false
           sbom: false
 
@@ -266,6 +272,9 @@ jobs:
           platforms: linux/arm64
           push: true
           tags: ${{ steps.meta.outputs.tags }}
+          build-args: |
+            APP_VERSION=${{ needs.detect-version.outputs.version || github.ref_name }}
+            GIT_SHA=${{ github.sha }}
           provenance: false
           sbom: false
 

.github/workflows/images.yml

@@ -97,6 +97,9 @@ jobs:
           platforms: linux/amd64
           push: true
           tags: ${{ steps.meta.outputs.tags }}
+          build-args: |
+            APP_VERSION=${{ github.ref_name }}
+            GIT_SHA=${{ github.sha }}
           provenance: false
           sbom: false
 
@@ -143,6 +146,9 @@ jobs:
           platforms: linux/arm64
           push: true
           tags: ${{ steps.meta.outputs.tags }}
+          build-args: |
+            APP_VERSION=${{ github.ref_name }}
+            GIT_SHA=${{ github.sha }}
           provenance: false
           sbom: false
 

README.md

@@ -74,6 +74,12 @@ docker compose -f docker-compose.prod.yml up -d
 
 Open [http://localhost:3000](http://localhost:3000)
 
+Check the running app version and build metadata:
+
+```bash
+curl http://localhost:3000/api/health
+```
+
 Sim also supports local models via [Ollama](https://ollama.ai) and [vLLM](https://docs.vllm.ai/) — see the [Docker self-hosting docs](https://docs.sim.ai/self-hosting/docker) for setup details.
 
 ### Self-hosted: Manual Setup

apps/sim/.env.example

@@ -12,6 +12,8 @@ BETTER_AUTH_URL=http://localhost:3000
 NEXT_PUBLIC_APP_URL=http://localhost:3000
 # INTERNAL_API_BASE_URL=http://sim-app.default.svc.cluster.local:3000  # Optional: internal URL for server-side /api self-calls; defaults to NEXT_PUBLIC_APP_URL
 # TRUSTED_ORIGINS=https://www.example.com,https://app.example.com  # Optional: comma-separated additional public origins to trust for auth (apex+www, alias domains). Merged into Better Auth trustedOrigins.
+# APP_VERSION=v0.6.91  # Optional: shown by /api/health for self-hosted version checks
+# GIT_SHA=              # Optional: commit/build SHA shown by /api/health
 
 # Security (Required)
 ENCRYPTION_KEY=your_encryption_key  # Use `openssl rand -hex 32` to generate, used to encrypt environment variables

apps/sim/app/api/health/route.test.ts

@@ -1,17 +1,56 @@
 /**
  * @vitest-environment node
  */
-import { describe, expect, it } from 'vitest'
+import appPackage from '@/package.json'
+import { NextRequest } from 'next/server'
+import { afterEach, describe, expect, it } from 'vitest'
 import { GET } from '@/app/api/health/route'
 
+afterEach(() => {
+  process.env.APP_VERSION = ''
+  process.env.NEXT_PUBLIC_APP_VERSION = ''
+  process.env.GIT_SHA = ''
+  process.env.VERCEL_GIT_COMMIT_SHA = ''
+  process.env.COMMIT_SHA = ''
+})
+
 describe('GET /api/health', () => {
-  it('returns an ok status payload', async () => {
-    const response = await GET()
+  it('returns status with runtime version metadata', async () => {
+    process.env.APP_VERSION = 'v1.2.3'
+    process.env.GIT_SHA = 'abc123'
+
+    const response = await GET(new NextRequest('http://localhost/api/health'))
+
+    expect(response.status).toBe(200)
+    await expect(response.json()).resolves.toEqual({
+      status: 'ok',
+      timestamp: expect.any(String),
+      version: 'v1.2.3',
+      commit: 'abc123',
+    })
+  })
+
+  it('accepts query parameters from health-checking clients', async () => {
+    const response = await GET(new NextRequest('http://localhost/api/health?_=123'))
+
+    expect(response.status).toBe(200)
+  })
+
+  it('falls back to the package version when runtime metadata is not provided', async () => {
+    process.env.APP_VERSION = ''
+    process.env.NEXT_PUBLIC_APP_VERSION = ''
+    process.env.GIT_SHA = ''
+    process.env.VERCEL_GIT_COMMIT_SHA = ''
+    process.env.COMMIT_SHA = ''
+
+    const response = await GET(new NextRequest('http://localhost/api/health'))
 
     expect(response.status).toBe(200)
     await expect(response.json()).resolves.toEqual({
       status: 'ok',
       timestamp: expect.any(String),
+      version: appPackage.version,
+      commit: null,
     })
   })
 })

apps/sim/app/api/health/route.ts

@@ -1,11 +1,31 @@
+import type { NextRequest } from 'next/server'
+import { NextResponse } from 'next/server'
+import { healthContract } from '@/lib/api/contracts/health'
+import { parseRequest } from '@/lib/api/server'
+import appPackage from '@/package.json'
+
+const DEFAULT_VERSION = appPackage.version
+
+function getAppVersion(): string {
+  return process.env.APP_VERSION || process.env.NEXT_PUBLIC_APP_VERSION || DEFAULT_VERSION
+}
+
+function getAppCommit(): string | null {
+  return process.env.GIT_SHA || process.env.VERCEL_GIT_COMMIT_SHA || process.env.COMMIT_SHA || null
+}
+
 /**
  * Health check endpoint for deployment platforms and container probes.
  */
-export async function GET(): Promise<Response> {
-  return Response.json(
+export async function GET(request: NextRequest): Promise<Response> {
+  const parsed = await parseRequest(healthContract, request, {})
+  if (!parsed.success) return parsed.response
+  return NextResponse.json(
     {
       status: 'ok',
       timestamp: new Date().toISOString(),
+      version: getAppVersion(),
+      commit: getAppCommit(),
     },
     { status: 200 }
   )

apps/sim/lib/api/contracts/health.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod'
+import { defineRouteContract } from '@/lib/api/contracts/types'
+
+const healthQuerySchema = z.object({}).passthrough()
+export const healthResponseSchema = z.object({
+  status: z.literal('ok'),
+  timestamp: z.string(),
+  version: z.string(),
+  commit: z.string().nullable(),
+})
+
+export type HealthResponse = z.output<typeof healthResponseSchema>
+
+export const healthContract = defineRouteContract({
+  method: 'GET',
+  path: '/api/health',
+  query: healthQuerySchema,
+  response: {
+    mode: 'json',
+    schema: healthResponseSchema,
+  },
+})

apps/sim/lib/api/contracts/index.ts

@@ -14,6 +14,7 @@ export * from './environment'
 export * from './execution-payloads'
 export * from './file-uploads'
 export * from './folders'
+export * from './health'
 export * from './hotspots'
 export * from './inbox'
 export * from './media'

docker/app.Dockerfile

@@ -88,6 +88,8 @@ RUN --mount=type=cache,id=next-cache-${TARGETPLATFORM},target=/app/apps/sim/.nex
 FROM base AS runner
 WORKDIR /app
 
+ARG APP_VERSION="0.1.0"
+ARG GIT_SHA=""
 # Node.js 22, Python, ffmpeg, etc. are already installed in base stage
 ENV NODE_ENV=production
 
@@ -134,6 +136,8 @@ USER nextjs
 
 EXPOSE 3000
 ENV PORT=3000 \
-    HOSTNAME="0.0.0.0"
+    HOSTNAME="0.0.0.0" \
+    APP_VERSION=${APP_VERSION} \
+    GIT_SHA=${GIT_SHA}
 
 CMD ["bun", "apps/sim/server.js"]