Add a backend

Backend identity and route selection are repo-owned contract. The concrete origin, environment row, readiness, and runtime token are platform-owned.

Outcome#

A named logical backend owns the intended routes, and the matching preview environment has a verified concrete origin and scoped runtime token.

Prerequisites#

• A managed business repository and preview environment.
• A reachable HTTPS backend origin.
• The backend id returned by backend list after the contract is accepted.

Declare the backend and route#

import * as fs from "@farthershore/business";
const requests = fs.requests();

const analytics = fs.backend("analytics", {
  transport: { mode: "direct" },
  verification: { required: true },
});

const analyze = fs.route("/v1/analyze", {
  post: { backend: analytics },
});

fs.plan("pro", {
  kind: fs.plan.kind.flat,
  price: fs.money.usd(29).monthly(),
  grants: [analyze],
  limits: [requests.perMinute(600)],
});

export default fs.business();

Build and push to a preview branch. Once its apply is accepted, the platform has an environment-scoped backend row with slug analytics.

farthershore build --format json
git push -u origin HEAD:env/backend-preview
farthershore apply-timeline inspect acme "$(git rev-parse HEAD)" \
  --env backend-preview \
  --format json
farthershore backend list acme --format json

Bind runtime state#

farthershore backend bind acme analytics \
  --env backend-preview \
  --origin-url https://analytics-preview.example.com \
  --format json

farthershore backend tokens create acme \
  --backend <backendId> \
  --env backend-preview \
  --idempotency-key <persisted-token-create-attempt> \
  --format json

Store the one-time secret as FS_RUNTIME_TOKEN in the preview backend. Binding is environment-specific. Until an environment-specific backend has a concrete target, the preview inherits the matching production backend by logical slug. To override it, create or accept the same logical backend in the preview, bind its origin, and deploy its own scoped runtime token.

Different upstream URLs per environment#

Keep the same logical backend slug in the Business program. Bind a different concrete upstream URL for each environment through the CLI:

farthershore backend bind acme analytics \
  --env staging \
  --origin-url https://analytics-staging.example.com \
  --format json

farthershore backend bind acme analytics \
  --env feature-preview \
  --origin-url https://analytics-feature.example.com \
  --format json

These commands assume analytics already has an environment row in each selected environment. They change only that environment's binding, not the logical route declaration or another environment's URL. Use --dry-run to inspect a proposed binding without applying it. Omitting --env targets production; agents should pass the intended environment explicitly and obtain approval for production changes. Store each overridden environment's matching runtime token in its own upstream service.

Preview resolution is targeted environment override -> production backend by stable slug. A manifest-created preview placeholder with no origin does not shadow a usable production backend. Partial overrides do not hide inherited sibling backends, another preview is never consulted, and an environment-only backend with no target fails safely with origin_unavailable. Deleting a preview override reveals the inherited production backend again. Changing a production binding queues republication for active previews that inherit it.

Verify one request through the preview runtime, confirm the backend reports healthy, and confirm an unsigned direct request is rejected. Deleting a backend revokes its runtime tokens; remove route references from the Business program before deletion.

Verify#

farthershore backend list acme --format json
farthershore analytics log acme --env <environmentId> --range 1h --domain usage --format json

Require the expected backend slug, environment, origin, and ready status, then prove one signed request through the preview gateway.

Recovery#

If binding fails because the inherited backend has no preview row, create the preview override with the same slug first, then bind it. If a secret is exposed, rotate the runtime token and deploy the replacement immediately. Remove repository route references before deleting an environment-only backend.

Agent prompt#

Add the named backend to the Business program, build and push it to preview,
bind only that environment's concrete origin, create a scoped runtime token,
and verify one signed gateway request. Stop before production changes.

See Backends and Preview environments.