Docker

Kolo works inside Docker. It writes everything to a .kolo directory in the working directory of the traced process: the text traces in .kolo/traces/, .kolo/kolo.txt, and its own data in .kolo/.internal/. Set KOLO_PATH to put .kolo somewhere else.

To read or grep traces from your host, or to let a coding agent running on your host read them, the .kolo directory needs to be on a volume that is mounted from the host. Most projects already mount their working directory, in which case no extra configuration is required. You can also run kolo cat and the other CLI commands inside the container.

Mounting the working directory

For example, with this in your Dockerfile:

WORKDIR /code
COPY . ./

you need the corresponding volume definition in your docker-compose.yml:

services:
  web:
    volumes:
      - .:/code

This puts the .kolo directory on your host as well as inside the container. The Kolo VSCode extension needs this too.

Docker on Mac

Docker’s file sharing on macOS can interfere with Kolo reading and writing the SQLite database it keeps in .kolo/.internal/. If you run into this, we recommend enabling “VirtioFS accelerated directory sharing” (Docker Desktop 4.6 or later), or working inside the container with VSCode’s Dev Containers extension.

File ownership

If traces don’t show up on your host, or you can’t read them, it may be because the .kolo directory is owned by root. This can happen in some cases, depending on how Docker is set up. To check whether the .kolo directory is owned by root, run ls -ld .kolo.

You can fix this by changing the ownership of the .kolo directory to the current user, for example by running sudo chown -R $USER .kolo