Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/GuaiZai233/FrostAgent/llms.txt

Use this file to discover all available pages before exploring further.

SettingsService lets you read and update FrostAgent’s environment variables at runtime through the management UI or directly via ConnectRPC, without restarting the process for variables that do not require a restart. Changes are persisted atomically to the .env file on disk and, where applicable, applied immediately to the running process via os.Setenv. The service is accessible under /frostagent.v1.SettingsService/.

​
Service base path

http://<host>:8080/frostagent.v1.SettingsService/

​
ListEnvVars

Returns the current values of all known environment variables. Secret values are automatically masked — all but the last four characters are replaced with * before the value is returned. Request: ListEnvVarsRequest No fields. Send {}. Response: ListEnvVarsResponse
​
env_vars
repeated EnvVar
Array of all registered environment variables.
Example 
curl -X POST http://localhost:8080/frostagent.v1.SettingsService/ListEnvVars \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "env_vars": [
    { "key": "UPSTREAM_ENDPOINT", "value": "https://dashscope.aliyuncs.com/compatible-mode/v1", "is_secret": false },
    { "key": "UPSTREAM_API_KEY",  "value": "*************1234", "is_secret": true },
    { "key": "MODEL_NAME",        "value": "qwen-turbo", "is_secret": false },
    { "key": "SYSTEM_PROMPT",     "value": "You are a helpful assistant.", "is_secret": false }
  ]
}

​
UpdateEnvVar

Updates a single environment variable in the .env file and sets it in the running process immediately. If the key already exists in .env, its line is updated in place; otherwise a new line is appended. Request: UpdateEnvVarRequest
​
key
string
required
The environment variable name to update. Must not be empty.
​
value
string
required
The new value to set.
​
is_secret
bool
Whether the value should be treated as a secret. This field is informational; masking is determined by the server-side registry, not this flag.
Response: UpdateEnvVarResponse
​
success
bool
true if the update was written and applied successfully.
​
error
string
Non-empty if success is false, containing a human-readable error description.
Example 
curl -X POST http://localhost:8080/frostagent.v1.SettingsService/UpdateEnvVar \
  -H "Content-Type: application/json" \
  -d '{
    "key": "SYSTEM_PROMPT",
    "value": "You are a concise and helpful assistant.",
    "is_secret": false
  }'

{ "success": true, "error": "" }

​
DeleteEnvVar

Removes a key from the .env file atomically and unsets it from the running process. Request: DeleteEnvVarRequest
​
key
string
required
The environment variable name to remove. Must not be empty.
Response: DeleteEnvVarResponse
​
success
bool
true if the key was removed (or was already absent).
​
error
string
Non-empty on failure.
Example 
curl -X POST http://localhost:8080/frostagent.v1.SettingsService/DeleteEnvVar \
  -H "Content-Type: application/json" \
  -d '{ "key": "VISUAL_MODEL_NAME" }'

{ "success": true, "error": "" }

​
GetRawEnvFile

Returns the complete, raw contents of the .env file as a single string. Useful for displaying or downloading the full configuration. If the file does not exist, content is an empty string. Request: GetRawEnvFileRequest No fields. Send {}. Response: GetRawEnvFileResponse
​
content
string
The raw text of the .env file, including comments and blank lines, exactly as stored on disk.
Example 
curl -X POST http://localhost:8080/frostagent.v1.SettingsService/GetRawEnvFile \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "content": "UPSTREAM_ENDPOINT=https://dashscope.aliyuncs.com/compatible-mode/v1\nUPSTREAM_API_KEY=sk-your-key\nMODEL_NAME=qwen-turbo\n"
}

​
UpdateRawEnvFile

Overwrites the entire .env file atomically with the provided content. The write is first made to a .env.tmp file and then renamed into place, guaranteeing that no partial writes are visible to other readers. In-process environment variables are not automatically reloaded; restart-required settings only take effect after a restart. Request: UpdateRawEnvFileRequest
​
content
string
required
The complete new content of the .env file. Use \n as the line separator.
Response: UpdateRawEnvFileResponse
​
success
bool
true if the file was written successfully.
​
error
string
Non-empty on failure, e.g. a filesystem permission error.
Example 
curl -X POST http://localhost:8080/frostagent.v1.SettingsService/UpdateRawEnvFile \
  -H "Content-Type: application/json" \
  -d '{
    "content": "UPSTREAM_ENDPOINT=https://api.openai.com/v1\nUPSTREAM_API_KEY=sk-new-key\nMODEL_NAME=gpt-4o\n"
  }'

{ "success": true, "error": "" }

​
Managed environment variables

The following variables are registered in the server-side knownEnvVars registry and are surfaced by ListEnvVars. Variables marked restart required are written to .env by UpdateEnvVar but only take effect after the process is restarted.
VariableSecretRestart requiredDescription
UPSTREAM_ENDPOINTNoYesUpstream API endpoint URL (OpenAI-compatible)
UPSTREAM_API_KEYYesYesUpstream API authentication key
CODER_API_KEYYesYesCoder sub-agent API key
LISTEN_ADDRNoYesHTTP server listen address (default :8080)
WS_LISTEN_ADDRNoYesWebSocket server listen address (default 0.0.0.0:1234)
SYSTEM_PROMPTNoNoSystem prompt prepended to every conversation
MODEL_NAMENoYesPrimary LLM model name
VISUAL_MODEL_NAMENoYesVision model name (falls back to MODEL_NAME if empty)
MAX_CONTEXT_MESSAGESNoNoMaximum number of messages retained in context
MAX_CONTEXT_CHARSNoNoApproximate character limit for context before trimming
WS_ALLOWED_ORIGINSNoYesAllowed WebSocket Origin header values
ENABLE_AT_IN_GROUP_MSGNoNoWhether to prefix group replies with an @ mention
Variables marked restart required — including UPSTREAM_ENDPOINT, UPSTREAM_API_KEY, CODER_API_KEY, LISTEN_ADDR, WS_LISTEN_ADDR, MODEL_NAME, VISUAL_MODEL_NAME, and WS_ALLOWED_ORIGINS — are persisted to .env immediately, but the running engine reads them only at startup. Restart FrostAgent after changing any of these for the new values to take effect.

Build docs developers (and LLMs) love

Get started for freeTalk to us