Quickstart

This walkthrough takes you from zero to an agent answering questions over your files: sign in, create a key, push a file, and run it through the Vercel AI SDK.

Before you begin

Node.js 20+ and a package manager like npm, pnpm, or yarn.
A model provider key. The example uses Anthropic, so it reads ANTHROPIC_API_KEY. Swap in any AI SDK provider you prefer.
A few minutes. Everything below runs on the free plan, no card required.

Create an API key

In the console, open API Keys and click Create key. The key is shown once, so copy it now and export it for the script:

export GREPTICON_API_KEY=grp_sk_your_key_here
export ANTHROPIC_API_KEY=sk-ant-your_model_key_here

Install the SDK

npm install @grepticon/sdk ai @ai-sdk/anthropic

@grepticon/sdk is the client, ai is the Vercel AI SDK, and @ai-sdk/anthropic is the model provider. Swap in whichever you use.

Create a workspace

A workspace is one isolated filesystem. Create it in the console or from the SDK; the code below uses the SDK.

quickstart.ts

import { GrepticonClient } from '@grepticon/sdk';

const client = new GrepticonClient({
  apiKey: process.env.GREPTICON_API_KEY,
});

const workspace = 'handbook';
await client.workspaces.create(workspace);

Push files

Upload files through the SDK, or add them in the console:

quickstart.ts

await client.files.upload(
  workspace,
  'guides/onboarding.md',
  '# Onboarding\n\nNew hires finish account setup on day one.\n',
  { contentType: 'text/markdown' },
);

Wait for ingestion

SDK uploads ingest asynchronously, so wait before reading. waitForReady resolves once the file reaches ready or error; check the returned status for failures.

quickstart.ts

const [file] = await client.files.waitForReady(workspace, {
  paths: ['guides/onboarding.md'],
});
if (file?.status === 'error') {
  throw new Error(`Ingestion failed: ${file.errorDetail ?? 'unknown error'}`);
}

Open a read session on your workspace and hand the four read tools to generateText. client.session(ws) reads with the client's own credential, so on a trusted backend like this script you read straight through.

quickstart.ts

import { anthropic } from '@ai-sdk/anthropic';
import { createVfsTools } from '@grepticon/sdk/ai-sdk';
import { generateText, stepCountIs } from 'ai';

const { text } = await generateText({
  model: anthropic('claude-sonnet-5'),
  tools: createVfsTools(client.session(workspace)),
  stopWhen: stepCountIs(10),
  prompt: 'When do new hires finish account setup?',
});

console.log(text);

stopWhen is not optional here. The AI SDK stops after a single step by default, so the model calls a read tool and the run ends before it ever writes an answer: text comes back as an empty string. stepCountIs(10) gives it room to read and then answer. Raise the budget if your agent chains more reads.

Running the agent somewhere you can't put your grp_sk_ key (a browser, an edge worker, one agent per end user)? Mint a scoped grp_at_ token and read with a standalone GrepticonSession, which carries the token and nothing else:

import { GrepticonSession } from '@grepticon/sdk';

const { token } = await client.tokens.mint(workspace, { ttlSeconds: 600 });
const session = new GrepticonSession({ token, workspace });
const tools = createVfsTools(session);

See Authentication and Access control to scope a token's claims to the files an agent should see.

The complete script

Putting every step together:

quickstart.ts

import { anthropic } from '@ai-sdk/anthropic';
import { GrepticonClient } from '@grepticon/sdk';
import { createVfsTools } from '@grepticon/sdk/ai-sdk';
import { generateText, stepCountIs } from 'ai';

// Authenticate with your grp_sk_ management key.
const client = new GrepticonClient({
  apiKey: process.env.GREPTICON_API_KEY,
});

const workspace = 'handbook';

// Create a workspace (or make one in the console under Workspaces).
await client.workspaces.create(workspace);

// Push a file. Uploads ingest asynchronously and return status 'pending'.
await client.files.upload(
  workspace,
  'guides/onboarding.md',
  '# Onboarding\n\nNew hires finish account setup on day one.\n',
  { contentType: 'text/markdown' },
);

// Wait for ingestion before reading, then check each entry for an ingest failure.
const [file] = await client.files.waitForReady(workspace, {
  paths: ['guides/onboarding.md'],
});
if (file?.status === 'error') {
  throw new Error(`Ingestion failed: ${file.errorDetail ?? 'unknown error'}`);
}

// Open a read session on your credential and hand the four read tools
// (ls / find / cat / grep) to the agent. stopWhen lets the model keep going
// after a tool call; without it the run stops at one step and text is ''.
const { text } = await generateText({
  model: anthropic('claude-sonnet-5'),
  tools: createVfsTools(client.session(workspace)),
  stopWhen: stepCountIs(10),
  prompt: 'When do new hires finish account setup?',
});

console.log(text);

Run it and the agent will grep the workspace and answer from your file.

Free-plan limits

What the free plan allows:

Limit	Free plan
Workspaces	3
Account storage	500 MiB
Reads per credential	60 / minute
Reads per account	300 / minute

Read rate limits return 429 with a Retry-After header; the SDK retries those automatically. Upgrading to Pro lifts these caps. See Limits for the full breakdown, or Support if you have questions.

Next steps

Access control: narrow a token's reach with the claims × visibility model, so an agent only sees the files it should.
SDK reference: the full GrepticonClient surface and createVfsTools.
Concepts: workspaces, the virtual filesystem, and read sessions.

Quickstart

Before you begin

Create an API key

Install the SDK

Create a workspace

Push files

Wait for ingestion

Run your agent

The complete script

Free-plan limits

Next steps

On this page