Connections and assignments

A connection is a declared requirement for a provider’s tools. An assignment selects the connected account that satisfies it. Your code uses the connection’s name, while ContextLayer resolves the account and credentials. For example, declare a Gmail connection named work-email, then assign a connected Gmail account to it. The code keeps calling work-email if you later select a different account. The declaration describes the requirement; the assignment supplies the account.

Declare a connection

Declare a connection under connections in the consuming app or agent’s slate.json:

public/slate.json

{
  "connections": {
    "work-email": {
      "toolkit": "gmail",
      "mode": "viewer"
    }
  }
}

Part	In this example	Meaning
Slug	`work-email`	The name used in tool calls. It belongs to the slate-wide connection namespace.
Toolkit	`gmail`	The Composio integration whose tools are available. The assigned account must belong to this toolkit.
Mode	`viewer`	The rule for selecting the account’s Owner in hosted execution. `viewer` selects the acting person’s account; `owner` selects the slate Owner’s account.

An app uses public/slate.json; an agent uses agents/<name>/slate.json. Each must declare the connection it uses. See resource modes for the ownership rules. The slug names the role the connection plays, while the toolkit names the provider. A slate can have both work-email and support-email connections using the gmail toolkit, with a different account assigned to each.

Assignments

An assignment stores an account ID for a connection slug; Composio keeps the credentials. Connecting an account makes it available to its Owner. Assigning it selects it for a particular connection. The same account can satisfy connections in several slates.

Hosted assignments

A hosted slate keeps its assignments in ContextLayer, one per slate, Owner, and connection slug. An owner-mode connection has one assignment, to an account of the slate’s Owner. A viewer-mode connection has one assignment per viewer, to that viewer’s own account. Push the declaration to main before configuring hosted assignments. Configure hosted assignments in the chrome, ContextLayer’s header and configuration tray in the hosted app. It lists the slate’s declared connections and lets you connect and assign accounts.

Connection mode	Who configures the assignment	Which accounts can be selected
`owner`	The slate’s owning user or members of its owning organization.	Accounts belonging to the slate’s Owner.
`viewer`	Each authorized viewer, for themselves.	That viewer’s personal accounts.

The CLI’s connections command also lists and assigns hosted connections for a slate named by SlateID or hostname. The API reference has List declared connections and their account assignments and Assign an account to a declared connection. These operations read declarations from the latest commit on main.

Local assignments

In a checkout, the CLI’s connections command reads declarations from your local files and saves assignments in the Git-ignored .contextlayer/connections.json. Local assignments always use your personal accounts, including for owner-mode connections and organization-owned slates. They do not read or change hosted assignments. For example, an assignment saved by the CLI looks like this:

.contextlayer/connections.json

{
  "work-email": "ca_example"
}

ca_example stands for the real account ID selected through the CLI. Restart pnpm dev after changing an assignment so local startup reads the new selection. Pushing the slate does not publish this file; configure the hosted assignment separately. Run npx @usecontextlayer/cli connections --help for its targets and arguments, and see Connect an account for the full steps.

Call tools by slug

Once the connection has an assignment, an app loader or action can obtain Tools from React Router context and call a provider tool. This loader excerpt uses the declaration above:

app/routes/home.tsx

import { toolsContext } from "@usecontextlayer/sdk"
import type { Route } from "./+types/home"

export async function loader({ context }: Route.LoaderArgs) {
  const tools = context.get(toolsContext)
  return tools.call("work-email", "GMAIL_FETCH_EMAILS", { max_results: 5 })
}

In this call, work-email selects the connection, GMAIL_FETCH_EMAILS selects the provider action, and { max_results: 5 } supplies that action’s arguments. ContextLayer looks up the slug in the app’s declaration, selects the resource Owner from the mode, finds that Owner’s assignment, and runs the tool through Composio. Composio defines each tool’s arguments and results. The call resolves to { data, logId }: the provider-specific result and the execution log ID. The excerpt demonstrates the call; in your app, parse data into the shape you use before rendering or processing it. If the connection has no assignment yet, the call throws an HTTP 409 connection-required response naming the slug. The starter’s root error boundary turns that response into setup guidance so the viewer can configure the connection.

Getting started

Core concepts

How-to

Reference

Connections and assignments

Declare a connection

Assignments

Hosted assignments

Local assignments

Call tools by slug

​Declare a connection

​Assignments

​Hosted assignments

​Local assignments

​Call tools by slug

Declare a connection

Assignments

Hosted assignments

Local assignments

Call tools by slug