Configuration

This reference covers every configuration surface of loop-task: environment variables, the data directory layout, interval and color syntax, the HTTP API defaults, log rotation settings, and IPC transport details.

Environment variables

Two environment variables control the runtime behaviour of loop-task.

LOOP_CLI_HOME overrides the default data-directory location. When unset, all state is stored under ~/.loop-cli. LOOP_CLI_HTTP_PORT changes the port the HTTP API listens on. The MCP server variables control the Model Context Protocol server, see MCP Server for details.

The HTTP API bind host is not controlled by an environment variable — it defaults to 0.0.0.0 (all interfaces) and is configurable at runtime via loop-task http-host. See CLI Reference for details.

Data directory structure

The data directory ($LOOP_CLI_HOME or ~/.loop-cli) contains the following files and directories.

• loops.json, tasks.json, and projects.json are the authoritative data stores. They are read at startup and written on every mutation.
• logs/ contains one log file per loop instance, named by the loop ID. Files are appended to and rotated automatically (see Log rotation).
• daemon.pid holds the PID of the running daemon process. It is written on daemon start and removed on clean shutdown.
• daemon.sig stores the SHA-1 hash of the dist/ directory at daemon launch time. The daemon compares this signature periodically to detect code changes and trigger a restart.
• daemon.log captures daemon-level diagnostics (startup, shutdown, keep-alive checks). It is distinct from per-loop log files.

Interval syntax

The interval field on loops and tasks accepts the following formats.

Intervals are specified as a positive integer followed by a single-letter unit (s, m, h, d, w). A value of manual or the literal string 0 disables automatic scheduling; the loop or task will only run when triggered explicitly.

Project colors

Projects may be assigned a colour for display in list and TUI views. Six named colours are built in, and any hex colour is also accepted.

In addition to the six named values, any hex colour string (e.g. #ff6b6b, #aaccff) is accepted. Colour values are validated on input; invalid strings produce a configuration error.

HTTP API

The HTTP API server binds to 0.0.0.0 (all interfaces) by default, making it reachable remotely. The bind host is configurable at runtime via loop-task http-host — restrict to localhost with loop-task http-host local.

The API is unauthenticated. When bound to anything other than 127.0.0.1, secure access at the network layer (SSH, Tailscale, firewall).

All API endpoints are served under the /api/ prefix. The Swagger UI provides an interactive documentation browser. The raw OpenAPI 3.0 specification is available at /api/openapi.json for use with code-generation tools and API clients.

Log rotation

Per-loop log files are rotated automatically when they exceed the maximum file size.

When a log file reaches the 1 MB threshold it is rotated: {id}.1.log is renamed to {id}.2.log, {id}.log is renamed to {id}.1.log, and a fresh {id}.log is created. Older generations beyond the max are discarded.

Each run is written as a header line followed by the captured output and a final exit-code line:

=== RUN 2026-07-09T10:00:00Z loop-name (task-id) ===
<captured stdout / stderr>
--- EXIT 0 ---

IPC

Inter-process communication between the CLI client and the daemon uses socket transport with a JSON-lines protocol.

• Each message is a single line of JSON terminated by \n.
• The client opens a connection, sends a request, and waits for a response with a 10-second timeout. If the daemon does not respond within that window the client treats the request as failed.
• On POSIX systems the socket file is created inside the data directory and cleaned up on daemon shutdown. On Windows the named pipe is managed by the operating system and does not persist on disk.