Self-hosted SDKs

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, SDK distribution, and computing SDK version numbers. Self-hosted SDK generation includes all Fern SDK features.

Infrastructure requirements

Each machine that runs fern generate --local needs:

• A Docker runtime. Generation runs inside a generator container, so a Docker daemon must be available (docker ps succeeds). In CI, use a runner with Docker preinstalled or a Docker-in-Docker service.
• A FERN_TOKEN. Organization verification requires a Fern API key, injected as the FERN_TOKEN environment variable. Store it as a CI secret rather than in the repo.
• Outbound network access to two endpoints. The CLI verifies your organization with Fern and pulls the generator image. No API definition leaves your infrastructure. Air-gapped environments must mirror generator images into a private registry reachable from the runner.
• Write access to the output location. Local-file-system output writes to disk; GitHub output needs a GITHUB_TOKEN with write access to the SDK repository.

Setup

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:

docker ps

fern token

groups:
  python-sdk:
    generators:
      - name: fern-python-sdk
        version: 4.0.0
        output:
          location: local-file-system
          path: ../sdks/python

export FERN_TOKEN=your-generated-token

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

Private registry setup

By default, fern generate --local pulls generator Docker images from Docker Hub. Organizations that restrict outbound traffic or require vetted images can mirror Fern’s generator images into a private registry and point the CLI at it. Remote (cloud) generation doesn’t support custom registries.

docker pull fernapi/fern-python-sdk:4.0.0
docker tag fernapi/fern-python-sdk:4.0.0 ghcr.io/your-org/fern-python-sdk:4.0.0
docker push ghcr.io/your-org/fern-python-sdk:4.0.0

groups:
  python-sdk:
    generators:
      - image:
          name: fern-python-sdk
          registry: ghcr.io/your-org
        version: 5.30.0
        output:
          location: local-file-system
          path: ../sdks/python

# 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

Trust a corporate CA bundle

Some generators make network calls from inside the container (pnpm install for TypeScript, go mod tidy for Go, NuGet restore during dotnet format for C#, and the git clone of an existing SDK repository when merging its README). On networks with TLS interception, these calls fail because the container doesn’t trust the corporate CA. Set FERN_CA_BUNDLE (Fern CLI 5.116.0 or later) to a PEM CA bundle on the host that runs the CLI:

export FERN_CA_BUNDLE=/etc/ssl/certs/corporate-bundle.pem
fern generate --local

The CLI mounts the file read-only at /fern/ca-bundle.crt in the generator container and points NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, and GIT_SSL_CAINFO at it. TLS verification stays on. The CLI exits with an error if the path is unreadable or contains no PEM certificates.

• SSL_CERT_FILE and GIT_SSL_CAINFO replace the container’s trust store, so the file must be a full bundle (the public roots plus your corporate CA), not only the corporate root or intermediate. The CLI warns when the file holds fewer than 50 certificates.
• Java ignores these variables, so Gradle and Spotless downloads in fern-java-* generators still fail behind interception. Set FERN_JAVA_SKIP_FORMATTING=true for those generators.
• The bind mount must be visible to the Docker daemon, so FERN_CA_BUNDLE requires a local daemon. Remote DOCKER_HOST and Docker-in-Docker sidecars aren’t supported.
• FERN_CA_BUNDLE only affects 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 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 the CLI makes when using the --local flag. No API definition or specification data is sent over the network: all SDK generation happens locally on your machine. The Java generator additionally reaches Gradle’s distribution and plugin hosts to format its output, which FERN_JAVA_SKIP_FORMATTING turns off.

Skip Java code formatting

The Java generator formats its output with ./gradlew :spotlessApply, which downloads Gradle and the Spotless plugin from services.gradle.org and plugins.gradle.org. On networks that block those hosts or intercept TLS (Java ignores FERN_CA_BUNDLE), set FERN_JAVA_SKIP_FORMATTING=true (Java generator 4.18.0 or later) to skip the formatting pass. The CLI forwards the variable into the generator container:

FERN_JAVA_SKIP_FORMATTING=true fern generate --local --group java-sdk

Generated code is left unformatted; run ./gradlew spotlessApply in the SDK repository to format it.