Chloe

Docs

Connections

Signing in to Google, sending mail through Resend, searching through Brave, which address each kind of mail comes from, a service's MCP server, and an account chloe does not ship.


A connection is an outside account that tools work through. A tool says which one it needs, so an agent that names gmailReadEmail gets the Google sign-in with it. The agent's Connections page in the dashboard, and the lines printed when chloe starts, say what each connection is still missing.

Connection For What you set
Google Gmail, Calendar and Drive tools, and the email channel on Gmail a Google app of your own, the account, and one sign-in
Resend sending mail from your own domain, and chloe's alerts an API key
Brave Search web.search, which uses DuckDuckGo without it an API key, if you want one
An MCP server a service's own tools, like GitHub's its address and key, on one agent

Google

One sign-in covers Gmail, Calendar and Drive. Reading Gmail is in Google's strictest tier, so every copy of chloe signs in with a Google app of its own. You make it once, in about ten minutes:

  1. At console.cloud.google.com, make a project. Under APIs and Services, then Library, switch on the Gmail API, the Google Calendar API and the Google Drive API.
  2. In the Google Auth Platform section, give the app a name and your own email as the contact, and choose External.
  3. Under Audience, press Publish app so it is In production. Left in Testing, Google ends the sign-in every 7 days. Google warns once, when you approve, that it has not checked the app: it is yours, so go past it.
  4. Under Clients, create an OAuth client of the Web application type, and add these redirect addresses exactly as written:
    • https://chloejs.org/connected, the page that shows you a code to send back;
    • http://127.0.0.1:33067/oauth2/callback, the fallback.
  5. Download the client file. Put its path, or its contents, in .env as CHLOE_CONNECTIONS_GOOGLE_CLIENT, and name the account in the config:
settings: {
  connections: {
    google: { account: "you@gmail.com", client: process.env.CHLOE_CONNECTIONS_GOOGLE_CLIENT },
  },
}

Then sign in, from either place:

  • A chat. Ask the agent for your mail. chloe sees nobody has signed in and sends a link. Approve it, and send back the short code the page you land on shows. chloe finishes the sign-in and answers what you asked.
  • The dashboard. Configuration, or any agent's Connections page, walks through the steps above with a link to each page in Google's console, copy buttons for the two addresses, a box for the client file (it goes into .env) and one for the account (it goes into chloe.config.ts). Then Sign in opens Google's page in a new tab, and you paste the code it ends on.

The model never sees the link or the code. The sign-in is saved as one file in the state folder, mode 600.

Each person signs in to their own. The sign-in above is yours, for connections.google.account. Somebody you invited, or anybody else an agent answers, who asks for their mail gets a link of their own, approves with whichever Google account is theirs, and from then on their turns read that. Nobody else is ever lent yours. What the agent sends as itself (the email channel's mailbox, email.provider on Gmail, a tool that writes only to the addresses you gave it) always goes from yours.

Setting Default What it controls
connections.google.account none The account that signs in. The mail tools read it, and the email channel on Gmail sends from it.
connections.google.client none The client file from step 5: its path or its contents. A secret, so it comes from .env.
connections.google.callback https://chloejs.org/connected Where Google sends you after you approve.

What the sign-in may do. Read and send mail, never delete it. Read calendar events and add them. Read files. If you untick one on Google's page, chloe says what it cannot reach.

The Google tools

Each one is bound in agent.ts. The binding is what it may see, and the model chooses only how far back, how many, or what to look for.

import * as calendar from "@chloejs/core/tools/calendar";
import * as drive from "@chloejs/core/tools/drive";
import * as gmail from "@chloejs/core/tools/gmail";

const PLANS = "'1AbC...' in parents"; // one Drive folder, by its id

tools: {
  gmailReadEmail: gmail.readEmail({ search: "in:inbox label:orders", what: "the order mail" }),
  gmailReplyEmail: gmail.replyEmail({ search: "in:inbox label:orders", what: "the order mail" }),
  calendarListEvents: calendar.listEvents({ calendars: ["primary"] }),
  calendarAddEvent: calendar.addEvent({ calendar: "primary" }),
  driveSearchFiles: drive.searchFiles({ search: PLANS, what: "the plans folder" }),
  driveReadFile: drive.readFile({ search: PLANS, what: "the plans folder" }),
}
Tool Bound to Default The model may
gmail.readEmail search, a Gmail query in:inbox, the whole inbox List that mail, 7 days back unless it asks for more, and read one message it listed.
gmail.replyEmail the same search Answer a message it listed, to whoever sent it, in the same thread. It never picks the address.
gmail.sendEmail from, to, when Write the subject and body. See sending an email.
calendar.listEvents calendars, by id ["primary"] List the events from a day it picks, up to 90 days ahead.
calendar.addEvent calendar "primary" Add one event. It invites nobody.
drive.searchFiles search, a Drive query every file the account can open Find files in it, by words or newest first.
drive.readFile the same search Read a file the search listed, as text: a Doc, Sheet, Slides or text file.
drive.downloadFile the same search, and agent Download a file as it is (a PDF, a picture) into the agent's received files, for a script. With a search, only a file it listed; without one, any Drive link.

The read tools take what too: that mail, calendar or folder in plain words, for the model. A job does the same work without a model through @chloejs/core/services: readEmailMessages, sendGmail, listCalendarEvents, addCalendarEvent, searchDriveFiles, readDriveFile and downloadDriveFile.

Resend

Resend sends mail from an address on a domain you own and have verified with Resend. Put the key in .env as CHLOE_CONNECTIONS_RESEND_API_KEY, and in the config as connections: { resend: { api_key: process.env.CHLOE_CONNECTIONS_RESEND_API_KEY } }. Then bind resend.sendEmail() from @chloejs/core/tools/resend.

Setting Default What it controls
connections.resend.api_key none The key. Without one, nothing is sent.
connections.resend.alerts on Mail you when somebody signs in from an address this copy has not seen, when one is locked out for guessing, and when a job starts failing or works again.
connections.resend.email_to none Where alerts go, one address or several split by commas.
connections.resend.email_from none The alerts' From line, like "Chloe <info@example.com>".

web.search() sends what the model searches for to Brave Search when there is a key, and to DuckDuckGo's results page when there is not. DuckDuckGo needs nothing set up, but it is a page for people rather than a service for programs, and it can stop answering a machine that searches often: the tool then says so rather than finding nothing. For an agent that searches every day, get a key at brave.com/search/api, put it in .env as CHLOE_CONNECTIONS_BRAVE_API_KEY, and in the config as connections: { brave: { api_key: process.env.CHLOE_CONNECTIONS_BRAVE_API_KEY } }.

Setting Default What it controls
connections.brave.api_key none The key. Without one, searches go to DuckDuckGo.

A job searches without a model with searchWeb() from @chloejs/core/services.

Which address mail comes from

What sends it From Where that is set
The email channel on Gmail the agent's label and connections.google.account settings
The email channel on a mailbox of your own whatever its send does your Mailbox
gmail.replyEmail the signed-in Google account settings
gmail.sendEmail its from: the signed-in account or an alias Google verified agent.ts
resend.sendEmail its from, on a domain verified with Resend agent.ts
deliverEmail() in a job the from the job gives it, carried by email.provider: "resend", "gmail", or "none" to log it and send nothing the job, and settings
chloe's own alerts connections.resend.email_from, always through Resend settings

MCP servers

Many services publish tools for models as an MCP server, reached over HTTP. List one in an agent's connections, and only that agent gets its tools.

import { mcpConnection } from "@chloejs/core/connections";

connections: [
  mcpConnection({
    name: "github",
    url: "https://api.githubcopilot.com/mcp/",
    token: process.env.GITHUB_TOKEN,
    tools: ["list_issues", "get_issue"],
  }),
],
Option Default What it controls
name required The first word of every tool it brings: github and list_issues make githubListIssues.
url required The server's address, from the service's docs.
token none Sent as a bearer key. A function works too, to fetch one when it is needed.
headers none For a server that wants something other than a bearer key.
tools all of them Only these, by the server's own names.
does none One line for the Connections page.

The tools are fetched as the agent loads. A server that does not answer leaves the agent loading without them, and the Connections page says why. A connection reaches whatever its key reaches, so keep mail, notes and files on chloe's own tools, which are bound to what one agent may see.

A connection of your own

An account chloe does not ship is a folder in the agent's own folder: its services, its tools, and a Connection. Nothing in the runtime changes.

/**
 * An outside account or service that a tool works through, such as Google.
 *
 * A tool names its connection in its `needs` field. chloe then asks the
 * connection what is missing, shows that on the dashboard, and runs its
 * sign-in when the tool throws `NeedsSignIn`.
 */
export interface Connection {
  /** The connection's name, as shown on the dashboard, such as `"google"`. `NeedsSignIn` uses the same name. Required. */
  name: string;
  /** What the connection is for, in one line, shown on the dashboard. Required. */
  does: string;
  /**
   * The settings it reads, as paths such as `"connections.resend.api_key"`.
   * Shown on the dashboard. Never put the values here. Required (can be empty).
   */
  settings: string[];
  /** How a person signs in from a chat. Leave it out if they cannot sign in from a chat. */
  signIn?: SignIn;
  /**
   * Returns what is still missing before the connection works, one short
   * line each. Returns an empty list when it is ready. Shown on the dashboard
   * and printed when chloe starts.
   */
  missing(): Promise<string[]>;
}

missing() is what the Connections page and the startup lines show, and an empty list means ready. A connection on a plain key has no signIn. One that has it gives start() for the words and the link, answers() to recognise the reply, and finish(). The words are for a chat: the page opens the link in a new tab and says its own, asking for the code the last page shows, or, when start() also gives code (a sign-in where the person types a code on the page, like Microsoft's), showing that code and a Done button. Its service throws NeedsSignIn when signing in would fix what failed. A tool that works through it says so with needs: Object.assign(tool({ ... }), { needs: crm }). Connection, SignIn and NeedsSignIn are exported from @chloejs/core.

A sign-in is the person asking's. Keep each in signInFolder("crm"), which is the owner's folder in the state folder for the owner and one of their own for anybody else, and read it through that every time, never once as the file loads. personAsking() says who it is for (undefined is the owner), and asOwner(() => ...) runs what belongs to the agent rather than the person as the owner. All three are exported from @chloejs/core.