Settings and secrets

Two places, and which one a value goes in is the only question:

What	Where
A choice about how chloe behaves, an address, a path, a name	settings in chloe.config.ts, in source control
A password, key or token	.env beside it, mode 600, never committed

import { defineConfig } from "@chloejs/core";

import shop from "./agents/shop/agent.ts";

export default defineConfig({
  agents: [shop],
  settings: {
    model: { defaultModel: "anthropic/claude-sonnet-5", key: process.env.CHLOE_MODEL_KEY },
    connections: { resend: { api_key: process.env.CHLOE_CONNECTIONS_RESEND_API_KEY } },
    agents: { shop: { telegram: process.env.CHLOE_AGENTS_SHOP_TELEGRAM } },
  },
});

CHLOE_MODEL_KEY=...
CHLOE_CONNECTIONS_RESEND_API_KEY=re_...
CHLOE_AGENTS_SHOP_TELEGRAM=123456:ABC...

chloe reads nothing from the environment by itself. A secret reaches it only where the config names it, as process.env. and its name, so reading the config shows every key there is. A setting the config leaves out is its default, and so is one handed a variable nothing set. Any other value can be kept out of the file the same way.

The secrets are model.key, model.keys, connections.resend.api_key, connections.brave.api_key, connections.google.client, and everything under agents. Their names in .env are CHLOE_ and the path in capitals, and a message saying a key is missing gives both the name and the config line.

Every setting

Section	What it controls	More
model	Which model an agent asks, how a call reaches it, the keys.	Models
email.provider	What carries mail a job sends with deliverEmail(): "resend" (the default), "gmail", or "none" to log it and send nothing.	Connections
connections.google	The Google account and the app it signs in with.	Connections
connections.resend	The Resend key, and chloe's alert mail.	Connections
connections.brave	The Brave Search key web.search uses. Without one it searches DuckDuckGo.	Connections
agents.<id>	Each agent's channel tokens, under the id in its agent.ts.	Channels
serve	Where the port listens: 127.0.0.1:3067. Change takes a restart. serve.url is the address the dashboard is opened at from elsewhere, so an agent can link to a file in its memory. serve.ownerKey is the key a copy in a machine takes as its owner, from the copy that made it, and serve.stopAfter the idle minutes before a copy stops itself.	The site, Machines
machine	Whether this chloe runs in a machine of its own, the shell user, the workspace, the hosts the shell may reach, the base image, and the keys every machine this copy makes is given.	Machines
owner	Who a run the clock started belongs to, as channel:who.	Asking a person
node	Which node npx chloe install runs. Empty is whichever is on the path.

Every setting with its default is in the settings reference, and your editor shows each one's explanation as you type it.

The dashboard's Configuration page (/configuration) changes them as forms, in the order the config says them: the model settings and keys, which service sends mail, the connections (Resend and its alerts, Google, Brave Search), the address the dashboard is reached at (serve.url), and the owner. Where the server listens, serve.host and serve.port, is changed in the file only, because a wrong one loses the page. A form changes the one value in chloe.config.ts and leaves the rest of the file, comments included, as it was. A key goes into .env, under the name the config already reads it from, or the suggested one, and the config names it as process.env.<name>. A value the file says as code (a variable, a spread, a call) is shown and not changed: the file is where to change it.

Below the forms, the Keys box takes any CHLOE_SOMETHING=value line and replaces that name's line in .env. It lists the names .env sets and never shows a value. Only CHLOE_ names are written, less CHLOE_STATE, CHLOE_MEMORY and CHLOE_DB, and an agent sends its owner there, at /configuration?key=<name>, rather than ask for a key in a chat. Each name the config does not hand over as process.env.<name> says so. Last is chloe.config.ts itself, as text.

Every save, from a form or the text, is loaded as the next reload would load it, and type checked when the project has TypeScript, and when either fails the old file stays (and .env with it) and the page shows why.

An edit to the config or .env is live without a restart, except serve.host and serve.port. Renaming an agent means renaming its entry under agents; until then chloe says which entry names no agent.

Where things are kept

Not a setting, because it is read before the config: CHLOE_STATE (the state folder, data/ beside the config), CHLOE_MEMORY (the agents' memories, data/memory) and CHLOE_DB (the run history), from the environment or .env. A change takes a restart. See The site.