Configuration¶
Learn how to configure janito for your needs.
Topics¶
- Providers - Configure OpenAI, local servers, or custom providers
- Provider Variants - Multiple configurations for the same provider (
<provider>-<word>) - Secrets - Manage API keys and sensitive credentials
Configuration File¶
janito stores your configuration in ~/.janito/. The main configuration file is ~/.janito/config.json.
Custom config directory: Use
-c/--config-dir <dir>to store all config (config, auth, secrets, MCP services and skills) in a different directory instead of~/.janito. For example:janito -c ~/myconf --set provider=openai.Project-local config:
./.janito(the current working directory) is always resolved first, falling back to the global~/.janitodirectory. Use-l/--localto store config, API keys and secrets in./.janitoinstead of~/.janito;--list-keys/--list-secretsshow both. For example:janito -l --set model=gpt-6-luna. The shell commands/provider <name>and/model <name>also persist their selection to the project-local./.janito/config.json(never the global one), so the next session in the same project resumes with the chosen provider/model.
View Configuration¶
Configuration Options¶
These keys are stored in ~/.janito/config.json (set them with --set).
Keys are scoped — model/endpoint live per provider and the model-level
keys per provider and model (see the note below and
CLI Options — Configuration Keys):
| Option | Scope | Description | Default |
|---|---|---|---|
provider |
flat | Provider name (openai, google, custom, alibaba, deepseek, minimax, meta, xiaomi, moonshot, zai, xai, mistral, anthropic, apertus, atria, opencode-go, openrouter) |
openai |
model |
per provider | Model name | provider's built-in default model |
endpoint |
per provider | API endpoint URL (required for custom providers) |
provider's built-in default |
max-input-tokens |
per provider/model | Maximum input tokens (context window) | model built-in |
max-output-tokens |
per provider/model | Maximum output tokens | model built-in |
effort |
per provider/model | Reasoning depth (none…max) |
model built-in |
api-type |
per provider/model | API type (Responses, Completions, Anthropic, DashScope, Gemini) |
model built-in default |
stateless-mode |
per provider/model | Whether the Responses API keeps conversation state server-side | model built-in default |
disabled-tools |
per provider/model | External tools hidden from the model (e.g. WebSearch when native server-side search exists; comma-separated or JSON list) |
derived default (WebSearch for native-search models) |
used-files |
flat | Whether the end-of-turn Used files report is printed by the CLI/shell |
false |
role |
flat | Role in the built-in system prompt; overridden by -R/--role |
software developer |
system-prompt |
flat | Literal text used as the system prompt's start section |
built-in base prompt |
system-prompt-file |
flat | Path to a file whose content becomes the start section (~ is expanded, relative paths resolve against the working directory); wins over system-prompt when both are set |
unset |
Role (role)¶
Choose a role that matches your task. The role gives the model a useful
perspective and helps guide its terminology, priorities and level of detail.
For example, use systems engineer for infrastructure design or technical
writer for documentation. The default, software developer, suits coding
work; a task-appropriate role can make other responses more relevant.
janito -R "systems engineer" "Review this deployment design"
janito --role "technical writer" "Improve this user guide"
janito --set role="systems engineer" # persist for future sessions
janito --get role # inspect the stored setting
janito --unset role # remove the configured override
janito -R "systems engineer" --show-system-prompt
Resolution order is -R/--role > configured role > software developer.
At startup, the line immediately below the version banner displays
Janito role is <role>, with the resolved role in bold green.
The CLI flag affects only the current run and does not change configuration.
The setting is global, not provider- or model-scoped, and follows normal
project-local configuration precedence. Removing a local override may expose
a global value; with no configured role, the built-in default applies.
Uppercase -R sets the role; lowercase -r still grants READ privilege.
The built-in prompt includes the resolved role before model requests:
This applies to single-prompt runs, interactive chat, and new web sessions
(e.g. janito --web -R "systems engineer"). It does not rewrite existing
conversations. Custom prompts supplied with -S, system-prompt or
system-prompt-file are used unchanged: their placeholders are not
interpolated and no role line is added. -Z disables the system prompt entirely.
A role is guidance, not a permission setting or a guarantee of expertise. It does not grant tools or read/write/execute privileges. Continue to provide clear task instructions and verify important results.
System prompt (system-prompt / system-prompt-file)¶
janito --set system-prompt="You are a terse assistant"
janito --set system-prompt-file=~/agents/base-prompt.md
When set, the configured text becomes the system prompt's start section;
the tools, skills, agents.md and plugin sections stay unchanged.
-S/--system-prompt
overrides the config value for that run (without changing it), and
-Z/--no-system-prompt disables the prompt entirely. --show-system-prompt
and the shell /prompt command show the configured start section as part
of the default section table.
The start row of that table is labelled with its source so you can tell
where the prompt came from: built-in for the packaged base prompt, -S
for a --system-prompt override, (config) <file> when
system-prompt-file is set, and (config) <config-file>:system-prompt
when the literal system-prompt key is used. Sections without a label
(tools, tools:<Toolname>, skills, agents.md, plugins:<name>) keep
showing their name.
The tools section collects the usage hints that tools declare through their
system_prompt_hint class attribute (see the tool guide, docs/TOOL.md),
limited to the tools the session may actually use. It carries only the
## Tool Usage Notes heading; each hint lives in its own tools:<Toolname>
section right after it. All of them are omitted when no available tool
declares a hint.
By default (neither key set) the start section is the built-in base prompt,
shipped with janito as janito/system-prompt.txt — installed as package data
and read from the resource location each time the default prompt is built, so
editing the installed file (or the source-tree copy) is picked up without a
code change.
The file is read at session start (each new session re-reads it), so editing
the file is picked up by the next session. The path is validated when the
value is set (janito --set system-prompt-file=... rejects a missing file
with exit code 1) and again at startup, so a session never starts with a
broken path; the error names the key and path. An empty file falls back to the
built-in base prompt (like an empty AGENTS.md).
Note:
system-prompt-fileis resolved from the merged config, so a checked-in./.janito/config.jsoncan point the start section at a repository file. This mirrors the existing trust model that auto-loads a cwdAGENTS.md— only use local configs you trust.
At call time, when no model-scoped value is configured, janito falls back to
the provider/model's built-in limit (e.g. OpenAI's gpt-6-luna:
1,050,000 in / 128,000 out); the generic fallback used when even the model
has none is 128000 input / 100000 output.
Provider base URLs are built in for known providers, so you normally only need
endpointfor thecustomprovider. At runtime the endpoint is used directly as the API base URL. The model-level keys (max-input-tokens,max-output-tokens,effort,api-type,stateless-mode,disabled-tools) are stored per provider and model, underproviders.<provider>.models.<model>.<key>inconfig.json.
Disabled tools (disabled-tools)¶
janito --provider alibaba --set disabled-tools=WebSearch
janito --provider alibaba --set disabled-tools='["WebSearch"]'
janito --provider alibaba --unset disabled-tools
Models with native server-side search (Alibaba/Qwen, Meta Muse Spark) hide
the external WebSearch (Brave API) function tool by default so the model
uses its built-in search. Set disabled-tools to override per model (an
empty value re-enables every tool); the session tool list and the web
tool router both honor it.
Used files report (used-files)¶
By default janito does not print the end-of-turn Used files report (the
list of files the tools read/wrote during the prompt). Set the flat
used-files key to True to enable it:
When enabled, the report is printed right before the token-usage summary at
the end of every turn (interactive shell, one-shot prompts, /ask). The
/compact compression call is the exception: it runs with the silent turn
observer, so it records the accounting row without rendering the used-files
report or the usage summary. The tracking itself always runs — the flag only
controls whether the report is displayed.
Configuration Priority¶
Configuration is resolved from local files — janito does not read any
OPENAI_* environment variables. Values are resolved in this order (later
overrides earlier):
- Provider's built-in default (endpoint) / no default (model)
- Configuration file (
~/.janito/config.json; the project-local./.janito/config.jsonis always consulted first and its values override the global ones) - Command-line arguments (
--model,--provider,--set endpoint=...)
API keys are read from the per-provider key stored in ~/.janito/auth.json
(set with --set-api-key <key> --provider <name>). There is no environment
variable fallback. Keys in ./.janito/auth.json always take
precedence over ~/.janito/auth.json.
Note: When using CLI arguments,
--setand--set-api-keymust be run as separate commands. They cannot be combined in a single invocation.
Deleting an API key¶
If janito --login reports an existing OpenAI API key, run
janito --delete-api-key --provider openai, then re-run janito --login.
janito --delete-api-key --provider openai
janito --delete-api-key # Use the configured default provider
janito -l --delete-api-key --provider openai # Delete only the project-local key
--delete-api-key removes the provider's key without prompting from the selected
auth.json: the global config directory by default, the directory selected by
--config-dir, or ./.janito with --local. Other providers, the configured
default provider, and OAuth credentials are unchanged. Use --logout to remove
OAuth credentials. Setting and deleting an API key cannot be combined.
The command exits with an error if no provider can be resolved, no key exists in
the selected file, or deletion fails. Deleting a local key may expose a global
fallback key; it does not remove that global key. Run without --local to
remove the global key separately.
Note: If OAuth details are stored for OpenAI,
--set-api-keyis refused without prompting or changing credentials. Runjanito --logout --provider openaifirst to switch to API-key authentication. Stored OpenAI OAuth details do not prevent setting keys for other providers.Note: If an API key is already stored for a provider,
--set-api-keywarns you and asks for confirmation before overwriting it.Note:
--set-api-keytargets the provider given with--provider. When--provideris omitted, the configured default provider is used (theprovidervalue fromconfig.json); if none is configured, janito exits with an error.
Next Steps¶
- Configure providers for different AI services
- Manage secrets securely