How to Use the `freellmapi launch` Command: Zero‑Persistence Claude Code Launcher

freellmapi launch is a zero‑persistence CLI command that starts Claude Code with credentials injected only into the child process environment, never written to disk.

The freellmapi launch command in the tashfeenahmed/freellmapi repository provides a secure, ephemeral way to run Anthropic's Claude Code coding agent. Unlike traditional setups that store API keys in persistent configuration files, this launcher keeps credentials strictly in memory for the duration of the session.

How freellmapi launch Works

The launch process follows a six‑step execution flow defined in cli/src/index.ts. Understanding this flow helps you troubleshoot issues and leverage advanced options.

1. Parse CLI Options

The parseArgs function (lines 57‑102 in cli/src/index.ts) processes command‑line flags:

• --url — FreeLLMAPI gateway endpoint
• --api-key — API key for authentication
• --profile — Claude profile to use
• --model — Specific model to pin
• --dry-run — Preview changes without launching

2. Obtain an API Key

If --api-key is omitted, promptForKey (lines 5‑35 in cli/src/index.ts) interactively prompts for credentials. For automated environments, set the FREELLMAPI_API_KEY environment variable instead.

3. Fetch the Model Catalog

The catalogs function (lines 84‑95 in cli/src/index.ts) contacts the FreeLLMAPI gateway to retrieve:

• Available‑only roster — Models currently servable
• Full roster — Complete list of supported models

4. Resolve the Target Model

Two resolution paths exist based on the --model flag:

resolvePinnedModel (lines 106‑136 in cli/src/index.ts): Validates a user‑specified model against the catalog and warns if unavailable.

resolveLaunchModel (defined in cli/src/models.ts): Automatically selects the first servable model when no model is pinned.

5. Construct a Clean Environment

The claudeLaunchEnv function (lines 27‑74 in cli/src/index.ts) builds a sanitized child‑process environment that:

• Strips existing Anthropic credentials (prevents conflicts with default configs)
• Injects the resolved model and gateway URL
• Preserves other necessary environment variables

6. Spawn the Child Process

runChild (lines 96‑125 in cli/src/index.ts) executes the claude binary with inherited stdio. The child process receives the prepared environment, runs Claude Code, and returns its exit code to the parent.

freellmapi launch Command Examples

Basic Interactive Launch

Prompts for API key if FREELLMAPI_API_KEY is not set:

npx freellmapi launch

Launch with Custom Gateway and Model

npx freellmapi launch --url http://localhost:3000 --model claude-3-sonnet-20240229

Use a Non‑Default Claude Profile

The profile must be created first via freellmapi setup-claude --profile <name>:

npx freellmapi launch --profile work

Dry‑Run Mode

Preview environment changes without launching Claude Code:

npx freellmapi launch --dry-run

CI‑Friendly Launch with Environment Variable

export FREELLMAPI_API_KEY=sk-xxxxxxxxxxxx
npx freellmapi launch

Key Source Files

Understanding the implementation helps with debugging and customization:

File	Purpose
cli/src/index.ts	Main entry point — argument parsing, model resolution, environment construction, and child process spawning
cli/src/models.ts	Model selection logic (resolveLaunchModel) and catalog data handling
cli/src/tools.ts	Command definitions (launch, launch-codex) and descriptions
cli/README.md	Official CLI documentation
docs/clients.md	Client integration overview for Claude Code and Codex

Security Advantages of freellmapi launch

The zero‑persistence design provides critical security benefits:

• No credential files: API keys never touch ~/.anthropic/, shell history, or configuration files
• Process‑bound scope: Credentials exist only in the child process environment
• Automatic cleanup: Environment variables are destroyed when the child exits
• Conflict prevention: Existing Anthropic credentials are removed to avoid authentication conflicts

This makes freellmapi launch ideal for shared workstations, ephemeral development environments, and security‑conscious workflows.

Summary

• freellmapi launch starts Claude Code with credentials injected only into the child process environment
• Six‑step execution flow: parse args → obtain API key → fetch catalog → resolve model → build clean env → spawn child
• Zero‑persistence security: No secrets written to disk; credentials stay in memory only
• Flexible authentication: Interactive prompts, --api-key flag, or FREELLMAPI_API_KEY environment variable
• Model control: Pin specific models or auto‑select from available catalog

Frequently Asked Questions

Does freellmapi launch modify my Claude Code configuration files?

No. According to the source code in cli/src/index.ts, claudeLaunchEnv explicitly removes existing Anthropic credentials from the environment rather than writing to any configuration. The launcher passes all necessary settings through environment variables to the child process only.

Can I use freellmapi launch without installing Claude Code separately?

No. The runChild function in cli/src/index.ts attempts to spawn the claude binary, which must be installed on your system. The launcher does not bundle Claude Code — it only provides the credential injection mechanism.

What happens if I specify an unavailable model with --model?

resolvePinnedModel checks your requested model against the fetched catalog and emits a warning if the model is not currently servable. The launch proceeds anyway, but Claude Code may fail to initialize if the gateway cannot fulfill requests for that model.

Is freellmapi launch different from freellmapi launch-codex?

Yes. While both commands follow similar zero‑persistence patterns, launch-codex targets OpenAI's Codex CLI agent instead of Claude Code. The underlying environment construction and child process spawning logic is adapted for each respective tool, as defined in cli/src/tools.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}