Instant DB

Real-time database integration with InstantDB. Use this skill when working with InstantDB apps to perform admin operations (create/update/delete entities, link/unlink relationships, query data) and subscribe to real-time data changes. Triggers include mentions of InstantDB, real-time updates, database sync, entity operations, or when OpenClaw needs to send action updates visible to humans in real-time.

Security Scan

The skill's code and README expect an InstantDB app ID and an admin token and perform admin operations, but the registry metadata declares no required credentials — this mismatch and the use of an admin credential for destructive operations warrant caution.

Purpose & Capability

The skill name/description match the included code and documentation: it integrates with InstantDB to perform queries, create/update/delete, link/unlink, transactions, and subscriptions. The required runtime dependencies (@instantdb/admin, ws) and the presented CLI/map to the described capabilities, so the feature set is coherent with the stated purpose.

Instruction Scope

SKILL.md and the CLI instruct only to run npm install, set INSTANTDB_APP_ID and INSTANTDB_ADMIN_TOKEN, and then use the provided commands. The instructions do not attempt to read unrelated files or exfiltrate data to unknown endpoints; runtime behavior is limited to operations against the InstantDB SDK and websocket subscriptions.

Install Mechanism

There is no formal install spec in the registry, but package.json and SKILL.md instruct running npm install which will fetch @instantdb/admin and ws from the public npm registry. This is expected for a Node SDK integration, but the lack of an explicit install spec in the registry metadata is an inconsistency to note.

Credentials

The skill requires INSTANTDB_APP_ID and INSTANTDB_ADMIN_TOKEN at runtime (documented in SKILL.md and enforced by the CLI), but the registry metadata incorrectly lists no required environment variables or primary credential. The admin token has broad privileges (transact, delete, link), so requesting an admin credential is proportionate to the functionality but must be explicitly declared and handled carefully — the metadata omission is a red flag.

Persistence & Privilege

The skill does not request always:true or other elevated persistence, does not modify other skills' config, and is user-invocable. It will run as a normal, on-demand/autonomous-invokable skill.

What to consider before installing

Before installing: 1) Be aware the code requires an admin-level INSTANTDB_ADMIN_TOKEN and an INSTANTDB_APP_ID — an admin token can perform destructive operations (delete/transact/link) so only provide a scoped credential or a non-production instance. 2) The registry metadata omits these required env vars — confirm with the publisher why they weren't declared and prefer skills that list needed secrets explicitly. 3) Audit the @instantdb/admin package version and its permissions, and consider running npm install and the skill in a sandboxed/test environment first. 4) If you cannot verify the skill author's trustworthiness or the package code, do not provide production admin credentials; consider creating a least-privilege test account for evaluation.

InstantDB Integration

Overview

Node.js integration for InstantDB enabling OpenClaw to perform admin operations and monitor real-time data changes via WebSocket subscriptions.

Setup

Install dependencies:

npm install

Set environment variables:

export INSTANTDB_APP_ID="your-app-id"
export INSTANTDB_ADMIN_TOKEN="your-admin-token"

Core Capabilities

1. Query Data

Fetch data using InstantDB's query syntax:

const { InstantDBClient } = require('./scripts/instantdb.js');

const client = new InstantDBClient(appId, adminToken);
const result = await client.query({
  tasks: {
    $: {
      where: { status: 'active' }
    }
  }
});

CLI:

./scripts/instantdb.js query '{"tasks": {}}'

2. Create Entities

Add new entities to a namespace:

const { entityId, result } = await client.createEntity('tasks', {
  title: 'Process data',
  status: 'pending',
  priority: 'high'
});

CLI:

./scripts/instantdb.js create tasks '{"title": "Process data", "status": "pending"}'

Optional entity ID:

./scripts/instantdb.js create tasks '{"title": "Task"}' custom-entity-id

3. Update Entities

Modify existing entity attributes:

await client.updateEntity(entityId, 'tasks', {
  status: 'completed'
});

CLI:

./scripts/instantdb.js update <entity-id> tasks '{"status": "completed"}'

4. Delete Entities

Remove entities:

await client.deleteEntity(entityId, 'tasks');

CLI:

./scripts/instantdb.js delete <entity-id> tasks

5. Link Entities

Create relationships between entities:

await client.linkEntities(taskId, assigneeId, 'assignees');

CLI:

./scripts/instantdb.js link <parent-id> <child-id> assignees

6. Unlink Entities

Remove relationships:

await client.unlinkEntities(taskId, assigneeId, 'assignees');

CLI:

./scripts/instantdb.js unlink <parent-id> <child-id> assignees

7. Real-time Subscriptions

Monitor data changes via WebSocket:

const subscriptionId = client.subscribe(
  { tasks: { $: { where: { status: 'active' } } } },
  (data) => {
    console.log('Data updated:', data);
  },
  (error) => {
    console.error('Subscription error:', error);
  }
);

// Later: client.unsubscribe(subscriptionId);

CLI (listens for specified duration):

./scripts/instantdb.js subscribe '{"tasks": {}}' 60  # Listen for 60 seconds

8. Transactions

Execute multiple operations atomically using the tx builder:

const { tx, id } = require('@instantdb/admin');

await client.transact([
  tx.tasks[id()].update({ title: 'Task 1' }),
  tx.tasks[id()].update({ title: 'Task 2' })
]);

CLI:

./scripts/instantdb.js transact '[{"op": "update", "id": "...", "data": {...}}]'

OpenClaw Usage Patterns

Action Status Updates

Send real-time progress to human observers:

const { id } = require('@instantdb/admin');

// Create status entity
const actionId = id();
await client.createEntity('actions', {
  type: 'file_processing',
  status: 'started',
  progress: 0,
  timestamp: Date.now()
}, actionId);

// Update progress
await client.updateEntity(actionId, 'actions', {
  progress: 50,
  status: 'processing'
});

// Mark complete
await client.updateEntity(actionId, 'actions', {
  progress: 100,
  status: 'completed'
});

Multi-step Workflow Tracking

Track complex operations:

const { tx, id } = require('@instantdb/admin');

const workflowId = id();
const steps = ['Extract', 'Transform', 'Validate', 'Load', 'Verify'];

// Initialize workflow with linked steps
const txs = [
  tx.workflows[workflowId].update({
    name: 'Data Pipeline',
    status: 'running',
    currentStep: 1,
    totalSteps: steps.length
  })
];

const stepIds = steps.map((name, i) => {
  const stepId = id();
  txs.push(
    tx.steps[stepId].update({
      name,
      order: i + 1,
      status: 'pending'
    }),
    tx.workflows[workflowId].link({ steps: stepId })
  );
  return stepId;
});

await client.transact(txs);

// Update as steps complete
for (let i = 0; i < stepIds.length; i++) {
  await client.updateEntity(stepIds[i], 'steps', { 
    status: 'completed' 
  });
  await client.updateEntity(workflowId, 'workflows', { 
    currentStep: i + 2 
  });
}

Human Monitoring Pattern

Humans subscribe to watch OpenClaw's actions:

// Human's frontend code
import { init } from '@instantdb/react';

const db = init({ appId });

function ActionMonitor() {
  const { data } = db.useQuery({
    actions: {
      $: {
        where: { status: { in: ['started', 'processing'] } }
      }
    }
  });
  
  return data?.actions?.map(action => (
    <div key={action.id}>
      {action.type}: {action.progress}%
    </div>
  ));
}

Streaming Progress Updates

For long-running operations, stream updates:

const { id } = require('@instantdb/admin');

async function processLargeDataset(items) {
  const progressId = id();
  
  await client.createEntity('progress', {
    total: items.length,
    completed: 0,
    status: 'running'
  }, progressId);

  for (let i = 0; i < items.length; i++) {
    // Process item...
    await processItem(items[i]);
    
    // Update every 10 items
    if (i % 10 === 0) {
      await client.updateEntity(progressId, 'progress', {
        completed: i + 1,
        percentage: Math.round(((i + 1) / items.length) * 100)
      });
    }
  }

  await client.updateEntity(progressId, 'progress', {
    completed: items.length,
    percentage: 100,
    status: 'completed'
  });
}

Transaction Patterns

See references/transactions.md for detailed transaction patterns including:

• Batch operations
• Relationship management
• Conditional updates
• State machines
• Cascade operations

Error Handling

All operations return promises that reject on failure:

try {
  const result = await client.createEntity('tasks', data);
} catch (error) {
  console.error('Operation failed:', error.message);
}

Query Syntax

See references/query_syntax.md for comprehensive query examples including:

• Where clauses and operators
• Relationship traversal
• Sorting and pagination
• Multi-level nesting

References

• InstantDB documentation: https://www.instantdb.com/docs
• Admin SDK: https://www.instantdb.com/docs/admin
• Query reference: See references/query_syntax.md
• Transaction patterns: See references/transactions.md