Installation

Install the SDK

npm

npm install configure

yarn

yarn add configure

pnpm

pnpm add configure

Stable install

Install configure and run npx configure setup.

API keys

CLI setup

The fastest way to get an API key:

npx configure setup

This opens a browser session where you sign in with Google or GitHub, choose or create the agent for this project, and receive a secret key plus a publishable key. The CLI writes .env values for CONFIGURE_API_KEY, CONFIGURE_PUBLISHABLE_KEY, and CONFIGURE_AGENT. (npx configure init also works as an alias.)

Agent-driven setup

If a coding agent is integrating Configure for you, point it to configure.dev/skill.md and tell it to install configure. If keys are missing, the agent should run npx configure setup after install and only fall back to configure.dev/login if the CLI cannot run interactively.

After install, the canonical starter lives at node_modules/configure/template/. Coding agents should start from that packaged template instead of inventing a new shell by default.

Manual setup

Use this only when npx configure setup cannot run interactively.

1. Sign in at configure.dev/login
2. Create an agent and copy your secret key plus publishable key
3. Add to your environment:

export CONFIGURE_API_KEY=sk_...
export CONFIGURE_PUBLISHABLE_KEY=pk_...
export CONFIGURE_AGENT=your-agent-name

Key types

Type	Prefix	Use case	What it can do
Secret	sk_	Server-side SDK, backend	Full API access — reads, writes, ingest, tool searches, agent CFS
Publishable	pk_	Client-side components, browser JS	Hosted auth, approved federated profile reads, tool OAuth connections

Both key types work with ConfigureClient. The server enforces access — pk_ keys that call server-only endpoints get a clear 403.

Legacy keys prefixed with cfg_ continue to work with full access.

WARNING

Never expose sk_ keys in client-side code. Use publishable keys (pk_) for browser environments.

Initialize the client

import { ConfigureClient } from 'configure';

// Pass the key directly
const client = new ConfigureClient('sk_...');

// Or read from CONFIGURE_API_KEY environment variable
const client = new ConfigureClient();

If your API key has multiple agents (e.g., a monorepo with several agents), set CONFIGURE_AGENT in your environment so the SDK knows which agent is making requests:

export CONFIGURE_AGENT=your-agent-name

Or pass it directly:

const client = new ConfigureClient({ agent: 'your-agent-name' });

With a single agent, this is optional — the SDK auto-resolves it.

Authenticating users

Configure identifies users by phone number. The same phone always resolves to the same userId, regardless of which agent authenticates them. This is how profiles persist across agents.

Use the hosted auth surface on your frontend — it handles phone OTP inside a secure Configure-owned iframe:

<div id="configure-auth"></div>
<script src="https://configure.dev/js/configure.js"></script>
<script>
  Configure.auth({
    el: "#configure-auth",
    publishableKey: "pk_...",
    agent: "your-agent",
    theme: "light"
  });

  document.addEventListener("configure:authenticated", (e) => {
    const { token, userId } = e.detail;
    // token is agent-scoped — pass it to your backend
  });
</script>

Configure.auth() mounts a hosted iframe that handles phone input, OTP verification, and profile approval. On success it fires configure:authenticated with an agent-scoped token and userId.

The userId is a stable identifier — the same phone number always returns the same user ID across all agents. For federated profile and tool operations, send both values to your backend and store them securely in your application.

Server-side users

If you already have a stable user identifier, you can read and update profiles without putting Configure auth or components in the hot path. Pass your ID as userId in a server-side SDK client or as the X-User-Id HTTP header with sk_.... Configure creates an unlinked profile scoped to your developer account.

const client = new ConfigureClient({
  apiKey: process.env.CONFIGURE_API_KEY,
  agent: process.env.CONFIGURE_AGENT,
  userId: 'your-internal-user-id',
});

const profile = await client.profile.get();
await client.profile.remember(undefined, undefined, 'Prefers concise answers');

Unlinked profiles support profile reads, writes, memories, and ingest. They cannot be read by other developers' agents, and connected tools require the user to link later with phone auth.

See the Server-Side Users guide for details and limitations.

Direct HTTP API (no SDK)

If you're calling Configure from a language without an official SDK — Go, Rust, Elixir, edge runtimes, or shell — you can hit the same endpoints directly with X-API-Key plus either a federated Bearer token or server-side X-User-Id for an unlinked profile. See the API Reference.

Link later

When you are ready for a user-owned federated identity, call Configure.auth({ externalId: 'your-internal-user-id' }). Phone verification merges the unlinked profile into the federated profile, unlocks connected tools, and lets the user approve other agents.

Next steps

Quick Start — Add Configure to your existing agent with hosted auth, profile.get(), CONFIGURE_TOOLS, and optional hosted UI tools. You control the LLM, the prompt, and the model provider.