Configuration

CodeTeleport stores its configuration in a single JSON file. This file is created when you run codeteleport setup and is used by both the codeteleport CLI and the codeteleport-mcp server. setup is also where you pick your coding agent (Claude Code, Codex, or Antigravity).

File location

~/.codeteleport/config.json

The full path is $HOME/.codeteleport/config.json on macOS and Linux, and %USERPROFILE%\.codeteleport\config.json (e.g. C:\Users\alice\.codeteleport\config.json) on Windows. There is no global or system-level config — each user account has its own.

Fields

A typical config file looks like this:

{
  "token": "ctk_live_a1b2c3d4e5f6...",
  "apiUrl": "https://api.codeteleport.com/v1",
  "deviceName": "alices-laptop",
  "agent": "claude-code"
}

Field	Type	Description
token	string	Your API token, prefixed with ctk_live_. Created during login and used for all API requests.
apiUrl	string	The CodeTeleport API endpoint. Defaults to https://api.codeteleport.com/v1. Changes if you use --api-url during login.
deviceName	string	A human-readable name for this machine. Auto-detected from your system hostname.
agent	string	The AI coding agent this machine uses. One of claude-code (default), codex, or antigravity. Chosen during codeteleport setup or via codeteleport config set agent <id>. Determines which session store is bundled on push and scanned on local list.

The agent field is optional: configs that omit it (including older configs written before multi-agent support) default to claude-code. The chosen agent determines the local session store CodeTeleport reads (e.g. ~/.claude/projects for Claude Code, ~/.codex/sessions for Codex, ~/.gemini/antigravity-cli/conversations for Antigravity) and the resume command shown after a pull — claude --resume <id> for Claude Code, codex resume <id> for Codex, agy --conversation <id> for Antigravity. The agent setting only affects what is bundled and scanned locally (push, local list); it does not affect pull, which always uses each bundle’s own recorded agent. See codeteleport config and codeteleport setup for details.

Device naming

The deviceName is derived from your system’s hostname with the .local suffix stripped. For example:

Hostname	deviceName
alices-laptop.local	alices-laptop
dev-server-01	dev-server-01
bobs-desktop.local	bobs-desktop

This name appears in the session list and dashboard so you can tell which machine a session was pushed from. It is set once at login time and does not change if you rename your computer afterward.

File permissions

The config file is created with 600 permissions (owner read/write only):

ls -la ~/.codeteleport/config.json

-rw-------  1 alice  staff  142 Mar 31 14:22 /Users/alice/.codeteleport/config.json

This prevents other users on the same machine from reading your API token. If permissions are accidentally changed, you can fix them:

chmod 600 ~/.codeteleport/config.json

Caution

Your config file contains a live API token. Do not commit it to version control, share it, or copy it to untrusted locations. If you suspect the token has been exposed, revoke it from the dashboard and run codeteleport auth login again to refresh just the token (your agent selection is preserved), or codeteleport setup for a full re-configure.

Editing the config manually

You can edit the file directly if needed, but in most cases the CLI handles everything. The supported way to update settable keys is codeteleport config set <key> <value>, which works for agent, deviceName, and apiUrl without editing the file by hand. Running codeteleport config with no arguments prints the current configuration. Common reasons to change these values:

• Switching API endpoints — change apiUrl to point to a staging or local server (e.g., http://localhost:8787/v1)
• Renaming your device — change deviceName to something more descriptive (e.g., work-laptop instead of C02X1234ABCD)
• Switching agents — change which coding agent is used, e.g. from Claude Code to Codex. Prefer codeteleport config set agent codex (valid ids: claude-code, codex, antigravity) since it validates the id; hand-editing to an unknown agent id will cause commands to fail with Unknown agent: <id>. Supported: claude-code, codex, antigravity.

After editing, the changes take effect on the next CLI or MCP command. No restart is needed.

Missing or corrupted config

If the config file is missing or cannot be parsed, the CLI exits with an error:

CodeTeleport is not configured yet. Run `codeteleport setup` to get started.

or:

Config file is corrupted. Run `codeteleport setup` to re-configure.

Running codeteleport setup creates a fresh config file and resolves both cases.