Configuration

Config file

The CLI stores its configuration in ~/.ix/config.yaml. Read and write it with ix config:

ix config show                # everything
ix config get endpoint        # one value
ix config set format llm      # set a value

Environment variables

Variable	Effect
IX_HOME	Relocates everything under ~/.ix, configuration included. Useful for giving a CI job or a second install its own state. It’s read at use, not at install, so move ~/.ix there rather than expecting the old configuration to be found
IX_FORMAT	Default output format: text, json or llm. Overrides the config file. --format overrides it
IX_TOKEN=<token>	Bearer token sent to a local backend (localhost or another loopback address) on every request. Overrides the stored local token (see Local token). Never sent to any other endpoint
IX_DEBUG=1	Prints full stack traces on errors, and one stderr line per backend request with the X-Correlation-Id it sent (the backend tags its request and slow-query logs with it). Every request of one ix run shares the id’s prefix
IX_READ_DEADLINE_MS=<ms>	How long one command’s reads may take in all before it fails (default 60000), so a hung backend fails a query in a minute rather than after each request’s 2-minute timeout. The clock restarts after each write the command makes. ix map, ix ingest and ix stats have no read deadline. 0 turns it off. A read that meets a refused or dropped connection, or a 502/503/504, is retried once; writes are not, except as IX_COMMIT_CONFLICT_RETRIES and IX_COMMIT_TRANSIENT_RETRY_MS describe
IX_MCP_SUBPROCESS=1	Runs each MCP tool call in its own ix process
IX_COMMIT_FAILURE_LIMIT=<n>	Consecutive failed commits before ix map stops (default 5). It stops after one when the backend reports its database unreachable. 0 never stops
IX_COMMIT_CONFLICT_RETRIES=<n>	Retries of one commit after a lock conflict or a dropped connection (default 6). 0 turns these retries off. It does not affect the 502/503/504/429 retries; see IX_COMMIT_TRANSIENT_RETRY_MS
IX_COMMIT_TRANSIENT_RETRY_MS=<ms>	The total time one bulk commit may spend retrying after a 502, 503, 504 or 429, counting both the requests and the waits between them (default 5000, at most three retries, and at most one after a 504). A bulk is sent again only if another request as long as the one that failed still fits, so a slow bulk goes straight to the per-file fallback. Retry-After is honoured up to that limit; a longer value is cut to it. 0 turns these retries off
IX_COMMIT_BASE_REV_RETRIES=<n>	Re-sends of a commit after another writer on the same backend moved the graph revision under it (default 8)
IX_PARSE_BUDGET_MS=<ms>	How long ix map / ix ingest may spend parsing one file before skipping it and naming it in the summary (default 10000). A skipped file is tried again on every run, and ix status warns about it until it is in the graph. 0 turns the budget off
IX_PARSE_WORKERS=<n>	Most parse workers ix map / ix ingest starts (default 8, never more than the cores less one). Workers start as files need them, one per 50 files
IX_RECONCILE_ON_FORCE=1	Makes an ix map --force (or ix ingest --force) also remove nodes an earlier extractor wrote and the current one no longer does, at the files’ current content. ix map does this by itself on the run after an extractor change, on a backend from 1.0.33 that applies deletes in bulk. Set this to finish a cleanup that run could not do (an older backend, since upgraded) or did not finish (its budget ran out): it reads only what was left. Without a record of what was left, it reads the patch of the extractor before the current one for every file
IX_ORPHAN_SWEEP_MAX_MS=<ms>	Time budget of that cleanup in one run (default 60000). Files past it are committed without the cleanup and named for the next IX_RECONCILE_ON_FORCE=1 run
IX_ORPHAN_SWEEP_MAX_REQUESTS=<n>	Request budget of that cleanup in one run (default 25000): one stored-patch read per file, one node read per 1000 candidates
IX_PATCH_ACTOR=<actor>	The actor stamped on each graph patch ix map / ix ingest sends (default ix/ingestion; ix ingest --github uses ix/github-ingest). Set it to empty (IX_PATCH_ACTOR=) for a backend that authenticates writers and stamps the verified principal itself: such a backend rejects a non-empty actor that differs from the principal with 403 body actor ... conflicts with verified principal. Any other value is sent as the actor
IX_LOAD_ALL_COMMANDS=1	Loads every command module on each call, as releases before the start-up fast path did. Without Ix Pro installed, ix <command> normally loads only that command; with Ix Pro installed every call already loads everything, so this changes nothing there. If a command misbehaves on an install without Pro, try it again with this set: a difference between the two is a bug worth reporting

Bootstrap script variables

These apply to the agent skill’s bootstrap.sh:

Variable	Skips
IX_SKIP_INSTALL=1	Installing the CLI
IX_SKIP_BACKEND=1	Starting and waiting for the backend
IX_SKIP_MAP=1	Running ix map
IX_SKIP_COMPASS=1	Restoring Compass with ix upgrade

Directories

Path	Contents
~/.ix/config.yaml	CLI configuration
~/.ix/backend/	Docker Compose file for the local backend, its .env (the local token, mode 0600) and an optional docker-compose.override.yml
~/.ix/cli/	The installed CLI
~/.ix/cli/compass/	Compass assets, fetched by ix upgrade

Ports

All services bind to 127.0.0.1 only.

Port	Service
8090	Ix Memory Layer (the HTTP API)
8080	Compass (ix view), configurable with --port

ArangoDB has no host port: it runs without authentication, so only the memory layer reaches it, over the Compose network. To use its web UI, publish the port yourself in ~/.ix/backend/docker-compose.override.yml, which ix docker applies, then run ix docker stop and ix docker start (a backend that is already healthy is left as it is, so ix docker start alone does not apply it):

services:
  arangodb:
    ports:
      - "127.0.0.1:8529:8529"

Local token

The backend refuses requests from other hosts, from web pages and with non-JSON bodies. It can also require a bearer token, so that another local process cannot use it without the token in ~/.ix. This is opt-in for now:

ix docker start --local-token     # generate a token, store it, restart the backend requiring it
ix docker start --no-local-token  # stop requiring it and forget it
ix doctor                         # "Backend token" says whether it is required and accepted

The token is stored as auth.local_token in ~/.ix/config.yaml and written to ~/.ix/backend/.env for Compose. The CLI and ix view send it only to a local endpoint. IX_TOKEN overrides it, under the same rule: no token, stored or from IX_TOKEN, is sent to a backend on another host. To use a token-protected backend elsewhere, forward its port to this machine (for example ssh -L 8090:localhost:8090 <host>) and point IX_ENDPOINT at http://localhost:8090.