Concepts

This page defines the handful of nouns the rest of the docs assume. To see them in action, follow the Quickstart.

Account

Your account is the top-level tenant, created when you first sign in. It owns your workspaces, credentials, and plan. Every credential belongs to one account, and accounts never see each other's data.

Workspace

A workspace is one isolated filesystem: a named, self-contained set of files. An account can hold many (see Limits), and nothing crosses between them: a credential scoped to one workspace can't read another.

The virtual filesystem

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

• Directories are derived. A directory exists when a file lives under it; ls and find build the tree from file paths on each read.
• Reads return text. An agent reads and greps a PDF the same way it does a Markdown file, whatever the original format.
• No chunking, no embeddings. Files are stored and read whole, and retrieval is literal search over the text. That's what makes the tools behave like their command-line namesakes.

Async ingestion

Uploads through the SDK or REST API are asynchronous. Right after an upload, the file isn't readable yet, so a read can come back empty. Use the SDK's waitForReady to wait until the file is ready before reading. Files uploaded or created in the console ingest inline and are readable immediately.

Read session

A read session is an agent's scoped view of one workspace. client.session(workspace) binds the four read tools to that workspace and the client's credential. Sessions are stateless: each ls / find / cat / grep call is an independent request, with nothing to open or close.

What a session can see comes down to its credential's claims and each file's visibility: a default session sees everything, a scoped one sees only what its claims permit. See Access control.

Credentials, in one line

Two bearer credentials reach the API: a grp_sk_ management key with full account control, and a read-only grp_at_ access token scoped to 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.