├── models.json # optional: user-defined models and provider endpoints
140
141
├── auth.json # api keys and oauth tokens (mode 0600)
141
142
├── sessions/ # jsonl transcripts, one dir per cwd
142
143
├── models-cache.json # live /v1/models discovery cache (6h ttl)
@@ -150,6 +151,16 @@ $ZOT_HOME/
150
151
151
152
Drop a `SYSTEM.md` in `$ZOT_HOME` to replace the built-in identity and zot-docs guidance for every run. `--system-prompt` still wins per-invocation. Pass an empty value (`--system-prompt ""`) to intentionally omit the built-in identity. Custom prompts still receive appended instructions and generated context, including `AGENTS.md`, skills, auto-swarm guidance when enabled, and the date/cwd footer. Delete the file to revert to the default.
152
153
154
+
### Configuration files
155
+
156
+
zot keeps both configuration and runtime state under `$ZOT_HOME`, even when that directory is under the platform's state directory. You can edit configuration files there directly while zot is not running:
157
+
158
+
-`config.json` selects the default `provider` and `model` and stores UI preferences. zot also updates it when you change settings or select a model interactively. Explicit `--provider` and `--model` flags override the saved selection for a run.
159
+
-`models.json` optionally defines model metadata and provider endpoints (`baseUrl`). Adding a model here does not select it as the default. See [Custom models](#custom-models).
160
+
-`auth.json` stores credentials, not model definitions. Prefer `/login` for supported providers, and keep secrets out of `config.json` and `models.json`.
161
+
162
+
Neither `config.json` nor `models.json` is required to start zot with an explicit provider and model. Without a saved or explicit provider, zot defaults to Anthropic and may offer login if no usable credentials are available. Ollama needs no login. See [Local models with ollama](#local-models-with-ollama) for minimal configuration and remote-server examples.
163
+
153
164
### HTTP proxy
154
165
155
166
To route zot-managed HTTP and HTTPS requests through one proxy, add `http_proxy` to `$ZOT_HOME/config.json`:
@@ -777,15 +788,20 @@ ollama pull qwen3.5:4b
777
788
zot --provider ollama --model qwen3.5:4b
778
789
```
779
790
780
-
That's it. No API key needed for local models. zot defaults to `http://localhost:11434`.
791
+
No login or API key is needed for local models. zot defaults to `http://localhost:11434`. The model ID must match a model installed on that Ollama server, including its tag. The server must already be running.
781
792
782
-
For a remote ollama instance or one behind auth:
793
+
#### Save a local default
783
794
784
-
```bash
785
-
zot --provider ollama --model llama3 --base-url https://my-server.com/v1 --api-key my-token
795
+
To start with just `zot`, create `$ZOT_HOME/config.json` with the following fields, or merge them into your existing configuration:
796
+
797
+
```json
798
+
{
799
+
"provider": "ollama",
800
+
"model": "qwen3.5:4b"
801
+
}
786
802
```
787
803
788
-
You can also add models to your `models.json` so you don't need flags every time:
804
+
A `models.json` file is not required for this setup. If you want explicit model metadata, add the following to `$ZOT_HOME/models.json`. This registers a model but does not change the default selection in `config.json`:
789
805
790
806
```json
791
807
{
@@ -804,7 +820,89 @@ You can also add models to your `models.json` so you don't need flags every time
804
820
}
805
821
```
806
822
807
-
The `ollama` provider uses the OpenAI chat completions protocol internally, so it also works with any OpenAI-compatible server (vLLM, LM Studio, LocalAI, etc.).
823
+
Set `contextWindow` and `maxTokens` to limits your model and server configuration actually support. These fields inform zot's context and output budgets. They do not configure Ollama's context size or install the model.
824
+
825
+
#### Use a remote Ollama server
826
+
827
+
For a single run, pass the endpoint explicitly:
828
+
829
+
```bash
830
+
zot --provider ollama --model qwen3.5:4b --base-url http://ollama-server:11434/v1
831
+
```
832
+
833
+
For an endpoint behind authentication, use HTTPS and pass `--api-key` with the token. The built-in `ollama` provider uses that flag or a placeholder credential. It does not load a saved Ollama key from `auth.json`.
834
+
835
+
To persist a remote endpoint, keep the `config.json` selection above and add `baseUrl` to the model in `$ZOT_HOME/models.json`:
836
+
837
+
```json
838
+
{
839
+
"providers": {
840
+
"ollama": {
841
+
"models": [
842
+
{
843
+
"id": "qwen3.5:4b",
844
+
"baseUrl": "http://ollama-server:11434/v1",
845
+
"contextWindow": 32768,
846
+
"maxTokens": 8192
847
+
}
848
+
]
849
+
}
850
+
}
851
+
}
852
+
```
853
+
854
+
`--base-url` overrides the model's endpoint for that run. `baseUrl` is a `models.json` field, not a `config.json` field. Only connect to trusted servers and do not expose an unauthenticated Ollama endpoint to the public internet.
855
+
856
+
#### Use the same model on two hosts
857
+
858
+
Models are identified by the pair `(provider, model ID)`. Two entries with the same ID under `ollama` cannot represent independently selectable hosts. A different display `name` does not change that identity.
859
+
860
+
Instead, define a custom provider for each host in `$ZOT_HOME/models.json`, keeping the actual Ollama model ID unchanged:
Save that selection in `$ZOT_HOME/config.json`. Custom providers support stored or environment credentials when required. Discovery-enabled custom providers also work without a key for unauthenticated local servers.
902
+
903
+
`discover` lists models already installed on each server. It does not download models into Ollama. Static `models` entries are optional when discovery is enabled, but let you override the discovered context and output defaults. See [Live model discovery for custom providers](#live-model-discovery-for-custom-providers) for refresh behavior and limitations.
904
+
905
+
The built-in `ollama` provider currently has no dedicated `/login` endpoint-setup flow or automatic model discovery. Use explicit model IDs, static entries, or discovery-enabled custom providers as above. The `ollama` provider uses the OpenAI chat completions protocol internally, so it also works with OpenAI-compatible servers such as vLLM, LM Studio, and LocalAI.
808
906
809
907
### Local models with LM Studio
810
908
@@ -137,6 +137,7 @@ All data lives under `$ZOT_HOME`:
├── models.json # optional: user-defined models and provider endpoints
140
├── auth.json # api keys and oauth tokens (mode 0600)
141
├── auth.json # api keys and oauth tokens (mode 0600)
141
├── sessions/ # jsonl transcripts, one dir per cwd
142
├── sessions/ # jsonl transcripts, one dir per cwd
142
├── models-cache.json # live /v1/models discovery cache (6h ttl)
143
├── models-cache.json # live /v1/models discovery cache (6h ttl)
@@ -150,6 +151,16 @@ $ZOT_HOME/
150
151
151
Drop a `SYSTEM.md` in `$ZOT_HOME` to replace the built-in identity and zot-docs guidance for every run. `--system-prompt` still wins per-invocation. Pass an empty value (`--system-prompt ""`) to intentionally omit the built-in identity. Custom prompts still receive appended instructions and generated context, including `AGENTS.md`, skills, auto-swarm guidance when enabled, and the date/cwd footer. Delete the file to revert to the default.
152
Drop a `SYSTEM.md` in `$ZOT_HOME` to replace the built-in identity and zot-docs guidance for every run. `--system-prompt` still wins per-invocation. Pass an empty value (`--system-prompt ""`) to intentionally omit the built-in identity. Custom prompts still receive appended instructions and generated context, including `AGENTS.md`, skills, auto-swarm guidance when enabled, and the date/cwd footer. Delete the file to revert to the default.
152
153
154
+
### Configuration files
155
+
156
+
zot keeps both configuration and runtime state under `$ZOT_HOME`, even when that directory is under the platform's state directory. You can edit configuration files there directly while zot is not running:
157
+
158
+
-`config.json` selects the default `provider` and `model` and stores UI preferences. zot also updates it when you change settings or select a model interactively. Explicit `--provider` and `--model` flags override the saved selection for a run.
159
+
-`models.json` optionally defines model metadata and provider endpoints (`baseUrl`). Adding a model here does not select it as the default. See [Custom models](#custom-models).
160
+
-`auth.json` stores credentials, not model definitions. Prefer `/login` for supported providers, and keep secrets out of `config.json` and `models.json`.
161
+
162
+
Neither `config.json` nor `models.json` is required to start zot with an explicit provider and model. Without a saved or explicit provider, zot defaults to Anthropic and may offer login if no usable credentials are available. Ollama needs no login. See [Local models with ollama](#local-models-with-ollama) for minimal configuration and remote-server examples.
163
+
153
### HTTP proxy
164
### HTTP proxy
154
165
155
To route zot-managed HTTP and HTTPS requests through one proxy, add `http_proxy` to `$ZOT_HOME/config.json`:
166
To route zot-managed HTTP and HTTPS requests through one proxy, add `http_proxy` to `$ZOT_HOME/config.json`:
@@ -777,15 +788,20 @@ ollama pull qwen3.5:4b
777
zot --provider ollama --model qwen3.5:4b
788
zot --provider ollama --model qwen3.5:4b
778
```
789
```
779
790
780
-
That's it. No API key needed for local models. zot defaults to `http://localhost:11434`.
791
+
No login or API key is needed for local models. zot defaults to `http://localhost:11434`. The model ID must match a model installed on that Ollama server, including its tag. The server must already be running.
781
792
782
-
For a remote ollama instance or one behind auth:
793
+
#### Save a local default
783
794
784
-
```bash
795
+
To start with just `zot`, create `$ZOT_HOME/config.json` with the following fields, or merge them into your existing configuration:
785
-
zot --provider ollama --model llama3 --base-url https://my-server.com/v1 --api-key my-token
796
+
797
+
```json
798
+
{
799
+
"provider": "ollama",
800
+
"model": "qwen3.5:4b"
801
+
}
786
```
802
```
787
803
788
-
You can also add models to your `models.json` so you don't need flags every time:
804
+
A `models.json` file is not required for this setup. If you want explicit model metadata, add the following to `$ZOT_HOME/models.json`. This registers a model but does not change the default selection in `config.json`:
789
805
790
```json
806
```json
791
{
807
{
@@ -804,7 +820,89 @@ You can also add models to your `models.json` so you don't need flags every time
804
}
820
}
805
```
821
```
806
822
807
-
The `ollama` provider uses the OpenAI chat completions protocol internally, so it also works with any OpenAI-compatible server (vLLM, LM Studio, LocalAI, etc.).
823
+
Set `contextWindow` and `maxTokens` to limits your model and server configuration actually support. These fields inform zot's context and output budgets. They do not configure Ollama's context size or install the model.
824
+
825
+
#### Use a remote Ollama server
826
+
827
+
For a single run, pass the endpoint explicitly:
828
+
829
+
```bash
830
+
zot --provider ollama --model qwen3.5:4b --base-url http://ollama-server:11434/v1
831
+
```
832
+
833
+
For an endpoint behind authentication, use HTTPS and pass `--api-key` with the token. The built-in `ollama` provider uses that flag or a placeholder credential. It does not load a saved Ollama key from `auth.json`.
834
+
835
+
To persist a remote endpoint, keep the `config.json` selection above and add `baseUrl` to the model in `$ZOT_HOME/models.json`:
836
+
837
+
```json
838
+
{
839
+
"providers": {
840
+
"ollama": {
841
+
"models": [
842
+
{
843
+
"id": "qwen3.5:4b",
844
+
"baseUrl": "http://ollama-server:11434/v1",
845
+
"contextWindow": 32768,
846
+
"maxTokens": 8192
847
+
}
848
+
]
849
+
}
850
+
}
851
+
}
852
+
```
853
+
854
+
`--base-url` overrides the model's endpoint for that run. `baseUrl` is a `models.json` field, not a `config.json` field. Only connect to trusted servers and do not expose an unauthenticated Ollama endpoint to the public internet.
855
+
856
+
#### Use the same model on two hosts
857
+
858
+
Models are identified by the pair `(provider, model ID)`. Two entries with the same ID under `ollama` cannot represent independently selectable hosts. A different display `name` does not change that identity.
859
+
860
+
Instead, define a custom provider for each host in `$ZOT_HOME/models.json`, keeping the actual Ollama model ID unchanged:
Save that selection in `$ZOT_HOME/config.json`. Custom providers support stored or environment credentials when required. Discovery-enabled custom providers also work without a key for unauthenticated local servers.
902
+
903
+
`discover` lists models already installed on each server. It does not download models into Ollama. Static `models` entries are optional when discovery is enabled, but let you override the discovered context and output defaults. See [Live model discovery for custom providers](#live-model-discovery-for-custom-providers) for refresh behavior and limitations.
904
+
905
+
The built-in `ollama` provider currently has no dedicated `/login` endpoint-setup flow or automatic model discovery. Use explicit model IDs, static entries, or discovery-enabled custom providers as above. The `ollama` provider uses the OpenAI chat completions protocol internally, so it also works with OpenAI-compatible servers such as vLLM, LM Studio, and LocalAI.