Environment variables
Every environment variable a builder sets across the SDKs.
Every environment variable a builder sets across the SDKs.
Farther Shore keeps configuration deliberately small: each SDK reads a handful
of environment variables, and most have safe defaults. This page lists every
variable a builder sets, grouped by where it's read. Secrets (mk_…, fsrt_…)
are never committed — set them in your shell, CI, or the upstream's deployment
environment.
@farthershore/cliRead by the farthershore command. See the CLI reference.
| Variable | Default | Purpose |
|---|---|---|
FARTHERSHORE_TOKEN | — | Maker token (mk_…). Overrides stored credentials in ~/.farthershore/credentials.json. The way agents/CI authenticate. |
FARTHERSHORE_API_URL | https://core.farthershore.com | Platform Core API URL. Overridden per-command by --api-url. |
FARTHERSHORE_ENV | (production) | Default environment scope when --env is omitted. |
export FARTHERSHORE_TOKEN=mk_xxx
farthershore product list --format json
The MCP stdio server reads the same token:
FARTHERSHORE_TOKEN=mk_xxx npx -p @farthershore/cli farthershore-mcp
@farthershore/backendRead by fartherShore.initFromEnv() in your upstream. The builder configures
exactly one thing — FS_RUNTIME_TOKEN — and everything else (ids, JWKS URL,
metering endpoint, transport) is fetched from bootstrap. See the
backend SDK reference.
| Variable | Default | Purpose |
|---|---|---|
FS_RUNTIME_TOKEN | — (required) | The runtime token (fsrt_…). Drives bootstrap, gateway-verification, and response-bound usage signing. Mint it once with farthershore backend tokens create. |
FS_CORE_URL | https://core.farthershore.com | Core base URL for bootstrap. |
FARTHERSHORE_CORE_URL | https://core.farthershore.com | Alternate spelling, read if FS_CORE_URL is unset. |
# In the upstream's deployment environment:
export FS_RUNTIME_TOKEN=fsrt_live_xxx
import { fartherShore } from "@farthershore/backend";
const fs = fartherShore.initFromEnv(); // reads FS_RUNTIME_TOKEN + FS_CORE_URL
The same FS_RUNTIME_TOKEN signs withUsage() / createUsage() response
metering — it is the DEFAULT_TOKEN_ENV the response-metering signer resolves.
@farthershore/farthershore-jsThe browser SDK reads almost nothing from process.env directly: on
platform-served portals the edge injects window.__FS_CONFIG__ (the
environment's coreUrl + Clerk connection) and the SDK falls back to it. In a
custom frontend you pass coreUrl to createFartherShoreClient, typically from
a bundler-exposed variable. The convention used by the scaffold and the
frontend preview shim:
| Variable | Read by | Purpose |
|---|---|---|
VITE_CORE_URL / VITE_FS_CORE_URL | your bundler (Vite) | Platform Core base URL passed to createFartherShoreClient({ coreUrl }). |
VITE_CLERK_PUBLISHABLE_KEY | your bundler (Vite) | Clerk publishable key for clerk-strategy environments. |
VITE_CLERK_SIGN_IN_URL | your bundler (Vite) | Clerk hosted sign-in URL. |
VITE_CLERK_SATELLITE_DOMAIN | your bundler (Vite) | Clerk satellite domain for satellite portals. |
import { createFartherShoreClient } from "@farthershore/farthershore-js";
const fs = createFartherShoreClient({ coreUrl: import.meta.env.VITE_CORE_URL });
farthershore frontend preview injects a window.__FS_CONFIG__ shim from these
same VITE_* variables (each overridable by a flag) so the portal renders
locally as it serves:
VITE_FS_CORE_URL=http://localhost:8787 farthershore frontend preview
# or
farthershore frontend preview --core-url http://localhost:8787
The VITE_ prefix is the bundler's convention, not a platform requirement — the
SDK only cares that you pass coreUrl to the client. On the platform edge,
nothing is baked: coreUrl and the Clerk connection arrive via the
edge-injected window.__FS_CONFIG__, so a platform-served portal needs no env at
all.
| Prefix | Token | Where it's set | Reference |
|---|---|---|---|
mk_… | Maker token | FARTHERSHORE_TOKEN (CLI / MCP / CI) | CLI |
fsrt_… | Runtime token | FS_RUNTIME_TOKEN (upstream) | Backend SDK |
fsk_live_… / fsk_test_… | Subscriber API key | passed to the frontend client (setApiKey) — never an env var | API keys |
Never commit mk_… or fsrt_… tokens. The maker token grants org-level write;
the runtime token authorizes a specific backend. Both are shown once on creation
— store them in a secret manager.