A step-by-step guide to using Coconut as a backend with the TypeScript SDK.

SDK guideNode 20+

Coconut as your backend for shared agent context.

Install the SDK, point it at a Coconut deployment, then use pages, records, search, link health, and space agents as a simple context backend for your product or agent workflow.

Start with setupSDK examples
Quick install
npm install coconut-sdk

COCO_BASE_URL=http://localhost:8787
COCO_API_KEY=coco_...
COCO_SPACE=demo
COCO_TEMPLATE=deal-memo
COCO_PAGE=demo/deals/acme
Client
import { CocoClient } from "coconut-sdk";

const coco = new CocoClient({
  baseUrl: process.env.COCO_BASE_URL,
  apiKey: process.env.COCO_API_KEY,
  orgSlug: process.env.COCO_ORG_SLUG,
});

Setup

Configure the SDK once.

The SDK examples share the same environment variables. Run Write back first when the target space is empty; the other guides read or extend the seeded data.

Configure the backend

COCO_BASE_URLAPI origin
COCO_API_KEYBearer credential. Production keys look like coco_...
COCO_SPACESpace to read and write. Defaults to demo.
COCO_TEMPLATERecord type used by the deal examples. Defaults to deal-memo.
COCO_PAGEPage inspected by Blame. Defaults to demo/deals/acme.
ANTHROPIC_API_KEYOnly needed by Chat with a space.
COCO_ORG_SLUGOptional org context for multi-tenant deployments.

Run examples

pnpm install
pnpm example:write-back
pnpm example:pull
pnpm example:visualize
pnpm example:chat
pnpm example:blame
pnpm example:gardener

Start with Write back when the space is empty. The rest can run as focused reads, reports, chat tools, history checks, and link-graph maintenance.

coco.pages

Read and write markdown pages, versions, links, and metadata.

coco.records

Treat templates as typed records with schemas and queries.

coco.spaces

List spaces, inspect pages, export/import bundles, and link health.

coco.search

Run text and metadata queries across your context.

coco.agents

Run scheduled space agents when your backend owns the loop.

Guides

Example guides

Open a guide for the step-by-step flow and the SDK calls used by the matching example file.

Write back

pnpm example:write-back

Seed the demo backend with a record type and a few typed deal records.

Open guide

Pull records

pnpm example:pull

Read the space the way an agent would on first contact.

Open guide

Visualize

pnpm example:visualize

Turn typed records into a dashboard and a queryable markdown report.

Open guide

Chat with a space

pnpm example:chat

Ground a terminal chat loop in pages, search, and typed records.

Open guide

Blame

pnpm example:blame

Inspect who wrote each line and how metadata changed over time.

Open guide

Gardener

pnpm example:gardener

Tend the page graph by healing dangling links and writing a map of content.

Open guide
CLI

Use the CLI to inspect the same backend from your terminal.

The SDK examples are deployment-agnostic: they only need an API origin, a credential, and a space. The CLI gives you a quick way to authenticate, list spaces, inspect records, and check the same data your app reads.

echo "$COCO_API_KEY" | coco auth login --key --base-url "$COCO_BASE_URL"
coco spaces list --stats
coco records list demo deal-memo --filter stage=diligence --order-by conviction-score --desc
CLI repositorynpm package

Backend

Coconut stores pages, records, metadata, links, and space state.

Query

Your app reads by path, full-text search, or structured metadata.

History

Page versions and metadata history stay inspectable over time.

Agents

LLMs can call small SDK-backed tools and cite the pages they used.