Configuration#

PacketCode stores its user configuration in config.toml under the PacketCode data home. By default that home is ~/.packetcode. Set PACKETCODE_HOME to an absolute directory before starting PacketCode to relocate the complete state.

Before you start#

• PacketCode has completed first-run setup, or you have created the data home.
• The configuration file is readable only by the intended user.
• Secret environment variables are supplied outside the project repository.

Minimal configuration#

[default]
provider = "ollama"
model = "qwen2.5-coder:14b"

[providers.ollama]
host = "http://localhost:11434"
default_model = "qwen2.5-coder:14b"

[permissions]
profile = "balanced"

The main groups are:

• [default]: provider and model selected for new sessions.
• [providers.<slug>]: credential, endpoint and provider defaults.
• [behavior]: compaction, retries, background-work limits and backup retention.
• [permissions]: active profile and ordered rules.
• [packet_computers]: remote-work feature switch.
• [acp]: optional local ACP stdio server switch.
• [mcp.<name>]: local MCP process definitions.
• [statusline]: external status command and timeout.

Project .env files and process environment variables can override provider credentials. Do not commit either secrets or a user config containing keys.

When PacketCode saves the file itself — after sugar login, /provider, /effort or the API-key picker — it edits only the settings it changed. Your comments, key order and spacing are preserved, as are any keys a newer build wrote that this one does not recognise.

Settings checked at startup#

The interactive interface, packetcode run and packetcode acp validate the loaded configuration at startup and print each problem to standard error. Each line carries the prefix of the command that printed it — packetcode: config, packetcode run: config or packetcode acp: config — then names the setting and, where a value is missing, the environment variable to set. The interactive interface prints its list after first-run setup, so a genuine first run is not warned about the key it is about to be asked for.

These are warnings, not failures. Every one of them is a setting PacketCode starts in spite of, applying its default instead. packetcode doctor reports the same list as its config.validation check, so a diagnostic run and a running session cannot disagree about which settings are inert. See Troubleshooting for the problems it reports and how to clear them.

Undo backup retention#

/undo restores files from a backup tree kept under backups in the data home. The undo history is held in memory and resets when PacketCode starts, so a tree left by a session that has already exited can never be used again. Each start prunes those unreachable trees once.

[behavior]
backup_retention_days = 14

The default window is 14 days. The tree for the session being started is never removed, whatever its age. Set backup_prune_disabled = true to keep every tree instead; a zero or negative backup_retention_days falls back to the default rather than disabling pruning.

Job records, background-agent worktrees and stored sessions are not pruned. Remove those yourself when you no longer need them.

Environment variables#

Provider credential variables are named per provider; packetcode doctor reports which variable the active provider expects. For what the diagnostic log records and what it never records, see Troubleshooting.

Verify#

packetcode doctor
packetcode

Confirm Doctor names the intended data home, reports config.validation with no outstanding problems, the selected provider is ready, and a new session starts with the expected model and permission profile. Starting the interface should print no packetcode: config line to standard error.