Personal setup for coding agents

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

Finds your installed coding agents and lets you select them together.
Signs you in, discovers your gateway, and asks which models and MCP servers to use.
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 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 installed on your computer.
curl on macOS/Linux, or PowerShell on Windows, to download the setup tool.

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.

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 for third-party setup.

Install the setup tool

Run the command for your platform to download the latest release. It installs the tool in your user account without administrator privileges.

macOS (Apple Silicon)
macOS (Intel)
Linux (x86-64)
Windows (x86-64)

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"

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"

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"

Run in PowerShell:

$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

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.

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

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

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. 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.

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 slug, rather than a provider-prefixed model ID. See Codex model configuration.
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

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

Choose MCP servers

Select the MCP servers 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.

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

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.

VS Code
Cursor
Claude Desktop
Terminal agents

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 for model settings and Connect MCP from your IDE for MCP authentication.

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. 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.

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.An agent can answer model requests while a connector still needs authentication. Verify both separately.

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

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.

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.
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:

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 for individual agent guides.

Troubleshooting

The command does not recognize personal

Rerun the installation command 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.

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.

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.

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.

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.

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.

I need a setup log

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

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.

​What setup does

​Before you start

​Install the setup tool

​Run the setup wizard

​Finish setup in your apps

​Verify the setup

​Change your setup later

​Supported agents

​Troubleshooting

​Remove the setup

What setup does

Before you start

Install the setup tool

Run the setup wizard

Finish setup in your apps

Verify the setup

Change your setup later

Supported agents

Troubleshooting

Remove the setup