Surrealist dashboard quickstart

Spectron Contexts live inside Surrealist as a SurrealDB Cloud product — alongside database instances, not a separate console. This page is a UI-first tour: Playground, Memory, Documents, and API keys — before you reach for an SDK or the REST API.

How to find your contexts

1. 1.

   Sign in to SurrealDB Cloud in Surrealist.

2. 2.

   Open your organisation → Contexts (when enabled).

3. 3.

   Subscribe to a Spectron plan (owner) if prompted, then Create context — choose a name and region.

Context names cannot be changed after creation. Provisioning is asynchronous: the new context starts in state creating, the card shows a provisioning spinner, and the workspace opens only when state becomes ready. Surrealist polls while creating, so you do not need to refresh — if you open the context URL early you see a waiting view instead of a token error.

Workspace views

Settings (organisation admins and owners only) covers context metadata, member principals, service accounts, model configuration, and usage.

You do not need the CLI for day-to-day exploration — Playground, Memory, Documents, and Scopes call the same Spectron data API your application uses. For scripted remember / recall, use Hosted quickstart or an SDK.

Overview

The Overview page is the home screen for a context. It shows:

• •

  Counts — how many documents, entities, scopes, and queries the context currently has (each tile links to its view). A brand-new context typically shows one scope (your principal's root write region) and zero everywhere else until you chat, upload, or register more paths.

• •

  Shortcuts — into Playground, Memory, Documents, and Scopes.

• •

  Integrations and API keys — links at the bottom for SDK snippets and long-lived sk-ctx-… secrets.

Use Overview as a health check; do the hands-on work in the views below.

Scopes in the dashboard

The Scopes tab is where you register slash-path folders (surrealdb/employee_1, surrealdb/employee_2, surrealdb/employee_1/books, …). Each registration can include an optional display name and description. Missing ancestors are created automatically — registering surrealdb/employee_1/books also ensures surrealdb and surrealdb/employee_1 exist in the vocabulary.

Important distinctions:

• •

  Scope tags partition data on facts, sessions, documents, and chunks — not only on upload. See Scopes apply to chat and documents, not only uploads.

• •

  Access is deny-by-default. A principal sees a scope node's facts only when explicitly granted that path (or a pattern that covers it). Grants do not implicitly flow up or down the folder tree — see Scope as security boundary.

• •

  Tombstone a scope node (scope:delete in the API) marks the folder as retired in the vocabulary — reversible in principle. POST /scopes/forget is different: it permanently erases all facts tagged under that subtree. See Forgetting memories.

Registering a path does not empty or pre-create a memory bucket. Chat and uploads can land in your write region before you register anything in Scopes — the tree is navigation and governance vocabulary as much as a prerequisite. See Default write region.

Scopes apply to chat and documents, not only uploads

Documents — optional scope sets at upload time narrow who can see the file. Paths within one set are ANDed; each set is ORed with the others. Leave scope sets empty to tag the document with your caller's full memory:write region (the same default as Playground).

Playground — Surrealist chats with a short-lived brokered token for your Cloud principal. Turns are tagged with your principal's write region unless the client passes an explicit scopes selector on the API. To experiment as surrealdb/employee_1 vs surrealdb/employee_2, use the REST API or an SDK with a key whose grants cover only that branch, and pass scopes / lens on writes and reads — for example:

curl -sS "https://<host>/api/v1/<context_id>/facts" \
  -H "Authorization: Bearer sk-ctx-..." \
  -H "Content-Type: application/json" \
  -d '{"text":"I prefer morning standups.","infer":"full","scopes":[["surrealdb/employee_1"]]}'

Settings → Users → Mint key (or service-account keys) provisions identity and attenuated grants for a principal. It does not switch Playground into that scope, and it is not the same as API keys (which return the one-time sk-ctx-… secret for applications). Use API keys or Integrations snippets for out-of-band clients; use grant-narrowed keys plus explicit scopes on each request to partition experiential memory by path.

Hands-on tour

Work through the steps below in order. Each view builds on the last so you can see how experiential memory from chat and authoritative knowledge from documents combine at recall time.

1. Chat in the Playground

Open Playground and send a few messages that establish personal context — for example:

• •

  I play the cello and mostly perform chamber music.

• •

  I'm learning the violin but still prefer lower-register instruments.

As you chat, watch the side panel on each turn. Spectron surfaces recalled facts (what it retrieved before answering) and memory updates (new experiential facts extracted from the conversation). This is the Experiential pillar forming in real time.

Use the in-app How it works popover for a short tour of the chat loop, the memory-activity panel, and the fact that you can ask about uploaded documents. Conversation state is kept per context when you leave Playground and return; switching contexts closes the previous session handle.

You can also drag and drop files onto the chat to upload them into the context's document store, and use Save as document on a message to ingest that turn via the same upload path.

2. Browse memory

When you are ready to inspect what was stored, open Memory from the sidebar.

You can explore:

• •

  Profile — stable identity-style facts about you from the conversation

• •

  Entities and attributes — structured nodes and properties extracted from turns; identity, knowledge, and context categories use distinct icons

• •

  Relations — directed links between entities (shown with clear subject → object arrows in the activity panel)

• •

  Traces — provenance back to the session turns that produced each fact

Compare what you said in Playground with what Spectron normalised into the graph. Not every phrase becomes a long-lived fact — extraction and reconciliation favour durable, reusable information.

3. Upload authoritative knowledge

Open Documents to add Authoritative pillar sources: curated files the agent should treat as ground truth beyond chat alone.

Supported uploads include plain text, markdown, JSON, HTML, PDF, and (depending on your context's ingestion profile) images, audio, and video. See Uploading documents for MIME types and pipeline behaviour.

The upload drawer closes when every file succeeds (it stays open if any upload fails). Failures surface as an inline alert and toast; unknown scopes are rejected up front. You can rename a document from the document inspector after it lands.

If you do not have a file ready, save the sample dataset below as instruments.json, upload it from Documents, and wait until the document status is ready.

{
  "instruments": [
    {
      "id": "violin",
      "name": "Violin",
      "family": "Strings",
      "type": "Bowed string",
      "size": "Small",
      "range": "G3–A7",
      "origin": "Italy",
      "typical_usage": ["Orchestra", "Chamber music", "Solo"],
      "related_instruments": ["viola", "cello"],
      "description": "A high-pitched string instrument played with a bow, known for its expressive tone."
    },
    {
      "id": "cello",
      "name": "Cello",
      "family": "Strings",
      "type": "Bowed string",
      "size": "Large",
      "range": "C2–A5",
      "origin": "Italy",
      "typical_usage": ["Orchestra", "Chamber music", "Solo"],
      "related_instruments": ["violin", "double_bass"],
      "description": "A deep-toned string instrument played seated, valued for its rich and warm sound."
    },
    {
      "id": "flute",
      "name": "Flute",
      "family": "Woodwinds",
      "type": "Aerophone",
      "size": "Small",
      "range": "C4–C7",
      "origin": "Global",
      "typical_usage": ["Orchestra", "Solo", "Band"],
      "related_instruments": ["piccolo", "clarinet"],
      "description": "A high-pitched woodwind instrument that produces sound from air blown across an opening."
    },
    {
      "id": "trumpet",
      "name": "Trumpet",
      "family": "Brass",
      "type": "Lip-vibrated",
      "size": "Medium",
      "range": "F#3–D6",
      "origin": "Ancient civilisations",
      "typical_usage": ["Orchestra", "Jazz", "Band"],
      "related_instruments": ["trombone", "horn"],
      "description": "A bright and powerful brass instrument commonly used for fanfares and melodies."
    },
    {
      "id": "piano",
      "name": "Piano",
      "family": "Keyboard",
      "type": "Hammered string",
      "size": "Large",
      "range": "A0–C8",
      "origin": "Italy",
      "typical_usage": ["Solo", "Accompaniment", "Composition"],
      "related_instruments": ["harpsichord"],
      "description": "A versatile keyboard instrument capable of playing melody and harmony simultaneously."
    },
    {
      "id": "guitar",
      "name": "Guitar",
      "family": "Strings",
      "type": "Plucked string",
      "size": "Medium",
      "range": "E2–E6",
      "origin": "Spain",
      "typical_usage": ["Solo", "Band", "Accompaniment"],
      "related_instruments": ["bass_guitar", "ukulele"],
      "description": "A popular string instrument used across many genres, played by plucking or strumming."
    },
    {
      "id": "drum_kit",
      "name": "Drum Kit",
      "family": "Percussion",
      "type": "Membranophone",
      "size": "Large",
      "range": "Varies",
      "origin": "Global",
      "typical_usage": ["Band", "Jazz", "Rock"],
      "related_instruments": ["snare_drum", "cymbals"],
      "description": "A collection of percussion instruments played together to provide rhythm."
    },
    {
      "id": "harp",
      "name": "Harp",
      "family": "Strings",
      "type": "Plucked string",
      "size": "Large",
      "range": "C1–G7",
      "origin": "Ancient civilisations",
      "typical_usage": ["Orchestra", "Solo"],
      "related_instruments": ["lyre"],
      "description": "A large string instrument with strings stretched vertically, played by plucking."
    }
  ]
}

After ingestion completes, search document chunks in Documents (for example, cello range) and confirm entities from the file appear under Memory.

4. Ground answers in both pillars

Return to Playground and ask questions that require both your earlier chat and the uploaded catalogue — for example:

• •

  What instrument family does the cello belong to, and how does that relate to what I play?

• •

  Suggest a bowed string instrument I might enjoy given my preferences.

Check the recall panel again. You should see hits from experiential memory (your stated preferences) and authoritative knowledge (instrument metadata from the JSON file). That combination is the core Spectron loop: chat forms memory, documents supply curated facts, and recall merges both at answer time.

How Cloud authentication works

SurrealDB Cloud uses two planes:

End users never paste Spectron's root management API key into Surrealist. Cloud holds that credential server-side.

**Members** obtain a **short-lived brokered token** via Cloud (`POST …/spectron_contexts/{id}/access_tokens`) — mapped to a Spectron principal with `external_id = surreal-cloud:`. Surrealist uses this token to power **Playground**, **Memory**, **Documents**, and **Scopes** in the browser.

Admins and owners manage contexts through Cloud. The SurrealDB Cloud API also proxies Spectron management operations (principals, grants, scopes, usage, providers) for admin callers.

See API keys and delegation for broker semantics on the Spectron side.

API keys (application integration)

Open API keys inside your context. You will see:

• •

  Endpoint — https://{context.host} (per-context hostname)

• •

  Context ID — the Spectron context identifier

• •

  Create key — name the key; the secret (sk-ctx-…) is shown once in a reveal modal (with a clear fallback if the server does not return a secret)

Use Authorization: Bearer sk-ctx-… on the data plane — see REST API. The Integrations view also includes copy-ready snippets (cURL, JavaScript, Python, Rust, and others).

If you use Surrealist's Playground only, Cloud may have already brokered a short-lived key for your session (see How Cloud authentication works above).

curl -sS "https://<host>/api/v1/<context_id>/facts" \
  -H "Authorization: Bearer sk-ctx-..." \
  -H "Content-Type: application/json" \
  -d '{"text":"I was promoted to CTO.","infer":"full","scopes":[["org/acme/user/alice"]]}'

Playground and other dashboard writes tag memory with your principal's write region when you have not chosen a narrower path. Facts can exist before you register paths in the Scopes tab — that view is the scope vocabulary (browsing and registering slash paths), not a prerequisite empty bucket. Register paths when you want explicit partitioning or org/user hierarchy; see Contexts and scope.

Next steps

• •

  Hosted quickstart — first remember / recall from your terminal

• •

  Uploading documents — REST upload, polling, and scopes

• •

  Integrations — Python, TypeScript, and Swift SDKs

• •

  Contexts and scope — slash-path scope model

• •

  Eight pillars and six categories — how Playground and Documents map onto Spectron's memory model