Quickstart

This path creates one managed business repository, defines a minimal contract, and verifies the platform accepted it.

0. Confirm you can deploy#

Farther Shore is the gateway, billing, and entitlement plane in front of an HTTP service that you run. It does not host that service, and a production publish fails until every declared backend has a real origin bound to it. Before you start, confirm all three:

1. Somewhere to run it — a host that serves a long-lived HTTP process on a public HTTPS URL: Railway, Render, Fly.io, Cloud Run, AWS, or your own infrastructure.
2. Somewhere to put secrets — the ability to set environment variables on that host, because the service reads FS_RUNTIME_TOKEN from its environment and that value must never be committed.
3. Somewhere to read logs — bootstrap and signature-verification failures appear only in the service's own logs.

If any is missing, resolve it first. For one service, the host's own CLI is enough; for a preview environment and a production environment that must stay in step, see Infrastructure with OpenTofu.

1. Sign in#

farthershore login
farthershore auth whoami

If your user belongs to several organizations, select the intended one:

farthershore auth organization list
farthershore auth organization use acme

2. Create and clone the managed repository#

CREATE_ATTEMPT=$(node -e 'console.log(crypto.randomUUID())')
REPO_URL=$(farthershore business create quillby \
  --idempotency-key "$CREATE_ATTEMPT")
git clone "$REPO_URL"
cd "$(basename "$REPO_URL" .git)"

To create in an organization other than the saved default, note that --organization is a global option and must precede the subcommand: farthershore --organization acme business create quillby …. Placed after create, it is rejected as an unknown option.

Human-mode stdout is only the repository URL. For structured recovery metadata, add --format json to the same keyed command and read .data.repoUrl.

The repository contains business/package.json, TypeScript tooling, and agent instructions. It intentionally contains no predefined business shape.

3. Author business/business.ts#

Create the program from the actual product requirements. This complete example declares one metered route and one free plan:

import * as fs from "@farthershore/business";

fs.backend("api");
const requests = fs.requests();

const health = fs.route("/v1/health", {
  get: { costs: [requests.fixed(1)] },
});

fs.plan("starter", {
  kind: fs.plan.kind.free,
  grants: [health],
  limits: [requests.perMinute(60)],
});

export default fs.business({
  customerContext: {
    // Required when a signed-in browser will mint fsc_ gateway credentials.
    contextTokens: { enabled: true },
    // Preview environments can use disposable personas; production auth is
    // configured by the platform connection.
    customerAuth: { strategy: "test-personas" },
  },
});

fs.requests() does not attach itself to every route in SDK 2.0. The explicit costs entry is what makes the plan limit meaningful.

customerContext.contextTokens is what makes authenticated browser-to-gateway requests possible. Do not omit it when the customer application calls protected backend routes through the Farther Shore gateway.

4. Build locally#

cd business
npm install
npm run build
cd ..
farthershore validate

Fix every compiler diagnostic. A build must be deterministic and every ref, grant, metering attachment, and limit must resolve.

5. Push and inspect apply#

git add business
git commit -m "Define business"
git push

A direct push reports two checks on the commit: farthershore/build for the Manifest IR build, then farthershore/apply for the compile, accept, and publish phases. farthershore/validate is the pull-request check and does not appear on a plain push, so do not wait for it.

Inspect the repository check for that commit, then confirm the accepted state:

farthershore apply-timeline list quillby
farthershore business contract quillby
farthershore business routes quillby

Do not treat a local build or pushed commit as accepted until the apply check succeeds.

6. Prove the first-customer path#

A successful contract apply, backend deployment, frontend build, or authenticated HTTP call is necessary but not sufficient. Before release, prove one new customer can complete this entire public path in the same environment:

1. Open the environment's returned portal hostname and sign in.
2. Select the intended organization; do not assume the personal workspace is the subscribed organization.
3. Start onboarding from the published offer. For a free plan, let Core select the current free compiled plan instead of copying an old plan id.
4. Read /me again and require subscriber.status: "ACTIVE" plus a non-null subscriber.compiledPlanId. A success message or plan catalog entry does not prove enrollment.
5. Mint the subscriber gateway credential through the SDK and call a declared route. Require a response marker produced by the backend, not merely a 2xx to 4xx status that could have come from the gateway.
6. Read the record back through the application UI.

For preview environments, public resolution must return that environment's runtime hostname. Browser SDK traffic must never fall back to the production gateway. See Test in a preview.

FartherShoreRoot from @farthershore/farthershore-js/components owns the organization, onboarding, entitlement-refetch, legal, and payment gates. Keep product content inside the root so an incomplete subscriber cannot enter the application.

7. Continue the real build#

• Scaffold the backend service: farthershore create api --node from the repository root, then Scaffold a backend.
• Add route policies and backend refs: Routes.
• Bind the deployed service: Bring your own backend.
• Provision more than one environment: Infrastructure with OpenTofu.
• Design economics and bounds: Plans & pricing.
• Build customer UI: Frontend SDK.
• Test in a branch environment: Environments.
• Review plan impact before release: Plan changes.

Publishing production is a separate, explicit action after runtime bindings, payments, and release checks are ready. It fails with BACKEND_TARGET_REQUIRED unless every backend declared in business/ has a concrete production origin, and with DEFAULT_BACKEND_REQUIRED when several backends exist without one marked default.

8. Operate through the CLI#

Use CLI commands for state that has no code representation:

farthershore usage summary quillby --format json
farthershore frontend status quillby --format json
farthershore notifications preferences quillby --format json

Use farthershore operations list --format json to discover available operations and their exact command shapes.

Verify#

• farthershore business create <slug> returned one managed repository URL.
• The repository began without a predefined business shape.
• farthershore build and farthershore validate succeeded locally.
• The pushed commit has successful build/apply checks.
• business status identifies the accepted business state.
• A newly signed-in customer has an active compiled plan and receives a backend-produced response through the environment gateway.

Recover#

• Create timed out: rerun the exact command with the persisted create key, then use business show to read current state.
• Build failed: correct business/ and rerun build and validate.
• Push check failed: inspect its annotations, fix the repo, and push again.
• Onboarding looked successful but /me has no compiled plan: treat the customer as not enrolled, repeat onboarding only after reading current state, and do not render the application yet.
• Preview UI calls the production gateway: inspect public business resolution; its runtimeHostname must equal the selected preview environment hostname.
• Platform operation failed: branch on the stable error code and follow its hint; do not move platform-owned state into the repo or contract state into a CLI write.

Agent prompt#

Generate and record one private attempt key, then create Farther Shore business
quillby with `farthershore business create quillby --idempotency-key
<persisted-key>`. Clone the returned repository URL and read its AGENTS.md.
Gather the requirements, then author the complete business/ program from
scratch using the functional @farthershore/business SDK. Run build and
validate, commit and push, inspect the Farther Shore checks and Apply Timeline,
and report exact results. Use the CLI only for platform state that has no code
representation.

Continue with Core concepts or the recipe closest to your product shape.