Niluxv1.0.11
/get-started

Configuration.

Nilux keeps configuration in plain files — no hidden databases, no magic registries. Global settings live in ~/.nilux/, project-scoped files live in your repo.

File map

Every file Nilux reads or writes. Nothing else touches the filesystem.

plaintext
# Global (per-user)
~/.nilux/
  config.json          # auth, model, language, thinking
  nilux.md             # user-wide instructions
  rules/*.md           # user-wide rules
  agents/*.md          # custom agent definitions
  skills/              # custom skills
  settings.json        # MCP servers (user scope)
  projects/<slug>/     # per-project sessions, todos, memory
# Project (in your repo)
nilux.md               # project instructions — commit this
nilux.local.md         # private overrides — gitignore this
.mcp.json              # MCP servers (project scope)
.nilux/
  settings.json        # permission rules (auto-generated)
  rules/*.md           # project rules
  agents/*.md          # project-scoped agents
  skills/              # project-scoped skills

nilux.md — project instructions

This is the most important config file. It tells the agent what your project is, how it should behave, and what to avoid. Nilux loads it into every conversation as context.

markdown
# nilux.md
This is a Next.js 16 + Prisma monorepo.
## Rules
- Never modify files in billing/* without asking.
- Always run tests after editing middleware.
- Use pnpm, not npm.
## Architecture
API routes in src/app/api/. Database models in prisma/schema.prisma.

Nilux discovers instructions in this order. Later files take priority:

  1. ~/.nilux/nilux.md — your global preferences, applied to every project
  2. ~/.nilux/rules/*.md — global rules (alphabetical)
  3. nilux.md — project instructions, checked into git
  4. .nilux/rules/*.md — project rules (alphabetical)
  5. nilux.local.md — private overrides, never committed
TIP

Run /init inside a session to have Nilux generate a nilux.md for your project based on its structure.

You can include other files with @path/to/file.md on its own line. Nilux resolves includes relative to the file, up to 5 levels deep.

Global config

~/.nilux/config.json stores account-level settings. Nilux manages this file — you rarely need to edit it by hand.

json
{
  "llm_mode":   "standard",     # active model tier
  "language":   "English",       # response language
  "show_thinking": true,        # show reasoning
  "thinking_mode": true,        # deep reasoning
  "server_url": "https://api.nilux.dev"
}

Most of these are easier to change through slash commands during a session:

  • /model — switch model tier (Standard, Pro)
  • /config — toggle language, thinking mode, vision, memory
  • /agents — assign models to individual agents

Permission rules

When Nilux asks to run a command or edit a file, you see a numbered menu. Choosing option 2 saves a persistent allow-rule to .nilux/settings.json:

json
{
  "permissions":  {
    "allow":  [
      "Bash(git status:*)",   # allow all git status
      "Bash(pnpm test:*)",    # allow pnpm test + args
      "Read"                   # allow reading any file
    ],
    "deny":  [],
    "additionalDirectories":  []
  }
}
NOTE

Dangerous operations like rm -rf, git reset --hard, and DROP TABLE always require approval regardless of rules.

MCP servers

MCP connects Nilux to external services — databases, APIs, cloud providers. Add servers via CLI or edit .mcp.json directly:

bash
# Add a stdio server (runs as a child process)
$nilux mcp add --transport stdio --scope project my-server -- npx -y @org/mcp-server
# Add a network server (connects via URL)
$nilux mcp add --transport sse --scope user my-api http://localhost:8080/mcp
json
// .mcp.json
{
  "mcpServers":  {
    "my-server":  {
      "command":  "npx",
      "args":  ["-y", "@org/mcp-server"]
    },
    "my-api":  {
      "url":  "http://localhost:8080/mcp",
      "transport":  "sse"
    }
  }
}

Three scopes, last wins: ~/.nilux/settings.json (global) → .mcp.json (project) → ~/.nilux/settings.local.json (private).

Environment variables

Two environment variables are supported:

  • NILUX_SERVER_URL — override the API server address. Takes priority over config.json.
  • NILUX_GIT_BASH_PATH — custom path to Git Bash (Windows only).

Per-project storage

Session history, todos, and memory are stored per-project in ~/.nilux/projects/<slug>/ where the slug is derived from your project path. These files stay on your machine — Nilux never uploads them. (The conversation itself is sent to the server while you're working and when you resume a session.)

plaintext
~/.nilux/projects/my-app/
  sessions-index.json  # fast index for /resume
  <uuid>.jsonl         # conversation logs
  todos.json           # project todos
  session_memory.md    # session summary
  file-history/        # checkpoints for /rewind

Use /resume to pick up a previous session. Use /rewind to roll back file changes to an earlier checkpoint.

← Previous · QuickstartNext · Permission modes →