Skip to main content

Configuration

The Runtime reads its settings once, when it starts. After a change, restart it: wisp stop and wisp serve, or restart the service. This page explains how settings work and walks through common changes. Every key, with its default, is in the Reference.

The file​

Settings live in $WISP_HOME/runtime.json, ~/.wisp/runtime.json by default. It is one JSON object:

{ "agentToken": "…", "port": 3008 }

The installer writes it with a fresh agentToken only, readable by you alone. Everything else takes its default until you add it.

wisp serve refuses to start, with exit code 78, when the file:

  • is not valid JSON, or not a JSON object;
  • has a key the Runtime does not know, so a typo never falls back to the default silently;
  • belongs to another user;
  • holds a secret, such as agentToken, and others can read it. Fix it with chmod 600 ~/.wisp/runtime.json.

wisp doctor names the problem and the command that fixes it. See Troubleshooting.

wisp serve --config <path> reads another file instead. wisp serve --home <dir> keeps the data in <dir> and reads <dir>/runtime.json, as WISP_HOME=<dir> does; set WISP_HOME for the other wisp commands too, so they find that Runtime. wispHome (the data directory) can be set in a file only through --config, never in a runtime.json found through WISP_HOME.

The environment​

Each key has an environment variable, listed next to it in the Reference: PORT for port, TEE_LLM_MODEL for teeLlmModel, and so on. The order is:

  1. the environment variable, when it is set;
  2. else the key in runtime.json;
  3. else the default.

The installed wisp reads no .env file. Only a Runtime run from source reads one.

Lists, such as ALLOWED_HOSTS and CONFIRMATION_MODES, are comma-separated in the environment and JSON arrays in the file.

Common changes​

Open the Runtime to another machine​

The Runtime listens on 127.0.0.1. To reach it from elsewhere, put a reverse proxy with TLS in front of it and list the name callers use in allowedHosts:

{ "agentToken": "…", "allowedHosts": ["wisp.example.com"] }

Never send the token over a network in clear. Remote access has the whole setup, a token per device, and the encryption key a Linux server needs.

To use the Runtime from Wisp Desktop on another machine, you need none of this: the app reaches it over SSH and the Runtime stays on loopback. See Connect to a server.

Stop callers from asking for approvals​

By default a /v1 Run may wait for a person's approval: the Telegram bot, the Slack app and wisp run --interactive need that. To refuse every such Run instead, leave interactive out:

{ "agentToken": "…", "confirmationModes": ["policy"] }

policy is always allowed, whether listed or not. A Run that asks for a mode left out is refused with 403, and the bot and the app then take no chat messages. See approvals.

Change the default model​

The Runtime Default is the model every chat, scheduled job and Run uses when it has not chosen its own. It takes effect at once, with no restart:

wisp models # the model ids you can name
wisp model set balanced # or advanced, or a model id; --thinking for its thinking form
wisp model # what is set now
wisp model reset # back to teeLlmModel

With no Runtime Default set, teeLlmModel applies. Its default, tier:thinking:balanced, is Balanced with thinking on; changing it needs a restart. Session titles and Recording summaries always use teeLlmModel.

A Session can still choose its own with /model in a chat, and a single Run with wisp run --model. See Choosing a model.

Let the Runtime update itself​

A Runtime nobody watches can install each newer release by itself, when no Run is in flight:

{ "agentToken": "…", "autoUpdate": true }

It is off by default, so that a release never restarts your Runtime without your say. See Update automatically.

Change the port​

{ "agentToken": "…", "port": 3010 }

wisp on the same machine finds the new port by itself, through ~/.wisp/runtime.lock. Another machine needs the new address.

Variables outside runtime.json​

A few settings belong to other processes, or are read only from the environment.

variableread bywhat it does
TELEGRAM_ALLOWED_IDSwisp telegramusers and chats let in without pairing, comma-separated — see Letting people in
SLACK_ALLOWED_IDSwisp slackusers and channels let in without pairing, comma-separated — see Letting people in
TELEGRAM_BOT_TOKENwisp telegramthe bot's token, instead of the one wisp telegram setup stored
SLACK_BOT_TOKEN, SLACK_APP_TOKENwisp slackthe app's two tokens, instead of the ones wisp slack setup stored
TELEGRAM_API_URLwisp telegramthe Bot API's address instead of https://api.telegram.org, for a Bot API server of your own
SLACK_API_URLwisp slackthe Web API's address instead of https://slack.com/api
WISP_URL, WISP_TOKENevery wisp commandthe Runtime to reach and its token — see Reaching a Runtime
WISP_MASTER_KEY_FILEwisp servethe file holding the root key, on a server — see the encryption key

TELEGRAM_API_URL and SLACK_API_URL must be https, or plain http to a loopback address: the bot's tokens travel in every call. An id in an allow list that is not a valid id stops the bot or the app before it starts.

WISP_KEY_BACKEND=file is for tests: it stores the Runtime's keys unencrypted beside the data they protect. On a server, use WISP_MASTER_KEY_FILE instead.