Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

Update instructions for TRUEFORGE_API_KEY

Chirag Jain6820d0af469d
diff --git a/.railway/README.md b/.railway/README.md
index 989ed3b89..5375b3a89 100644
--- a/.railway/README.md
+++ b/.railway/README.md
@@ -8,9 +8,15 @@ railway login
railway init --name trueforge # or: railway link to an existing project
railway config plan
railway config apply
+# Set shared TRUEFORGE_API_KEY once (Project Settings → Shared Variables), e.g.
+# openssl rand -hex 32
+# railway variable set TRUEFORGE_API_KEY --stdin --skip-deploys
+# then re-apply or redeploy so trueforge + trueforge-controller pick it up.
railway domain # public URL for the trueforge service
```
-`RAILWAY_DOCKERFILE_PATH=Dockerfile.dev` selects the from-source image (`STANDALONE=false` and `HOST=0.0.0.0` are baked into that file). Auth is **off** by default — anyone who can reach the URL is admin. Before sharing a deployment, enable [OIDC login](https://trueforge.dev/authentication/overview) (optional shared-variable block is commented in `railway.ts`).
+- **Image:** `RAILWAY_DOCKERFILE_PATH=Dockerfile.dev` selects the from-source build.
+- **API key:** Set `TRUEFORGE_API_KEY` yourself as a Railway shared variable. IaC only wires `${{shared.TRUEFORGE_API_KEY}}` onto `trueforge` and `trueforge-controller`.
+- **Auth:** Off by default — anyone who can reach the URL is admin. Before sharing a deployment, enable [OIDC login](https://trueforge.dev/authentication/overview) (optional shared-variable block is commented in `railway.ts`).
See [Railway Infrastructure as Code](https://docs.railway.com/infrastructure-as-code). Do not add a root `railway.toml` / `railway.json` — those conflict with this file.
diff --git a/.railway/railway.ts b/.railway/railway.ts
index 264b7409c..d94a378db 100644
--- a/.railway/railway.ts
+++ b/.railway/railway.ts
@@ -7,6 +7,9 @@
* railway init --name trueforge # or: railway link
* railway config plan
* railway config apply
+ * # Shared TRUEFORGE_API_KEY once (Project Settings → Shared Variables), then
+ * # re-apply or redeploy so both services pick it up. Example value:
+ * # openssl rand -hex 32
* railway domain # public URL for the trueforge service
*
* Docs: https://docs.railway.com/infrastructure-as-code
@@ -46,6 +49,8 @@ export default defineRailway(_ctx => {
REDIS_URL: cache.env.REDIS_URL,
// Expanded by Railway at runtime once a public domain exists on this service.
PUBLIC_BASE_URL: 'https://${{RAILWAY_PUBLIC_DOMAIN}}',
+ // Set once in Railway (shared); IaC only references it — see header.
+ TRUEFORGE_API_KEY: _ctx.shared.TRUEFORGE_API_KEY,
// Optional OIDC (login off until these are set). Create matching *shared*
// variables on the Railway environment, uncomment, then `railway config apply`.
@@ -80,6 +85,8 @@ export default defineRailway(_ctx => {
RAILWAY_DOCKERFILE_PATH: 'Dockerfile.dev',
STANDALONE: 'false',
DATABASE_URL: db.env.DATABASE_URL,
+ // Same shared key as the app (Bearer auth for schedule dispatch).
+ TRUEFORGE_API_KEY: _ctx.shared.TRUEFORGE_API_KEY,
// Reaches the app over Railway private networking (no public egress).
SERVER_URL: 'http://${{trueforge.RAILWAY_PRIVATE_DOMAIN}}:${{trueforge.PORT}}',
},
diff --git a/charts/trueforge/README.md b/charts/trueforge/README.md
index 1ff547f38..2505a3dd4 100644
--- a/charts/trueforge/README.md
+++ b/charts/trueforge/README.md
@@ -21,12 +21,14 @@ Those defaults are **not** production-safe:
| Default | Risk if the Service / Ingress is reachable |
| --- | --- |
| `configs.oidc.enabled: false` | No login; every caller is the shared local admin (`trueforge-default`) |
+| `apiKey: placeholder-value-please-generate-your-own` | Well-known controller↔server key (`TRUEFORGE_API_KEY`); replace before any shared deploy |
| `postgresql.auth.password: trueforge` | Well-known Postgres password (unless you set `existingSecret` / a strong password) |
| `redis.auth.enabled: false` | Unauthenticated Redis on the cluster network |
-Before exposing TrueForge beyond a trusted network: enable OIDC, change or
-Secret-back the Postgres password, and prefer external passworded Redis (or
-keep Redis ClusterIP-only and NetworkPolicy-restricted). See
+Before exposing TrueForge beyond a trusted network: enable OIDC, replace the
+`apiKey` placeholder with a Secret-backed value, change or Secret-back the
+Postgres password, and prefer external passworded Redis (or keep Redis
+ClusterIP-only and NetworkPolicy-restricted). See
[Production checklist](#production-checklist) and the
[Setup Login](https://github.com/truefoundry/trueforge/blob/main/docs/authentication/overview.mdx)
docs.
@@ -64,15 +66,24 @@ helm upgrade --install trueforge oci://tfy.jfrog.io/tfy-helm/trueforge \
--set server.publicBaseUrl=https://trueforge.example.com
```
-## API keys
+## API key
-`apiKey` (`TRUEFORGE_API_KEY`) authenticates the controller to the server. The
-server always runs peered (`STANDALONE=false`) and the app rejects an empty
-value, so the chart ships a **dev placeholder**
-(`placeholder-value-please-generate-your-own`). Replace it before any shared
-deployment, as a string or, preferably, a `valueFrom`:
+`apiKey` becomes `TRUEFORGE_API_KEY` on both the server and the controller. It
+authenticates controller → server calls (schedule dispatch). The chart always
+runs peered (`STANDALONE=false`) and rejects an empty key.
+
+`values.yaml` ships a **dev placeholder**
+(`placeholder-value-please-generate-your-own`). The chart does **not** create a
+Secret for it. Before any shared or production deploy, create a Secret and
+point `apiKey` at it (strongly recommended over an inlined string):
+
+```bash
+kubectl create secret generic trueforge-api-key \
+ --from-literal=TRUEFORGE_API_KEY="$(openssl rand -hex 32)"
+```
```yaml
+# values override (or --set-file / parent chart)
apiKey:
valueFrom:
secretKeyRef:
@@ -80,6 +91,9 @@ apiKey:
key: TRUEFORGE_API_KEY
```
+A literal string still works for throwaway clusters (`apiKey: "…"`), but prefer
+`valueFrom.secretKeyRef` so the key never lives in committed values.
+
## Extra environment
`env` is a map of variable name to value, applied to both the server and the
@@ -320,7 +334,7 @@ also sets the `/tmp` `emptyDir.sizeLimit`.
## Production checklist
- **Enable `configs.oidc`** — leaving it off grants shared admin to anyone who can reach the server.
-- **Replace the `apiKey` placeholder** with a generated secret (prefer `valueFrom.secretKeyRef`).
+- **Replace the `apiKey` placeholder** — create a Secret for `TRUEFORGE_API_KEY` and set `apiKey.valueFrom.secretKeyRef` (do not leave `placeholder-value-please-generate-your-own`).
- **Replace the bundled Postgres password** (`trueforge`) or set `postgresql.auth.existingSecret`.
- Treat bundled Redis (`redis.auth.enabled: false`) as cluster-internal only, or switch to external passworded Redis via `externalRedis.url`.
- Set `server.publicBaseUrl` to the real public application URL before using MCP OAuth or OIDC (include a pathname when the UI is served under a stripped prefix).
diff --git a/charts/trueforge/templates/NOTES.txt b/charts/trueforge/templates/NOTES.txt
index 5a468fbc2..74f4e8546 100644
--- a/charts/trueforge/templates/NOTES.txt
+++ b/charts/trueforge/templates/NOTES.txt
@@ -21,6 +21,14 @@ admin (trueforge-default). Enable configs.oidc before exposing this release
beyond a trusted network.
{{- end }}
+{{- if and (kindIs "string" .Values.apiKey) (eq .Values.apiKey "placeholder-value-please-generate-your-own") }}
+
+WARNING: apiKey is still the chart's well-known placeholder. Create a Secret
+(e.g. kubectl create secret generic trueforge-api-key
+--from-literal=TRUEFORGE_API_KEY="$(openssl rand -hex 32)") and set
+apiKey.valueFrom.secretKeyRef before any shared / public deploy.
+{{- end }}
+
{{- if and .Values.postgresql.enabled (eq (default "" .Values.postgresql.auth.existingSecret) "") (eq (default "" .Values.postgresql.auth.password) "trueforge") }}
WARNING: Bundled Postgres is using the chart's well-known dev password
diff --git a/charts/trueforge/values.yaml b/charts/trueforge/values.yaml
index 9c4c1f5d5..2a172b094 100644
--- a/charts/trueforge/values.yaml
+++ b/charts/trueforge/values.yaml
@@ -95,9 +95,10 @@ controller:
cpu: 100m
memory: 256Mi
ephemeral-storage: 256Mi
-# Controller -> server API key (TRUEFORGE_API_KEY). string, or
-# { valueFrom: { secretKeyRef: { name, key } } }. Replace the dev default
-# before any shared deployment; the chart never creates a Secret for it.
+# Controller → server API key (TRUEFORGE_API_KEY). Dev default is a known
+# placeholder — strongly recommended to create a Secret and set:
+# apiKey: { valueFrom: { secretKeyRef: { name: trueforge-api-key, key: TRUEFORGE_API_KEY } } }
+# The chart never creates that Secret. A plain string also works for local trials.
apiKey: "placeholder-value-please-generate-your-own"
# Extra env for BOTH server and controller: name -> scalar or { valueFrom: ... }.
# A key that matches a chart-computed variable (POSTGRES_HOST, PUBLIC_BASE_URL,
diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
index f280af296..b0acba70a 100644
--- a/docs/quickstart.mdx
+++ b/docs/quickstart.mdx
@@ -45,14 +45,34 @@ TrueForge runs in [two modes](/introduction#two-ways-to-run-it): **local mode**
</Tab>
<Tab title="Kubernetes (Hosted)">
- The Helm chart deploys the server in hosted mode with bundled Postgres and Redis (or point it at your own):
+ The Helm chart deploys the server in hosted mode with bundled Postgres and Redis (or point it at your own).
+
+ Create a Secret for the controller↔server API key, then point `apiKey` at it. The chart ships a
+ well-known placeholder (`placeholder-value-please-generate-your-own`) — strongly recommended to
+ replace with a Secret before any shared deploy (the chart does not create one):
+
+ ```bash
+ kubectl create secret generic trueforge-api-key \
+ --from-literal=TRUEFORGE_API_KEY="$(openssl rand -hex 32)"
+ ```
+
+ ```yaml
+ # values.yaml (snippet)
+ apiKey:
+ valueFrom:
+ secretKeyRef:
+ name: trueforge-api-key
+ key: TRUEFORGE_API_KEY
+ ```
```bash
helm install trueforge oci://tfy.jfrog.io/tfy-helm/trueforge \
- --version <x.y.z>
+ --version <x.y.z> \
+ --values values.yaml
```
Find the version you want to install in the [published Helm charts](https://tfy.jfrog.io/ui/packages/oci:%2F%2Ftrueforge).
+ See the [chart README](https://github.com/truefoundry/trueforge/blob/main/charts/trueforge/README.md#api-key) for full `apiKey` details.
To expose TrueForge through an Istio gateway, save this `VirtualService` in
`values.yaml` under `extraObjects`. Replace the host and gateway with your
@@ -77,16 +97,17 @@ TrueForge runs in [two modes](/introduction#two-ways-to-run-it): **local mode**
name: http
```
- Then install the chart with the values file:
+ Then install (or upgrade) with the values file that includes both `apiKey` and `extraObjects`:
```bash
- helm install trueforge oci://tfy.jfrog.io/tfy-helm/trueforge \
+ helm upgrade --install trueforge oci://tfy.jfrog.io/tfy-helm/trueforge \
--version <x.y.z> \
--values values.yaml
```
| Value | Default | Description |
| ---------------------- | ------- | ------------------------------------------------------------------------ |
+ | `apiKey` | placeholder string | Controller↔server key (`TRUEFORGE_API_KEY`). Prefer `valueFrom.secretKeyRef`. |
| `replicaCount` | `1` | Number of server replicas (peered over Redis). |
| `postgresql.enabled` | `true` | Bundle Postgres; set `false` + `externalPostgres.*` to bring your own. |
| `redis.enabled` | `true` | Bundle Redis; set `false` + `externalRedis.url` (string or `valueFrom`). |
diff --git a/packages/trueforge/.env.example b/packages/trueforge/.env.example
index dd2e4f184..505a33e37 100644
--- a/packages/trueforge/.env.example
+++ b/packages/trueforge/.env.example
@@ -131,7 +131,7 @@ REDIS_URL=redis://localhost:6379
## Service credential for controller → /api/internal/schedules.
## Required when STANDALONE=false. Standalone defaults to `trueforge-standalone` (local only).
-# TRUEFORGE_API_KEY=
+TRUEFORGE_API_KEY=placeholder-value-please-generate-your-own
## ---------------------------------------------------------------------------
## MCP knobs.