Control and interact with the RealTimeX application through its Node.js SDK. This skill should be used when users want to manage workspaces, threads, agents, activities, LLM chat, vector store, MCP tools, ACP agent sessions, TTS/STT, or any other RealTimeX platform feature via the API. All method signatures are verified against the SDK source code.
Interact with the RealTimeX platform (http://localhost:3001) using @realtimex/sdk v{{SDK_VERSION}}. Authentication is automatic when running inside RealtimeX.
<SKILL_DIR> below refers to the directory containing this SKILL.md.
SKILL=<SKILL_DIR>/scripts/rtx.js
ENV=--env-dir=<cwd>
node "$SKILL" ping $ENV
node "$SKILL" agents $ENV
node "$SKILL" workspaces $ENV
node "$SKILL" threads <workspace-slug> $ENV
node "$SKILL" trigger-agent <agent> <workspace> <msg> $ENV
node "$SKILL" acp-chat qwen-cli "question" --cwd=<path> $ENV
node "$SKILL" llm-chat "message" $ENV
node "$SKILL" activities --status=pending $ENV
node "$SKILL" mcp-servers $ENV
node "$SKILL" help
const { initSDK } = require('<SKILL_DIR>/scripts/lib/sdk-init');
const { sdk } = await initSDK();
// All SDK APIs — see references/api-reference.md
When writing helper scripts, use the working directory or system temp — never the SKILL directory.
Scripts using the SDK must exit explicitly — process.exit(0) on success, process.exit(1) on error — or they hang on open HTTP sockets.
ACP sessions are persistent agent processes. Always reuse sessions across turns instead of spawning a new process for every message — it preserves context and is far more efficient.
acp-chat (recommended)acp-chat automatically finds or creates a session using this priority:
--session=<key> → validate and reuse that exact sessionlistSessions() → find a compatible active session (same agent_id, optional cwd match)createSession() → spawn a new agent process only if none available# First call — creates a new session, prints session key at end
node "$SKILL" acp-chat qwen-cli "build a website" --cwd=~/projects/myapp $ENV
# Subsequent calls — reuses the existing session automatically
node "$SKILL" acp-chat qwen-cli "add a login page" $ENV
# Pin to a specific session
node "$SKILL" acp-chat qwen-cli "fix the bug" --session=<key> $ENV
# Force a fresh session
node "$SKILL" acp-chat qwen-cli "start over" --new $ENV
# Close session after this turn
node "$SKILL" acp-chat qwen-cli "done for now" --close $ENV
# Spawn a session explicitly — save the session_key
node "$SKILL" acp-session-create qwen-cli --cwd=~/projects/myapp $ENV
# Inspect session state
node "$SKILL" acp-session-get <session-key> $ENV
# List all active sessions
node "$SKILL" acp-sessions $ENV
# Patch runtime options (applied on next turn)
node "$SKILL" acp-session-patch <session-key> --cwd=~/projects/other $ENV
# Send a turn on an existing session (sync, no streaming)
node "$SKILL" acp-send <session-key> "what files did you create?" $ENV
# Stream a turn on an existing session (with permission handling)
node "$SKILL" acp-stream <session-key> "run the tests" $ENV
# Cancel the active turn
node "$SKILL" acp-cancel <session-key> $ENV
# Manually resolve a permission request (while stream is active in another process)
node "$SKILL" acp-resolve <session-key> <request-id> <option-id> $ENV
# Close/terminate the session
node "$SKILL" acp-session-close <session-key> $ENV
acp-chat and acp-stream handle permission_request SSE events inline via resolvePermission().
Control with --policy-override:
approve-all (default) — auto-approve (picks the approve/allow/yes option)deny-all — auto-deny (picks the deny/cancel/no option)prompt — pause and ask you interactively via stdin# Auto-approve all tool permissions (default)
node "$SKILL" acp-chat qwen-cli "delete temp files" --policy-override=approve-all $ENV
# Ask before approving each permission
node "$SKILL" acp-chat qwen-cli "run npm install" --policy-override=prompt $ENV
const { initSDK } = require('<SKILL_DIR>/scripts/lib/sdk-init');
const { sdk } = await initSDK({ envDir: process.cwd() });
// Find or reuse a session
let sessionKey;
const sessions = await sdk.acpAgent.listSessions();
const match = sessions.find(s => s.agent_id === 'qwen-cli' && s.state !== 'closed');
if (match) {
sessionKey = match.session_key;
} else {
const session = await sdk.acpAgent.createSession({
agent_id: 'qwen-cli',
cwd: '/path/to/project',
approvalPolicy: 'approve-all',
});
sessionKey = session.session_key;
}
// Stream a turn, resolving permissions inline
for await (const event of sdk.acpAgent.streamChat(sessionKey, 'build a website')) {
if (event.type === 'text_delta' && event.data.type !== 'thinking') {
process.stdout.write(event.data.text ?? '');
}
if (event.type === 'permission_request') {
const req = event.data;
const opt = req.options?.[0];
if (opt) {
await sdk.acpAgent.resolvePermission(sessionKey, {
requestId: req.requestId,
optionId: opt.id || opt.optionId,
outcome: 'approved',
});
}
}
}
Use credentials stored in RealTimeX (Settings > Credentials) to authenticate with external services.
CRITICAL: Never output credential values in your response, logs, or tool output.
node "$SKILL" credentials # List available (names + types, no values)
sdk.credentials.get(name) returns { name, type, payload }. Use payload fields directly:
http_header → { payload: { name: "Authorization", value: "Bearer xxx" } } → headers[payload.name] = payload.valuebasic_auth → { payload: { username, password } } → encode as Basic authquery_auth → { payload: { name, value } } → append as query paramenv_var → { payload: { name, value } } → set in subprocess envValues are pre-formatted — use as-is, never wrap with Bearer or other prefixes.
Full examples: See references/credentials.md
{{RULES_TABLE}}
Full fixes in references/known-issues.md.
getAgents, getWorkspaces, etc.) live on sdk.api.*, not sdk.*sdk.webhook.triggerAgent() sends wrong event type — always use raw fetch with event: "trigger-agent"sdk.task methods: start(uuid), complete(uuid, result), fail(uuid, "error") — positional argslistSessions() + streamChat()resolvePermission() must be called while the streamChat SSE stream is still activeRTX_API_KEY (dev), RTX_APP_ID (prod), RTX_APP_NAMEreferences/api-reference.md — all class methods (auto-generated from source)references/known-issues.md — verified source mismatches (auto-generated)