Aller au contenu principal

Agent configuration

The native host reads config.toml from its selected state directory. The file holds user defaults for that host. Each accepted input retains the defaults that applied when it was accepted.

Surfaceconfig.tomlChanges by the agentManaged operations
Grida Desktop on macOS and LinuxOne per workspace, in a digest-named folder under chats/workspaces/ in Desktop's application data folderFile edits; every write asks for your approvalNot offered
Source-built grida-agent runIn the --state-dir you choose; read at startupFile edits under a write-capable permission profile; every write asksNot offered
Source-built grida-agent serve with an ACP clientIn the --state-dir you chooseAs for runAvailable after negotiation

In Desktop, ask the agent to change a setting, or edit the file while Desktop is closed. Desktop has no settings control. Change agent settings

For an ACP client, start the host with your own state directory, for example grida-agent serve --stdio --state-dir /absolute/path/to/agent-state plus your provider options, edit /absolute/path/to/agent-state/config.toml, and call _co.grida/config/reload.

Supported file​

schema_version = 1

[context]
max_input_tokens = 64000
FieldMeaningAccepted values
schema_versionConfiguration-file format1
context.max_input_tokensHard upper limit for complete model inputAn integer from 1 through 9007199254740991, or omitted for automatic budgeting

The input limit covers instructions, conversation history, media representation, tool declarations, and provider framing. The provider must establish an exact count or conservative bound for its complete prepared request. Unsupported counting or an excessive request produces a recorded failure before generation. Remote counting sends the prepared input to the selected provider under the same authority and deadline as generation. An estimate cannot certify this hard limit.

The native host can count requests on Responses connections and on a supported local llama.cpp text connection explicitly launched with --llama-cpp-input-count. The llama.cpp option requires a direct numeric loopback /v1 endpoint. It does not discover or change the model's capacity.

The limit remains subject to actual model capacity and host constraints. A larger value does not enlarge the model's context window. Remove max_input_tokens to restore automatic budgeting. Zero is invalid.

An absent file selects the host's defaults. An existing file requires its schema version. Unknown fields, unsupported versions, and invalid values are rejected.

Configure local request counting​

In Grida Desktop on macOS and Linux, quit Desktop and set "input_counting": "llama.cpp" on the saved endpoint in Desktop's endpoint file, ~/.grida/agent/endpoints.json. This private file holds an array of endpoint entries. An entry can look like this.

{
"id": "llama",
"base_url": "http://127.0.0.1:8080/v1",
"models": [{ "id": "local-model" }],
"input_counting": "llama.cpp"
}

Set the workspace's input limit in its config.toml as above. Start Desktop, approve the saved endpoint address, and choose its llama.cpp counting connection for a new chat. Use a numeric loopback address and the /v1 base path on a server that supports POST /v1/chat/completions/input_tokens. Desktop uses that route only when the counted chat has an input limit. It sends the same prepared text and tools that the generation request would use. A failed count or a request over the limit ends before generation. llama.cpp token counting API

The ordinary endpoint choice keeps working as before. Removing the declaration makes chats saved on the counting connection unavailable until it is restored. For a headless host, launch with --llama-cpp-input-count instead.

Scope and activation​

Changes apply to later accepted inputs. Running and already accepted work retains its captured settings.

An edit by the agent takes effect for inputs accepted after it is saved. A manual edit takes effect at host startup or after an explicit configuration reload. An invalid startup file prevents execution and reports its diagnostic. A rejected reload retains the last valid active defaults and reports the file diagnostic.

Inspection distinguishes the current file revision from the active settings snapshot. They can differ after a manual edit awaiting reload or a rejected reload.

Changes made by the agent​

The agent reads and edits config.toml with its ordinary file tools, as the directory agent-settings; that directory holds only this file. A read runs without asking and reports whether the content is active, waiting for the next start, or invalid. Every write_file or edit_file on it is an approval request for that exact change, answered like any other file approval. It is asked even where the agent may write the project without asking, an earlier approval does not cover the next change, Plan offers no writes, and automatic review never answers it. Commands the agent runs can neither read nor write the file.

The host validates the complete result before saving it. Invalid content is refused with its diagnostic and leaves the file and the active settings unchanged. A saved change applies to inputs accepted afterwards.

Managed changes​

Capable ACP clients use typed host operations for inspection, set/reset, and reload. These are client operations for a person's own tooling; they require the corresponding negotiated ACP capability and are not offered to the agent. Connect an agent client.

MethodBehavior
_co.grida/config/inspectReturns the field description, file revision, diagnostics, and active snapshot
_co.grida/config/updateApplies one typed set or reset change using the expected file revision
_co.grida/config/reloadValidates and activates the file at the expected revision

Managed updates serialize writes, validate the complete result, preserve unrelated comments, and atomically replace the file. A stale revision is rejected so a client can inspect the newer state before trying again. If a reply is lost, inspection reveals the current revision and values.

When editing manually, stop the host or reload deliberately after the edit. External editors operate independently of the managed writer lock.