Configuration

CodeTeleport stores its configuration in a single JSON file. This file is created automatically when you log in and is used by both the codeteleport CLI and the codeteleport-mcp server.

File location

~/.codeteleport/config.json

The full path is $HOME/.codeteleport/config.json on both macOS and Linux. 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"
}

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.

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.

Editing the config manually

You can edit the file directly if needed, but in most cases the CLI handles everything. Common reasons to edit manually:

• 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)

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:

Not logged in. Run `codeteleport auth login` first.

or:

Config file is corrupted. Run `codeteleport auth login` to re-authenticate.

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