Hosting

Self-hosted SDKs

View as Markdown
Enterprise feature

This feature is available only for the Enterprise plan. To get started, reach out to support@buildwithfern.com.

Fern SDK generation runs on Fern’s infrastructure by default. Self-hosting allows you to run SDK generation on your own infrastructure. Use self-hosting if your organization:

  • Operates without internet access
  • Has strict compliance or security requirements
  • Needs full control over your SDK generation process

When you self-host, you’re responsible for infrastructure management and SDK distribution. Self-hosted SDK generation includes all Fern SDK features.

Unless you have specific requirements that prevent using Fern’s default hosting, we recommend using our managed cloud generation solution for easier setup and maintenance.

Setup

This page assumes that you have:

Self-hosted SDK generation allows you to output to your local file system or push directly to a GitHub repository you control. Follow these steps to set up and run local generation:

1

Ensure Docker is running

Verify that a Docker daemon is running on your machine, as SDK generation runs inside a Docker container:

$docker ps
2

Generate a Fern token

Generate a Fern token, which is required for local generation to verify your organization.

$fern token

The token is specific to your organization defined in fern.config.json and doesn’t expire.

3

Configure output location

Configure your generators.yml to output SDKs to your local file system or a GitHub repository you control.

Output generated SDKs directly to a local directory:

generators.yml
1groups:
2  python-sdk:
3    generators:
4      - name: fernapi/fern-python-sdk
5        version: 4.0.0
6        output:
7          location: local-file-system
8          path: ../sdks/python
4

Set up authentication

Configure authentication based on your chosen output location.

Set your Fern token as an environment variable:

$export FERN_TOKEN=your-generated-token
5

Run generation locally

Use the --local flag to generate SDKs locally instead of using Fern’s cloud infrastructure. You can combine --local with --group to generate specific SDKs locally.

$fern generate --local
$fern generate --group python-sdk --local

By default, fern generate --local pulls generator Docker images from Docker Hub. If your organization mirrors Fern’s images into a private registry, you can configure the CLI to pull from that registry instead. To use a custom registry, replace the name field in your generator configuration with an image object containing name and registry:

generators.yml
1groups:
2  python-sdk:
3    generators:
4      - image:
5          name: fern-python-sdk
6          registry: ghcr.io/your-org
7        version: 5.5.6
8        output:
9          location: local-file-system
10          path: ../sdks/python

The image.name must be a recognized Fern generator name (for example, fern-python-sdk or fern-typescript-sdk). This ensures the CLI can resolve the correct IR version for your generator. The version must also match a published Fern generator version.

Generators configured with a custom image are skipped during fern generator upgrade. You must manually update the version for these generators.

If your registry requires authentication, log in before running fern generate --local. The CLI uses the credentials stored by Docker.

$# Example: authenticate with GitHub Container Registry
$echo $CR_PAT | docker login ghcr.io -u USERNAME --password-stdin
$
$# Then run local generation as usual
$fern generate --local

How it works

When you run fern generate --local, the Fern CLI executes SDK generation on your local machine instead of using Fern’s cloud infrastructure.

The underlying SDK generation architecture is the same whether you use cloud or self-hosted generation. See the expanded architecture diagram for details.

The self-hosted process works as follows:

  1. Organization verification (network call) - The CLI verifies your organization registration with Fern
  2. Download generator image (network call if not cached) - The CLI downloads the generator’s Docker image if not already available locally
  3. Generate SDK (local) - The CLI runs the generator container locally to produce SDK files based on your API definition and generators.yml configuration
  4. Output SDK (local) - Generated SDK files are saved to your configured output location (local file system or GitHub repository)

Steps 1 and 2 are the only network calls made when using the --local flag. No API definition or specification data is sent over the network: all SDK generation happens locally on your machine.