Background service

On Linux and macOS, K-code can run as a service for your user so you do not need to keep a terminal open.

Manage the service

Install the t3 CLI first (Install K-code), then run these commands on the machine that will host K-code:

Uninstalling the service leaves your projects, threads, and settings intact. Running kcode service install again repairs a service that kcode service status reports as broken.

kcode update downloads the newest release on your channel and switches t3 and the service to it. Restarting interrupts running agent turns, terminals, and remote clients, so it asks first; answer no and the service keeps running the old version until you run kcode service restart. Pass --yes from a script. A server you started by hand is left running; stop and start it again to pick up the new version. Wait for any remote update already in progress before updating; to match a remote client’s version, follow Updating K-code.

Pass an exact version (kcode update 0.0.42) to pin one, --channel nightly to switch trains, or --allow-downgrade to move backwards. preview is a maintainers’ test train: its builds can be broken and are never offered as updates, so the installer and kcode update ask for confirmation before installing one.

kcode uninstall removes the background service, the t3 launcher, and the downloaded versions after showing you the list and asking once. Your projects, threads, and settings under ~/.t3/userdata are kept, along with service.env under K-code home. Pass --yes from a script.

Local network access

A service installed before T3CODE_LAN existed keeps listening on the local network. t3 status says so, and t3 up --no-lan turns it off. Any T3CODE_HOST value replaces this setting.

Configure the service environment

Put custom environment variables in service.env under the service’s K-code home directory, normally ~/.t3/service.env. This file survives service installation and updates. For example:

T3CODE_PORT=3773
T3CODE_HOST=127.0.0.1

Use KEY=VALUE entries, quoting values that contain spaces or #. Values are literal: shell commands and variable expansion are not evaluated. Entries override the inherited service environment, except for PATH, T3CODE_HOME, T3_BOOT_SERVICE_UNIT, and T3_SERVICE_LAUNCHER_CONTEXT (including case variants).

Run kcode service restart after changing the file. Changes apply when the service starts again; switching the server version alone keeps the current values. For a service installed before env-file support, run kcode service install once with an up-to-date CLI. A missing file is ignored; other read failures stop service startup. If the file contains credentials, restrict access to that file with chmod 600 (for the default K-code home, chmod 600 ~/.t3/service.env).

Platform support

Linux needs systemd user services. Setup enables lingering so K-code starts at boot and keeps running after logout. If this needs administrator permission, setup prints a recovery command before changing the service.

macOS starts the service when you log in and stops it when you log out. Keep the Mac logged in and awake for unattended remote access. Installing over SSH while nobody is logged in at the Mac’s screen can fail at the final start step; the service is still installed and will start at the next login.

Keep the server responsive when agents use all memory

On Linux, agents already run with lower priority than the server. When they fill the machine’s memory, though, the kernel may still slow down or stop the server, because only an administrator can reserve memory for it. Run, as your normal user:

kcode service protect

It shows the system settings it will change, asks before applying them, and then asks for your sudo password. If the machine runs Tailscale or SSH, it also offers to protect them, so you can still reach the machine. Memory protection takes effect at once. The server’s protection from the kernel’s out-of-memory killer takes effect after kcode service restart. kcode service status reports whether the protection is in place, and kcode service protect --undo removes it.

Troubleshooting

Start with kcode service status on the host. It prints the log path and, on Linux, checks whether the installed service is running, enabled, and allowed to survive logout.

If it stops when your SSH session closes, check for linger-disabled. An administrator can enable lingering with:

sudo loginctl enable-linger "$(id -un)"

Over SSH, allow sudo to prompt:

ssh -t your-server 'sudo loginctl enable-linger "$(id -un)"'

Then retry service setup as your normal user. Run only the loginctl command with sudo; running K-code as root creates a separate installation and Connect identity. Without administrator access, run kcode serve in a terminal and keep that session open.

On macOS, check System Settings → General → Login Items if the service no longer starts at login. If agent work cannot access Desktop, Documents, or Downloads, it may need Full Disk Access for the kcode executable listed in ProgramArguments in ~/Library/LaunchAgents/com.t3tools.t3code.service.plist.

Reclaim database space

K-code removes internal history older than a day on its own while it runs; your conversations are kept. Databases created before this shrank automatically still hold the freed space on disk until a one-time offline repair returns it and turns on automatic shrinking. Settings > Maintenance (web and desktop) or Settings > Maintenance (mobile) suggests the repair when at least 1 GiB can be reclaimed.

Run kcode doctor on the machine that hosts the environment. It reports the database size and the space it can reclaim, then asks which repairs to run; pass --fix to run the recommended ones without a prompt (for scripts), or --dry-run to only report. An installed background service for the same data directory is stopped for the repair and started again afterwards, also when the repair fails. Quit a server you started by hand, or the desktop app, first: the repair refuses to touch a database that is in use. Use --base-dir for a different data directory.

The repair can take several minutes on a large database. It rebuilds the database through a temporary copy, so it needs free space of about the database’s size twice over: once in the system temporary directory (TMPDIR or /tmp on Linux and macOS) and once next to the database for its write-ahead log.

If you upgraded from a version before 0.1.0, its database (state.sqlite) is still kept next to the current one so you can roll back. kcode doctor offers to delete it, but never selects that repair for you and --fix skips it: once it is gone, a version before 0.1.0 starts with no threads or settings.

Found a mistake?Edit this page on GitHub.