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

> Learn how to use the freellmapi launch command to securely start Claude Code without writing credentials to disk. This zero-persistence CLI injects secrets only into the child process environment.

- Repository: [Tashfeen/freellmapi](https://github.com/tashfeenahmed/freellmapi)
- Tags: how-to-guide
- Published: 2026-08-28

---

**`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](https://github.com/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/cli/src/index.ts)): Validates a user‑specified model against the catalog and warns if unavailable.

**`resolveLaunchModel`** (defined in [`cli/src/models.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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:

```bash
npx freellmapi launch

```

### Launch with Custom Gateway and Model

```bash
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>`:

```bash
npx freellmapi launch --profile work

```

### Dry‑Run Mode

Preview environment changes without launching Claude Code:

```bash
npx freellmapi launch --dry-run

```

### CI‑Friendly Launch with Environment Variable

```bash
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`](https://github.com/tashfeenahmed/freellmapi/blob/main/cli/src/index.ts) | Main entry point — argument parsing, model resolution, environment construction, and child process spawning |
| [`cli/src/models.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/cli/src/models.ts) | Model selection logic (`resolveLaunchModel`) and catalog data handling |
| [`cli/src/tools.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/cli/src/tools.ts) | Command definitions (`launch`, `launch-codex`) and descriptions |
| [`cli/README.md`](https://github.com/tashfeenahmed/freellmapi/blob/main/cli/README.md) | Official CLI documentation |
| [`docs/clients.md`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/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`](https://github.com/tashfeenahmed/freellmapi/blob/main/cli/src/tools.ts).