> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Personal setup for coding agents

> Connect your installed coding agents to the TrueFoundry AI Gateway with one setup wizard.

Run `tfy-local-ai-setup personal` once to connect the coding agents on your laptop to the TrueFoundry AI Gateway. Select your agents, choose models and MCP servers, and review the changes before applying them.

Setup writes your user settings. It does not install the agents or require administrator privileges.

## What setup does

1. Finds your installed coding agents and lets you select them together.
2. Signs you in, discovers your gateway, and asks which models and MCP servers to use.
3. Shows the proposed changes before you apply them, then reports any remaining app steps.

Your choices are saved in `~/.tf/config.toml` for future runs. Before the first edit to an existing file, setup saves a `.bak` recovery copy. See [credential handling](#finish-setup-in-your-apps) for where each app keeps its token.

## Before you start

You need:

* Your **TrueFoundry control plane URL**: the address where you sign in to TrueFoundry.
* Access to at least one gateway model. Ask your administrator which models to use.
* One or more [supported coding agents](#supported-agents) installed on your computer.
* `curl` on macOS/Linux, or PowerShell on Windows, to download the setup tool.

> [!NOTE]
>
> If an agent is managed by your organization's IT team, its managed settings take precedence. Leave it under IT management. For organization-wide deployment, see [Enforce with MDM](https://www.truefoundry.com/docs/ai-gateway/claude-mdm.md).

> [!NOTE]
>
> **Claude Desktop:** launch the app and save a valid third-party configuration before running setup, then fully quit it before applying changes. The current personal setup requires an existing active configuration. Merely opening a clean installation may not create one. See [Claude Desktop and Cowork](https://www.truefoundry.com/docs/ai-gateway/claude-desktop.md) for third-party setup.

## Install the setup tool

Run the command for your platform to download the [latest release](https://github.com/truefoundry/tfy-local-ai-setup/releases/latest). It installs the tool in your user account without administrator privileges.

> [tab] macOS (Apple Silicon)
>
> ```bash theme={"dark"}
> mkdir -p "$HOME/.local/bin" && \
>   curl -fsSL https://github.com/truefoundry/tfy-local-ai-setup/releases/latest/download/tfy-local-ai-setup-darwin-arm64 -o "$HOME/.local/bin/tfy-local-ai-setup" && \
>   chmod +x "$HOME/.local/bin/tfy-local-ai-setup" && \
>   export PATH="$HOME/.local/bin:$PATH"
> ```

> [tab] macOS (Intel)
>
> ```bash theme={"dark"}
> mkdir -p "$HOME/.local/bin" && \
>   curl -fsSL https://github.com/truefoundry/tfy-local-ai-setup/releases/latest/download/tfy-local-ai-setup-darwin-amd64 -o "$HOME/.local/bin/tfy-local-ai-setup" && \
>   chmod +x "$HOME/.local/bin/tfy-local-ai-setup" && \
>   export PATH="$HOME/.local/bin:$PATH"
> ```

> [tab] Linux (x86-64)
>
> ```bash theme={"dark"}
> mkdir -p "$HOME/.local/bin" && \
>   curl -fsSL https://github.com/truefoundry/tfy-local-ai-setup/releases/latest/download/tfy-local-ai-setup-linux-amd64 -o "$HOME/.local/bin/tfy-local-ai-setup" && \
>   chmod +x "$HOME/.local/bin/tfy-local-ai-setup" && \
>   export PATH="$HOME/.local/bin:$PATH"
> ```

> [tab] Windows (x86-64)
>
> Run in PowerShell:
>
> ```powershell theme={"dark"}
> $setupDir = "$env:LOCALAPPDATA\TrueFoundry"
> New-Item -ItemType Directory -Force -Path $setupDir | Out-Null
> Invoke-WebRequest -Uri "https://github.com/truefoundry/tfy-local-ai-setup/releases/latest/download/tfy-local-ai-setup-windows-amd64.exe" -OutFile "$setupDir\tfy-local-ai-setup.exe" -ErrorAction Stop
> $userPath = [Environment]::GetEnvironmentVariable("Path", "User")
> if (($userPath -split ';') -notcontains $setupDir) {
>   [Environment]::SetEnvironmentVariable("Path", "$userPath;$setupDir", "User")
> }
> $env:Path = "$setupDir;$env:Path"
> ```

On macOS/Linux, also add `export PATH="$HOME/.local/bin:$PATH"` to your shell startup file so future terminals can find the tool: `~/.zshrc` for Zsh or `~/.bashrc` for Bash (`~/.bash_profile` for a macOS Bash login shell). The Windows commands save the user PATH automatically.

Keep the binary in its installed location: agents may call it later to retrieve credentials.

## Run the setup wizard

```bash theme={"dark"}
tfy-local-ai-setup personal
```

Use the arrow keys to move, **Space** to toggle checkboxes, and **Enter** to continue. Follow the hints on each screen. **Esc** goes back where offered; **Ctrl+C** cancels. The questions depend on the agents you select and any saved choices.

Terminal screenshots show the current wizard, with account and gateway values anonymized.

**1. Sign in to TrueFoundry**

On first use, enter your control plane URL. Setup looks up your tenant and starts browser sign-in. Open the displayed link if the browser does not open, complete your organization's login, then return to the terminal.

On later runs, check the displayed account and tenant and choose **Continue**. Use **Sign in to a different tenant** when you intend to switch organizations.

![Returning-user sign-in screen with Continue and Sign in to a different tenant options](https://mintcdn.com/truefoundry/GsQqe3-nV0a5qzP7/images/ai-gateway/personal-setup/current-sign-in.png?fit=max\&auto=format\&n=GsQqe3-nV0a5qzP7\&q=85\&s=5df28f8c66e34b1508eab25c2f77a59b)

**2. Select your coding agents**

Setup scans for installed agents. Select all the agents you want to configure in this checklist, then press **Enter**. You do not need to run a separate setup command for each agent.

On a rerun, previous selections are preserved. Check the list if you installed another agent since the last run.

![Installed-agent checklist with Claude Desktop, VS Code, and Cursor selected together](https://mintcdn.com/truefoundry/GsQqe3-nV0a5qzP7/images/ai-gateway/personal-setup/current-agents.png?fit=max\&auto=format\&n=GsQqe3-nV0a5qzP7\&q=85\&s=964b4d1b97d6c4b224907d6bbc950255)

**3. Check the gateway and authentication**

Setup discovers the gateway after sign-in. A single gateway is selected automatically. With several gateways, the main wizard uses your saved gateway or the tenant default. If discovery cannot find one, enter the gateway URL provided by your administrator.

Your **control plane URL** is where you sign in. Your **gateway URL** is where agents send model requests. These can be different addresses.

**If setup asks for a Personal Access Token:** reuse an existing token, create one for this machine, or paste a token you [created in TrueFoundry](https://www.truefoundry.com/docs/generating-truefoundry-api-keys.md). For a new token, use a recognizable name such as `work-laptop`; it is created only when you apply changes. If prompted for a team owner, choose a team you belong to.

With only OIDC-capable agents selected and OIDC available for your tenant, setup uses organization sign-in instead and skips the PAT choice. Browser sign-in to the wizard and authentication inside your agents are separate steps.

**4. Choose models**

You see only the questions relevant to your selected agents:

* **Claude Code and Claude Desktop:** separate choices for their Opus, Sonnet, and Haiku tiers.
* **Codex:** a default model. Use a [Virtual Model](https://www.truefoundry.com/docs/ai-gateway/virtual-model.md) slug, rather than a provider-prefixed model ID. See [Codex model configuration](https://www.truefoundry.com/docs/ai-gateway/openai-codex-cli.md#why-you-need-a-virtual-model).
* **Agents with a model list:** choose shared models, then a default from that list.
* **Cursor:** finish model routing in the app after the wizard.

Type to search, check the exact model row with **Space** in a multi-select, then press **Enter**. Search can return similar model names, so check the full ID before selecting it.

![Claude Desktop model picker with the saved tier choice prefilled](https://mintcdn.com/truefoundry/GsQqe3-nV0a5qzP7/images/ai-gateway/personal-setup/current-models.png?fit=max\&auto=format\&n=GsQqe3-nV0a5qzP7\&q=85\&s=25dd3fcfc69235c598df7abdc1c604f6)

Saved per-agent overrides take precedence over shared defaults. Changing shared models in the main wizard preserves those overrides.

**5. Choose MCP servers**

Select the [MCP servers](https://www.truefoundry.com/docs/ai-gateway/mcp/mcp-overview.md) you want your agents to use, or leave the selection empty to skip MCP. The main wizard edits shared MCP defaults and preserves per-agent overrides.

Adding a server configures its connection. Servers that use OAuth still require sign-in inside each agent. This is separate from model authentication.

**6. Review and apply**

Read the proposed changes, including file diffs, credential operations, backups, and manual steps. Where prompted, confirm the Personal Access Token (PAT) to reuse or create, and its owning team if your tenant requires one. A new PAT is created at apply time.

Choose **View full diff** to expand a longer change. Choose **Apply changes** when the plan is correct, or **Cancel** to leave the configuration unchanged. Credential values are redacted in the preview. An unchanged run may finish without an apply prompt.

![Review screen with Apply changes, View full diff, and Cancel options](https://mintcdn.com/truefoundry/GsQqe3-nV0a5qzP7/images/ai-gateway/personal-setup/current-review.png?fit=max\&auto=format\&n=GsQqe3-nV0a5qzP7\&q=85\&s=507883ad5bdd152a35823067b651e982)

Read the result for each agent:

| Result | What to do |
| - | - |
| **configured** | Settings were written. Continue to the app and verification steps below. |
| **unchanged** | Settings already match. Check any listed manual steps. |
| **action required** | Settings were written, but you must finish the listed steps inside the app. |
| **failed** / **partially configured** | Fix the reported error and rerun setup. Successful changes may already have been kept. |

Open a **new terminal** before launching terminal-based agents so they inherit setup's shell environment. Fully reopen Claude Desktop if you configured it.

## Finish setup in your apps

Use the instructions for the apps you selected. These are finishing steps after the same wizard.

> [tab] VS Code
>
> Setup adds the gateway models and MCP configuration. If the app still needs a key, run `tfy-local-ai-setup token`, then paste it through the model row's **Update API Key** menu.
>
> Select your gateway model in a new chat. On VS Code 1.140.0, use the **Local** harness if the Copilot harness asks for GitHub sign-in.
>
> See the [VS Code guide](https://www.truefoundry.com/docs/ai-gateway/vscode.md) for model settings and [Connect MCP from your IDE](https://www.truefoundry.com/docs/ai-gateway/mcp/connect-mcp-from-ide.md) for MCP authentication.

> [tab] Cursor
>
> Setup writes Cursor's MCP configuration. Finish the model API key, gateway endpoint, and custom model selection in the app using the [Cursor setup guide](https://www.truefoundry.com/docs/ai-gateway/cursor.md#connect-cursor-to-the-gateway). Run `tfy-local-ai-setup token` to retrieve your PAT when entering the key.
>
> For MCP sign-in, follow the Cursor instructions in [Connect MCP from your IDE](https://www.truefoundry.com/docs/ai-gateway/mcp/connect-mcp-from-ide.md).

> [tab] Claude Desktop
>
> Reopen Desktop after setup and complete organization sign-in if prompted. For MCP, open **Customize → Connectors** and connect each server separately. MCP uses its own OAuth session, including when model requests use a PAT.
>
> Personal Desktop setup supports macOS and Windows. If setup reports no valid active configuration, see [Troubleshooting](#troubleshooting).

> [tab] Terminal agents
>
> Open a new terminal and launch your selected agent normally. Complete any model sign-in and MCP authentication prompts. For example:
>
> * **Claude Code:** open `/mcp` inside Claude Code to check servers and authenticate when prompted.
> * **Codex:** run `codex mcp login <server-name>`.
> * **Gemini CLI:** run `/mcp auth <server-name>` inside Gemini CLI.
> * **OpenCode:** run `opencode mcp auth <server-name>`. Launch its desktop app from a terminal if it needs to inherit `TFY_AGENT_TOKEN`.
>
> **Gemini CLI:** choose a Gemini-compatible model. For routing to other model families, see [Using Gemini CLI with OpenAI models](https://www.truefoundry.com/docs/ai-gateway/gemini-cli.md#using-gemini-cli-with-openai-models).
>
> An agent can answer model requests while a connector still needs authentication. Verify both separately.

> [!NOTE]
>
> Setup uses the OS credential store when available and warns when it falls back to protected files under `~/.tf`. Agent credential handling varies: CLI agents use helpers or environment references, VS Code keeps a UI-entered key in its own secret storage, and Claude Desktop's static-token mode stores the PAT in its local profile. Keep configuration files and backups private.

## Verify the setup

```bash theme={"dark"}
tfy-local-ai-setup status
tfy-local-ai-setup doctor
```

`status` checks configuration. `doctor` checks items such as stored credentials, gateway model discovery, and configured MCP endpoints. Neither proves that an app has completed its own sign-in or can execute a tool.

1. **Test the model in each selected agent.** Select the configured gateway model and ask: `Reply exactly TFY-CHAT-OK. Do not use tools.` Confirm that the response arrives without an authentication or model error.
2. **Test MCP if you selected it.** Ask for a harmless read through a configured server. Check that the app shows a completed tool invocation, rather than only a textual claim that a tool was used.

For example, if your organization exposes DeepWiki, use:

```text theme={"dark"}
Use only the DeepWiki MCP ask_wiki_question tool for facebook/react.
Ask: What is the purpose of React hooks?
Include TFY-GUIDE-VERIFIED in your answer.
Do not read local files or use other tools.
```

You can also open **AI Gateway → Request Logs** in TrueFoundry to find the model request and check which model served it.

You are finished when each selected agent answers through its configured model and each MCP server you need completes a real tool call.

## Change your setup later

| Task | Command |
| - | - |
| Edit choices in the main wizard | `tfy-local-ai-setup personal` |
| Reapply saved choices | `tfy-local-ai-setup update` |
| Inspect saved settings | `tfy-local-ai-setup config show` |
| Sign in again | `tfy-local-ai-setup login` |
| Retrieve a token for an app | `tfy-local-ai-setup token` |
| Edit one agent's model or MCP choices | `tfy-local-ai-setup personal <agent>` |

The main wizard preserves per-agent overrides. Connection and authentication settings remain shared, even when editing one agent. Review any changes affecting other agents before applying.

## Supported agents

Select these together in the main wizard. The command names below are only needed if you later want to edit one agent with `tfy-local-ai-setup personal <agent>`.

| Agent | Command name | What setup configures |
| - | - | - |
| Claude Code | `claude-code` | User settings, credential helper, and MCP servers |
| Codex | `codex` | `~/.codex/config.toml` |
| Claude Desktop | `claude-desktop` | A TrueFoundry third-party profile on macOS/Windows |
| VS Code | `vscode` | Gateway models and MCP configuration; enter the API key in the app |
| Cursor | `cursor` | MCP configuration; finish model setup in the app |
| Gemini CLI | `gemini-cli` | User settings and shell environment |
| OpenCode | `opencode` | User provider and MCP configuration |
| Grok Build | `grok-build` | `~/.grok/config.toml` |
| GitHub Copilot CLI | `copilot-cli` | Shell environment and MCP configuration |
| Goose | `goose` | Custom provider and user configuration |
| Pi | `pi` | Models, settings, and MCP configuration |
| Qwen Code | `qwen-code` | User model-provider and MCP settings |

See [Integration with IDEs](https://www.truefoundry.com/docs/ai-gateway/coding-agents-governance.md) for individual agent guides.

## Troubleshooting

> [accordion] The command does not recognize personal
>
> Rerun the [installation command](#install-the-setup-tool) to download the latest release. Open a new terminal and try again. If the command is still unknown, check that an older copy of `tfy-local-ai-setup` is not earlier on your PATH.

> [accordion] An installed agent is missing or unselected
>
> Make sure its CLI is on your PATH or its supported desktop app is installed. Open a new terminal and rerun the main wizard. Previous selections are preserved, so check the agent's checkbox after installing it.

> [accordion] VS Code lists the model but chat fails
>
> Enter the key through the model row's **Update API Key** menu if required. Select the exact model and use a new **Local** chat on the tested VS Code build. A GitHub sign-in request from the Copilot harness is separate from gateway authentication.

> [accordion] Chat works but MCP needs authentication or waits
>
> Open the agent interactively and complete the server's OAuth flow. Configuring the MCP URL does not authenticate it in every app.

> [accordion] Claude Desktop has no valid active configuration
>
> Open Desktop and save a third-party configuration, then fully quit it and rerun setup. A clean installation may not create the active profile just by launching. If you cannot save that configuration, leave Desktop unselected and ask your administrator for help.

> [accordion] A terminal agent cannot find the token
>
> Open a new terminal after setup so the shell loads its updated environment. Launch desktop apps that rely on `TFY_AGENT_TOKEN`, such as OpenCode, from that terminal. Also check that `tfy-local-ai-setup` is still installed at the path used during setup.

> [accordion] I need a setup log
>
> ```bash theme={"dark"}
> tfy-local-ai-setup update --debug --log-file ./tfy-personal.log
> ```
>
> Logs omit headers and tokens, but can include organization URLs and server names. Review the log before sharing it.

## Remove the setup

```bash theme={"dark"}
tfy-local-ai-setup uninstall
```

Review the removal plan and confirm when ready. Restart your agents and open a new terminal afterwards. A PAT created in TrueFoundry still exists after local uninstall; revoke it in TrueFoundry if you no longer need it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.