Concepts

Grepticon is a hosted, read-only filesystem for AI agents. You push files into isolated workspaces, and your agents retrieve from them with four familiar tools — ls, find, cat, and grep — instead of an embedding index. This page defines the handful of nouns the rest of the docs assume. To see them in action end to end, follow the Quickstart.

Account

Your account is the top-level tenant, created the first time you sign in with Google. It owns your workspaces, your credentials, and your plan (free or pro). Every credential you create resolves to exactly one account, and one account's data is never visible to another.

Workspace

A workspace is one isolated filesystem — a named, self-contained set of files. Accounts hold many workspaces (3 on the free plan; see Limits), and nothing crosses the boundary between them: a credential scoped to one workspace can never read another.

Workspace names are stable identifiers you choose — 1–64 lowercase letters, digits, hyphens, or underscores, starting and ending with a letter or digit (for example, handbook, acme_corp, support-kb). You reference a workspace by that name in every SDK call and REST route.

The virtual filesystem

Inside a workspace, a file is just a canonical path and its extracted text — guides/onboarding.md, reports/q3.pdf. There is no on-disk tree to manage:

• Directories are derived. A directory exists exactly when a file lives under it; ls and find compute the tree from the file paths on each read.
• Reads see extracted text, not the raw bytes. During ingestion, Grepticon extracts a plain-text form of each file — Markdown and text pass through, HTML is converted to Markdown, and PDFs are read via their text layer. cat serves that extracted text, so an agent greps a PDF the same way it greps a .md file.
• No chunking, no embeddings. Files are stored and read whole. Retrieval is literal search over the text, which is what makes the tools behave like their command-line namesakes.

Async ingestion

Uploading a file is a two-step, asynchronous process:

1. The upload call returns immediately with status: 'pending'. The raw file is stored, but its text is not yet extracted.
2. A background worker extracts and normalizes the text, then flips the file to status: 'ready'. If extraction fails, the file becomes status: 'error' with an errorDetail.

Reads only ever see ready files. A pending file is invisible to ls, find, cat, and grep — which is why, right after an upload, a read can come back empty. This is the gap the SDK's waitForReady closes: it polls until the paths you name reach ready (or error), so your agent never reads a half-ingested workspace. Ingestion is deliberately unhurried; speed is a non-goal, correctness is not.

Read session

A read session is a scoped view of one workspace that an agent reads through. In the SDK, client.session(workspace) binds the four read tools to a workspace and the credential the client holds. Sessions are stateless — every ls / find / cat / grep call is an independent request — so there is nothing to open, close, or keep alive.

What a session can see is governed entirely by its credential's claims and each file's visibility. A default session sees everything; a scoped one sees only the files its claims permit. That model is the subject of Access control.

Credentials, in one line

Two bearer credentials reach the API: a grp_sk_ management key (full control over an account) and a grp_at_ access token (read-only, one workspace). Authentication covers both.

Where to go next

• Quickstart — the whole loop, signup to agent answer.
• Tools — how ls / find / cat / grep behave and when to reach for each.
• Access control — scope what an agent can see with the claims × visibility model.