Sign-in and configuration.

For setup and updates, see Install and update. Check kaitoi --version and use kaitoi code --help to confirm available commands. Older builds may interpret unsupported code acp or code serve commands as model prompts.

Sign-in gives the CLI access to your Kaitoi account. Configuration controls how Code starts and which preferences it remembers. You can use Code with built-in defaults; a settings file is optional.

See Install and update for installation and update instructions. Commands beginning with kaitoi run in your terminal; slash commands run at Code's You > prompt.

#Sign in through your browser

In your terminal, run:

kaitoi connect login

Complete sign-in in the browser that opens, then return to the terminal and wait for its success message. The browser returns to a temporary local callback on the same computer. The CLI waits up to ten minutes; if the flow times out, start a fresh login.

Check the saved account without displaying its tokens:

kaitoi connect whoami

The output identifies the stored account and whether API and Relay credentials are present. Code's hosted models and account tools need the API credential; Connect uses the relay credential for its tunnels. This command reports the stored login, rather than testing every server permission.

Code and Connect share this CLI login. If you are already inside Code, use /login to sign in or refresh it, then /status to check Authenticated. After a successful sign-in, account tools are available from the next message. If you were using a local model, signing in keeps that model selected.

#Local models can work without sign-in

A local-model conversation does not require a Kaitoi account. With a ready Ollama server, for example, start:

kaitoi code --provider local:ollama

Use /providers to inspect available models. Code can also offer a detected, ready local model from its sign-in prompt. Auto-detection covers Ollama and LM Studio at their usual addresses; other endpoints belong in agent.json. See Hosted and local models for model selection and endpoint setup.

Using a local model does not sign you into Kaitoi. Hosted models, account tools, and Crew still require the CLI login.

#Where the login is kept

New logins use the system keychain when it is available and file storage has not been explicitly selected: macOS Keychain, Windows Credential Manager, or Linux Secret Service. Otherwise the CLI saves credentials in its local credentials file. The terminal's success message tells you which storage was used. Older file-based logins stay there until a new login replaces them.

Credentials are separate from Code's settings. Keep tokens out of config.json, project files, and shared diagnostics. For automation, KAITOI_API_TOKEN overrides the saved API credential; a stale value can therefore mask a refreshed browser login.

To switch accounts, leave any active Code session, then run:

kaitoi connect logout
kaitoi connect login

Check the browser account before completing the new login. Logout clears the CLI's stored login for that environment; it does not sign out the browser or clear a token supplied through an environment variable.

#Check the active session and saved defaults

Inside Code:

/status
/config

/status describes the current session, including its authentication, provider, model, workspace, mode, command availability, and config path. /config shows the loaded config path and its provider, model, and command defaults. It is a summary, not the full file or a reload command.

The two can differ. A launch option can override a saved setting for one session, and changes you make directly in a settings file normally require a new Code session.

#Keep choices for future sessions

Create the optional defaults file from inside Code:

/config init

Code prints the path. An existing file is left in place. A new file contains starter defaults; it does not capture every setting in your current session or switch your active model. After creating it, choose the defaults you want:

/providers
/provider <provider-id>
/model <model-id>

Replace the placeholders with IDs from the list. Choosing a provider without a model follows that provider's default; choosing a specific model pins that choice. /commands on and /commands off also update the saved command default when a writable user config is loaded.

Read the response after changing a setting:

• Saved as your default for new sessions. The choice was written.
• For this session only. No user config was selected for saving; without a config, Code suggests /config init.
• Not saved for new sessions: … The choice could not be saved. For example, the model catalog could not verify it, or the file could not be written.

Model and command choices are not always temporary. Check the save message and /config before assuming the next session will start differently.

#Override a default for one launch

Launch options take precedence over their corresponding saved defaults. For example, keep the agent's command tools off for this session:

kaitoi code --no-commands

That option does not rewrite defaults.commandsEnabled. Similarly, --provider, --model, and --effort choose startup values without saving them. When you supply --provider without --model, Code does not carry over a model saved for another provider.

For ordinary Code sessions, an explicit --commands or --no-commands option wins over defaults.commandsEnabled in config.json. Without either launch option, Code uses the saved command default; without that setting, its built-in default is off. In this example the saved default is on. Starting kaitoi code therefore enables command tools; starting kaitoi code --no-commands disables them for that launch while the saved default remains on. A later plain launch uses the saved value again, provided no setting was changed in between. Enabling command tools does not approve their actions; mode, workspace, and permission checks still apply. The diagram executes no command and changes no settings.

The saved JSON artifact keeps commandsEnabled true in both states. The launch overlay changes only the current session’s command-tool value.

A later /commands on or /commands off is a separate choice and can save a new default. Enabling the agent's command tools does not approve individual actions or remove mode, workspace, and permission checks. See Plan, Build and Crew modes.

#Find the right settings file

Both Code settings files live in your user configuration folder:

System	Default folder
macOS or Linux	~/.config/kaitoi-code/
Windows	%APPDATA%\Kaitoi Code\

On macOS and Linux, XDG_CONFIG_HOME replaces ~/.config when set. Use the path Code reports to locate your file. These are user settings; Code does not load a repository's agent.json as its user configuration.

#config.json: startup defaults and limits

The supported sections are:

Section	What belongs here
defaults	provider, model, commandsEnabled, and outputStyle (markdown or plain).
commands	defaultTimeoutSeconds, maxTimeoutSeconds, and maxOutputChars. These can lower the built-in limits.
runtime	Local recipe Runtime host, port, and autoStart. This is separate from a local language-model server.
localFiles	Additional skip/deny rules: skipDirs, denyFiles, denySuffixes, denyLockfiles, binarySuffixes, and denyGlobs.

For example, this valid partial config keeps command tools off and Runtime autostart disabled:

{
	"defaults": {
		"commandsEnabled": false,
		"outputStyle": "markdown"
	},
	"runtime": {
		"host": "localhost",
		"port": 8766,
		"autoStart": false
	}
}

Merge the settings you want into your existing file, preserving other values. Omitted settings use built-in defaults. runtime.host accepts only localhost, 127.0.0.1, or ::1. Setting autoStart to true lets Code start Runtime when a recipe tool needs it. Local-file rules add restrictions to the built-in policy; they do not remove its protections.

Use valid JSON with the supported keys. An invalid config.json stops Code from starting and reports the file and problem. Restart Code after editing the file, then check /status. /doctor provides more detailed diagnostics, including command limits and their sources.

The command limits have fixed ceilings:

Key	Highest supported value
commands.defaultTimeoutSeconds	120 seconds when the command requests no longer timeout.
commands.maxTimeoutSeconds	600 seconds for any one command.
commands.maxOutputChars	20,000 characters of output shown to the model.

These values can lower the built-in ceilings, not raise them. An older config may still cap commands at 120 seconds. Check /doctor, then raise or remove a lower configured limit if you want to allow the current maximum. Approval and sandbox checks still apply to the command itself.

#agent.json: feature settings and preferences

agent.json lives beside config.json. Features such as local-model endpoints, checkpoints, context compaction, and language servers read their own sections from it. The relevant feature guides describe those schemas.

Section	Keys and limits
sandbox	mode (auto or off), extraWritablePaths, extraDeniedReadPaths; see Permissions and sandbox.
localModels	autoDetect, contextTokens, endpoints; see Local model setup.
checkpoints	enabled; see Checkpoints and rewind.
compaction	auto, thresholdPercent (50–95, default 80), model; see Sessions and context.
lsp	enabled, waitSeconds (1–10, default 3), servers.
autoApprove	model, maxJudgmentsPerTurn (default 50).
agents	roles, maxBackground (1–8, default 3), timeoutSeconds (60–7200, default 1800); see Subagents.

Language servers check edited files when a matching server is installed. They run inside the command sandbox; this feature is unavailable on Windows or when that sandbox is off or unavailable. lsp.waitSeconds controls how long Code waits for their diagnostics.

autoApprove.model chooses the /auto reviewer as provider/model. maxJudgmentsPerTurn limits its reviews in one turn, not the cost of the whole task. Review calls can use credits; see Modes and approvals.

Common preferences have commands you can use directly:

Command	Saved preference
/effort auto	Let the model use its default reasoning effort. Other choices are low, medium, and high, where supported.
/statusline on or /statusline off	Show or hide Code's status line.
/notify system, /notify bell, or /notify off	Choose completion notifications. Availability depends on the terminal and OS.

These choices save under preferences in agent.json and can create that file without /config init. They do not belong in config.json. Code reports whether saving succeeded. For example, the preferences section can contain:

{
	"preferences": {
		"effort": "auto",
		"statusLine": true,
		"notifications": "off"
	}
}

An unusable agent.json produces a warning and falls back to defaults; an invalid section is skipped. Fix the reported problem before relying on those settings. MCP server and hook definitions have their own configuration; see MCP servers and Hooks.

If you previously used Kaitoi Agent, Code can copy a valid legacy config.json into the new location when no Code config exists. It reports the copy and leaves the old file in place. Check the reported path before editing an old settings file.

#Environment variables

Variable	Effect
KAITOI_API_URL	Selects the Kaitoi server to sign in to. kaitoi code --api-url URL overrides it for one launch.
KAITOI_API_TOKEN	Overrides the saved API credential. Keep it out of prompts and committed configuration.
KAITOI_CREDENTIAL_STORE	Set to file to use a local credentials file instead of the system keychain.
KAITOI_NO_UPDATE_CHECK	Set to 1 to disable the daily update check.
OLLAMA_HOST	Changes the address used to discover Ollama.
XDG_CONFIG_HOME	Moves the settings folder on macOS and Linux.

#When a setting or login does not take effect

Symptom	Check next
Browser sign-in succeeded, but Code still has no account access.	Use /login in the active session and check /status. Check whether KAITOI_API_TOKEN overrides the saved login.
The login command says you are already signed in.	Use /login inside Code to refresh it, or logout/login to switch accounts.
The system-keychain login cannot be read.	Follow the reported login-again instruction; do not copy tokens into Code's config.
A model choice disappears next time.	Read its save message, check /config, and verify the model is still in /providers.
Editing a file changed nothing in the current session.	Confirm the path, start a new Code session, and check /status. /config does not reload the file.
Code stops at an invalid-config error.	Fix the named JSON key, type, or limit in the reported file. /config init does not replace an existing file.

For installation, command environments, Runtime, or recipe connection issues, continue with Troubleshooting.