Running it

Configuration

One JSON file, twelve environment overrides, and everything else under ~/.crv/. Your project directories are never written to except by the edits you ask for.

The config file

Written on first run to ~/.config/cerveau/config.json. Defaults come from config.Default() in internal/config/config.go.

{
  "project":      "cerveau",
  "addr":         "127.0.0.1:7700",
  "workspace":    ".",
  "sessions_dir": "~/.crv/sessions",
  "model_ctx":    32768,
  "endpoints": {
    "model":     "http://localhost:8080",
    "embedder":  "http://localhost:8081",
    "typesense": "http://localhost:8108"
  }
}

The path matters The core reads ~/.config/cerveau/config.json. It does not read ~/.crv/config.json — writing there is silently ignored, which is an easy hour to lose.

Fields

Field	Default	Notes
`project`	`cerveau`	Namespace for the Typesense collections.
`addr`	`127.0.0.1:7700`	Where the core binds. Loopback deliberately — the API is unauthenticated and can run shell commands. Set it to something else only behind your own auth.
`workspace`	`.`	The directory the agent operates in. File tools are jailed to it, symlinks included.
`sessions_dir`	`~/.crv/sessions`	One directory per session, holding its episodic log.
`model_ctx`	`32768`	The context budget the packer plans against. Must match what your engine actually serves — see the warning below.
`typesense_key`	generated	Written on first run for the managed instance.
`typesense_managed`	`false`	Set when Cerveau spawned the instance itself.
`remote_access_token`	unset	Gates every API route and the panel once set. Required before `addr` may be anything but localhost. Minted by pairing — see Pocket.
`endpoints.model`	`localhost:8080`	Your Core. Any OpenAI-compatible chat-completions endpoint.
`endpoints.embedder`	`localhost:8081`	OpenAI-compatible `/v1/embeddings`. Optional; without it recall is keyword-only.
`endpoints.typesense`	`localhost:8108`	Where memory is searched.

model_ctx has to match the engine The window manager plans every turn against this number. Serve 96K but leave this at 32K and the packer trims history it never needed to; serve 32K and set 96K and requests will be rejected mid-build. Change both together.

Environment variables

Every CRV_* variable overrides the config file at load time. Useful for systemd units, where the file is shared but one machine differs.

Variable	Overrides
`CRV_ADDR`	`addr`. Also the base URL `crvcli` talks to.
`CRV_MODEL_URL`	`endpoints.model`.
`CRV_MODEL_NAME`	The model name sent in each request. vLLM validates it; llama.cpp ignores it.
`CRV_MODEL_KEY`	Bearer token for the model endpoint. vLLM returns 401 without it.
`CRV_EMBEDDER_URL`	`endpoints.embedder`.
`CRV_TYPESENSE_URL`	`endpoints.typesense`.
`CRV_SESSIONS_DIR`	`sessions_dir`.
`CRV_RFX_DIR`	Where RFX packs are loaded from. See RFX packs.
`CRV_REMOTE_ACCESS_TOKEN`	`remote_access_token`.
`CRV_TEMP`	Sampling preset. See Sampling.
`CRV_TIMEOUT`	Per-request timeout against the model endpoint.
`CRV_CHROME`	Path to the Chrome/Chromium binary `check_page` drives.

Sampling

Sampling is a preset rather than a pile of knobs, set with CRV_TEMP or through GET/POST /api/sampling at runtime. The panel exposes it as a dial. A small model is far more sensitive to these than a frontier one — a temperature that reads as "creative" on a large model reads as "unable to follow a schema" on a 3B active-parameter one.

Where things live

~/.config/cerveau/config.json

The config the core reads. Mode 0600 once a token is written into it.

~/.crv/sessions/

One directory per session: the episodic log, plans, reports.

~/.crv/models/

Where the embedder sidecar looks for its weights by default.

~/.crv/bin/crv

Conventional install location if you are running under systemd.

~/.crv/pair.id

The one-shot pairing id, deleted the moment it is used.

~/.crv/devices.json

Registered devices: id, public key, when they were added and last seen.

Switching workspace

The workspace can be changed at runtime without a restart, from the panel or over the API:

curl -X POST localhost:7700/api/config/workspace \
  -H 'content-type: application/json' \
  -d '{"path":"/home/you/projects/thing"}'

The file-tool jail, the code index and the guard's rm boundary all re-anchor to the new root. See HTTP API.

PreviousBrain Cores NextCLI