API Reference@crux/core
Workspaces
API reference for durable, path-addressed agent workspaces.
Import from @crux/core/workspace:
import { workspace, workspaceToolNames } from '@crux/core/workspace'
import type { BlobStore } from '@crux/core/storage'workspace()
const ws = workspace({
id: 'research',
namespace: `thread:${threadId}`,
storage,
})Defaults:
/workspace
/outputsMethods
await ws.list('/workspace/**/*.md')
await ws.read('/workspace/notes.md')
await ws.write('/outputs/report.md', '# Report')
await ws.edit('/outputs/report.md', { find: 'draft', replace: 'final' })
await ws.delete('/outputs/report.md')deleteWorkspaceFile is not auto-injected unless tools.delete is enabled.
Prompt Injection
prompt({
id: 'agent',
use: [ws],
system: 'Use the workspace for durable files.',
})Manual control:
use: [ws.asContext()]
tools: ws.asTools({ prefix: 'research' })Blob Stores
Use BlobStore for binary and oversized workspace files.
Custom stores implement:
interface BlobStore {
put(input: BlobPutInput): Promise<BlobRef>
get(uri: string): Promise<BlobReadResult>
delete?(uri: string): Promise<void>
}Use @crux/convex for Convex storage:
import { storage } from '@crux/core/storage'
import { convexWorkspaceBlobStore } from '@crux/convex'
const ws = workspace({
id: 'research',
namespace: threadId,
storage: storage({
data,
blobs: convexWorkspaceBlobStore({ ctx }),
}),
})See Storage for the difference between DataStore, VectorStore, and BlobStore, and BlobStore for custom S3/R2/GCS-style blob stores.
Tool Names
const names = workspaceToolNames({ prefix: 'research' })
names.list // listResearchWorkspace
names.writeFile // writeResearchWorkspaceFileUse this helper when matching workspace tools in middleware.