Resources

Resources are pieces of context you attach to a Workspace (Canvas) so the Assistants (Agents) running there can use them. A Resource can be an uploaded file, a reference link, a freeform note, or a named variable. When an Assistant starts (spawns) inside a Workspace, every Resource in that Workspace is folded into its working context automatically — no per-Assistant wiring required.

Resources are workspace-scoped: they belong to one Workspace and are shared by all the Assistants on that Workspace’s canvas.

Resource types

There are four types, stored on the WorkspaceResource model:

Every Resource also has a name, an optional description, and createdAt / updatedAt timestamps.

How Resources reach an Assistant

When an Assistant starts, RondoFlow builds a workspace context from the Workspace’s context document plus all of its Resources, then merges it into the spawn configuration. Each type contributes differently:

Building this context is non-fatal: if it can’t be assembled for some reason, the Assistant still starts — just without the Workspace context.

Variables and secrets

A variable Resource is a varKey plus a varValue. At run time the key becomes an environment variable for the Assistant, which is the right way to pass API keys, tokens, or configuration without hard-coding them into a prompt.

How variable values are resolved

A few rules govern what actually reaches the spawned process:

• Agent-level env wins. When an Assistant already defines an environment variable with the same key, that value takes precedence — a workspace variable Resource is only applied when its key is not already present in the Assistant’s own env.
• Reserved server secrets are stripped. Variables named DATABASE_URL, BETTER_AUTH_SECRET, or rondoflow_SECRET are silently dropped before the child process launches (the blocklist is compared case-insensitively). A variable Resource cannot inject these — they belong to the server, not to a run. See Security.
• Tuning Claude’s output ceiling. A variable named CLAUDE_CODE_MAX_OUTPUT_TOKENS overrides the spawned CLI’s per-response output-token limit (default 128000, which Claude Code clamps to each model’s true maximum). This is a handy way to raise the ceiling for a single Workspace without editing the root .env.

Marking a variable secret

Set isSecret: true to mark a variable as sensitive. Two things change:

• At rest — the value is encrypted with AES-256-GCM before it touches the database. The key is derived (via scrypt) from a server secret, with a static salt so it stays stable across restarts.
• In the API — varValue is never returned for any variable Resource, secret or not. The serialized shape omits the field entirely (the shared WorkspaceResource type has no varValue at all). The API exposes varKey and isSecret, so the canvas and other clients can show that a variable exists — and whether it’s a secret — without ever exposing the value.

The plaintext value is decrypted only when an Assistant starts, so it can be placed into that run’s environment. If decryption fails (for example, because the key changed), that one variable is logged and skipped, and the Assistant continues without it.

The Resource card on the canvas

Drag a Resource card (Node) onto the Workspace from the palette at the bottom of the canvas. The card is a compact summary of everything attached to the Workspace — it shows running counts of files, links, notes, and variables, for example 3 files · 2 links and 1 note · 4 vars.

The palette item is tagged for the Standard tier, but interface complexity is currently pinned to the full tier and isn’t a user-facing setting, so tier gating is inert — the Resource card (like every other palette card) is always available.

See The Canvas for general canvas and card mechanics.

Managing Resources

All endpoints are nested under a Workspace: /api/workspaces/:workspaceId/resources. The workspaceId and any resource id must be valid UUIDs.

All responses use the standard envelope: { success, data?, error?, meta? }. See the API reference.

Creating a URL, note, or variable

The create endpoint accepts url, note, and variable types (files use the upload endpoint). The ?type= filter on the list endpoint additionally accepts file. Required fields are validated per type: a url Resource needs a url, and a variable Resource needs a varKey.

curl -X POST http://localhost:3001/api/workspaces/$WORKSPACE_ID/resources \
  -H "Content-Type: application/json" \
  -d '{
    "type": "url",
    "name": "API docs",
    "description": "Reference for the payments API",
    "url": "https://example.com/api"
  }'

curl -X POST http://localhost:3001/api/workspaces/$WORKSPACE_ID/resources \
  -H "Content-Type: application/json" \
  -d '{
    "type": "note",
    "name": "House style",
    "content": "Write in US English. Prefer short sentences."
  }'

curl -X POST http://localhost:3001/api/workspaces/$WORKSPACE_ID/resources \
  -H "Content-Type: application/json" \
  -d '{
    "type": "variable",
    "name": "Environment",
    "varKey": "APP_ENV",
    "varValue": "staging"
  }'

curl -X POST http://localhost:3001/api/workspaces/$WORKSPACE_ID/resources \
  -H "Content-Type: application/json" \
  -d '{
    "type": "variable",
    "name": "Service token",
    "varKey": "SERVICE_TOKEN",
    "varValue": "sk-live-...",
    "isSecret": true
  }'

name is limited to 200 characters and varKey to 100 characters. isSecret defaults to false.

Uploading a file

Files use a dedicated multipart endpoint. The maximum upload size is 50 MB — the server streams the upload and rejects anything larger.

curl -X POST http://localhost:3001/api/workspaces/$WORKSPACE_ID/resources/upload \
  -F "file=@./spec.pdf" \
  -F "name=Product spec"

Updating and deleting

PATCH accepts a partial body — send only the fields you want to change (name, description, url, content, varKey, varValue, isSecret). When you update a varValue on a variable that is (or is becoming) secret, the new value is re-encrypted before storage.

DELETE removes the Resource and, for files, cleans up the stored file.

Related