Environment variables
CLI configuration, backend runtime credentials, and business variables (public by FS_PUBLIC_ prefix, secret otherwise).
Business behavior is not configured with environment variables. Plans, prices,
meters, routes, limits, policies, and surfaces remain deterministic declarations
under business/.
This page covers three unrelated configuration channels that are easy to confuse.
CLI process configuration
| Variable | Default | Purpose |
|---|---|---|
FARTHERSHORE_API_URL | https://core.farthershore.com | Override the control-plane API, primarily for development or stage testing |
FARTHERSHORE_ENV | production | Default environment for commands that accept --env |
FARTHERSHORE_TOKEN | unset | Ephemeral, pre-issued organization-scoped MakerToken for this process |
Normal authentication is user-bound and persisted by farthershore login.
FARTHERSHORE_TOKEN is the narrow automation override; it is not persisted
automatically and must never be committed or printed.
Backend runtime bootstrap
@farthershore/backend reads one runtime credential:
| Variable | Default | Purpose |
|---|---|---|
FS_RUNTIME_TOKEN | required | Bootstrap request verification, runtime identity, transport configuration, and metering |
FS_CORE_URL | https://core.farthershore.com | Runtime bootstrap URL override |
import { fartherShore } from "@farthershore/backend";
const fs = fartherShore.initFromEnv();
A runtime token may be business-wide, environment-scoped, or backend-scoped. It can also restrict operations, meter names, and route identities. The token value is shown once, stored hash-only by the platform, and belongs in the backend host's secret manager.
Rotation is a hard cutover: the predecessor is revoked immediately. Deploy the new secret as one coordinated change; there is no period where both tokens are valid. See Runtime tokens.
Business variables: the name is the class
Business variables are platform-owned values addressed by business,
environment, and key. An environment-specific value overrides the production
value for that environment. There is no delivery setting — a name starting
with FS_PUBLIC_ is public; any other name is a write-only secret.
| Name | Read behavior | Where it goes | Rebuild? |
|---|---|---|---|
FS_PUBLIC_* | readable plaintext | inlined into the hosted frontend bundle; visible to every visitor | yes |
| anything else | write-only | the hosted frontend build (leak-scanned), and injected by the gateway into a compiled fs.frontendIntegration() that references it | no |
A secret variable does not set a process environment variable on your
backend host, and it is unrelated to FS_RUNTIME_TOKEN.
farthershore variables list quillby --format json
printf %s "$VALUE" | farthershore variables set quillby API_REGION \
--idempotency-key <persisted-variable-set-attempt-key> --format json
farthershore variables status quillby <operation-id> --format json
FS_PUBLIC_* values are returned by reads because they are intentionally
public. Every other variable stays write-only; list/status responses expose
metadata, not plaintext. Use rotate, revoke, and rm for lifecycle changes.
Read Variables for frontend usage and Frontend integrations for the only edge injection path.
Hosted frontend bootstrap
@farthershore/farthershore-js reads connection and business context from the
window.__FS_CONFIG__ shim injected by the hosted shell. Application code does
not embed a Core URL or platform credential. Local preview commands inject the
same shape:
farthershore frontend dev
farthershore frontend preview
Ownership test
If a value changes what the business sells or permits, put it in deterministic
business/ code. If it is an environment-specific credential, public setting,
or runtime binding with no contract representation, operate it through the CLI.