runtimeuse (Runtime)

TypeScript runtime package for runtimeuse. Runs inside the sandbox and handles the agent lifecycle: receives invocations over WebSocket, executes your agent handler, manages artifact uploads, runs pre-commands, downloads runtime files, and sends structured results back to the client.

This package is used together with the Python client in runtimeuse-client, which connects to the runtime from outside the sandbox.

Installation

npm install runtimeuse

Quick Start

Run the runtime inside any sandbox:

export OPENAI_API_KEY=your_openai_api_key
npx -y runtimeuse@latest

This starts a WebSocket server on port 8080 using the OpenAI agent handler (default). You can choose between built-in handlers:

• openai (default) -- uses @openai/agents SDK
• claude -- uses @anthropic-ai/claude-agent-sdk with Claude Code tools and bypassPermissions mode

The Claude handler requires the claude CLI to be installed in the sandbox environment.

npx -y runtimeuse@latest                    # OpenAI (default)
npx -y runtimeuse@latest --agent claude     # Claude

Use it programmatically:

import { RuntimeUseServer, openaiHandler, claudeHandler } from "runtimeuse";

const server = new RuntimeUseServer({ handler: openaiHandler, port: 8080 });
await server.startListening();

Pair this with the richer Python client examples in runtimeuse-client, including streamed assistant messages and pre_agent_downloadables for bootstrapping files into the sandbox before invocation.

Custom Handler

Implement AgentHandler to plug in your own agent:

import { RuntimeUseServer } from "runtimeuse";
import type {
  AgentHandler,
  AgentInvocation,
  AgentResult,
  MessageSender,
} from "runtimeuse";

const handler: AgentHandler = {
  async run(
    invocation: AgentInvocation,
    sender: MessageSender,
  ): Promise<AgentResult> {
    sender.sendAssistantMessage(["Running agent..."]);

    const output = await myAgent(
      invocation.systemPrompt,
      invocation.userPrompt,
    );

    return {
      type: "structured_output",
      structuredOutput: output,
      metadata: { duration_ms: 1500 },
    };
  },
};

const server = new RuntimeUseServer({ handler, port: 8080 });
await server.startListening();

Core Concept: AgentHandler

The AgentHandler interface is the single integration point. Implement run() to plug in any agent.

interface AgentHandler {
  run(invocation: AgentInvocation, sender: MessageSender): Promise<AgentResult>;
}

AgentInvocation -- everything your agent needs:

| Field | Type | Description | | -------------- | ---------------------------------------------------------- | ------------------------------------------ | | systemPrompt | string | System prompt for the agent | | userPrompt | string | User prompt / task description | | outputFormat | { type: "json_schema"; schema: Record<string, unknown> } | Expected output schema | | model | string | Model identifier | | env | Record<string, string> (optional) | Environment variables to pass to the agent | | secrets | string[] | Values to redact from logs | | signal | AbortSignal | Observe for cancellation (read-only) | | logger | Logger | Prefixed logger for this invocation |

MessageSender -- send intermediate messages back to the client:

sender.sendAssistantMessage(["Step 1: Navigating to login page..."]);
sender.sendErrorMessage("Something went wrong", { code: "TIMEOUT" });

AgentResult -- what your handler returns (discriminated union):

type AgentResult =
  | { type: "text"; text: string; metadata?: Record<string, unknown> }
  | {
      type: "structured_output";
      structuredOutput: Record<string, unknown>;
      metadata?: Record<string, unknown>;
    };

Server Options

CLI

npx runtimeuse                            # OpenAI handler (default)
npx runtimeuse --agent claude             # Claude handler
npx runtimeuse --handler ./my-handler.js  # custom handler
npx runtimeuse --port 3000                # custom port

Programmatic

import { RuntimeUseServer } from "runtimeuse";

const server = new RuntimeUseServer({
  handler: myHandler,
  port: 8080, // default: 8080
  uploadTimeoutMs: 30_000,
  artifactWaitMs: 60_000,
  postInvocationDelayMs: 3_000,
});

await server.startListening();
// ... later
await server.stop();

Direct Session Usage

For custom WebSocket servers:

import { WebSocketSession, UploadTracker } from "runtimeuse";

wss.on("connection", (ws) => {
  const session = new WebSocketSession(ws, {
    handler: myHandler,
    uploadTracker: new UploadTracker(),
  });
  session.run();
});

Invocation Lifecycle

When a client sends an invocation_message, the session:

1. Downloads runtime files -- if pre_agent_downloadables is set, fetches and extracts them
2. Runs pre-commands -- if pre_agent_invocation_commands is set, executes them. Each command can specify its own env and cwd. If it exits 0, execution continues to the next command or the agent. Any other non-zero exit code sends an error message and terminates the invocation.
3. Calls handler.run() -- your agent logic runs with the invocation context (including any agent_env environment variables) and a MessageSender
4. Sends result_message -- the AgentResult from your handler is sent back to the client
5. Finalizes -- stops artifact watching, waits for pending uploads, closes the WebSocket

Command-Only Execution (no agent)

The session also accepts a command_execution_message instead of an invocation_message. This runs pre_execution_downloadables and the provided commands, streams stdout/stderr as command_output_messages (each carrying stream, text, and command), and returns a command_execution_result_message with per-command exit codes. The agent handler never gets invoked. Each command can specify its own env and cwd. See the Python client docs for usage.

Environment Variables

Environment variables can be injected at two levels:

• Per-command (Command.env) -- each command in pre_agent_invocation_commands, post_agent_invocation_commands, or command_execution_message.commands can carry its own env map. These are merged on top of process.env when the command is spawned.
• Per-invocation (InvocationMessage.agent_env) -- environment variables passed to the agent handler. The Claude handler merges these on top of process.env when calling the Claude Agent SDK. Custom handlers receive these via AgentInvocation.env.

Artifact Management

Files written to any of the artifact directories are automatically detected via chokidar file watching and uploaded through a presigned URL handshake with the client. The directories to watch are specified per-invocation via the artifacts_dirs field (a string[]) on the InvocationMessage or CommandExecutionMessage. The legacy singular artifacts_dir field is still accepted but deprecated.

• The client provides the content_type for each artifact via the presigned URL response
• .artifactignore files are respected (same syntax as .gitignore)
• Default ignore patterns exclude node_modules/, dist/, __pycache__/, virtual environments, etc.

Secret Redaction

The redactSecrets utility recursively replaces secret values in strings, arrays, and objects:

import { redactSecrets } from "runtimeuse";

const safe = redactSecrets("token=sk-abc123", ["sk-abc123"]);
// "token=[REDACTED]"

Command output (stdout/stderr) from pre-commands is automatically redacted using the command's environment variable values.

API Reference

Classes

| Class | Description | | ------------------ | ---------------------------------------------------------------- | | RuntimeUseServer | Standalone WebSocket server that creates sessions per connection | | WebSocketSession | Manages a single WebSocket connection lifecycle | | ArtifactManager | Watches a directory and handles the upload handshake | | UploadTracker | Tracks in-flight uploads with timeout support | | CommandHandler | Executes shell commands with secret redaction and abort support | | DownloadHandler | Downloads files via fetch() with automatic zip extraction |

Functions

| Function | Description | | ------------------------------------ | -------------------------------------------------- | | uploadFile(path, url, contentType) | Upload a file to a presigned URL | | redactSecrets(value, secrets) | Recursively redact secrets from any data structure | | createLogger(sourceId) | Create a prefixed logger | | sleep(ms) | Promise-based sleep |

Protocol Message Types

| Type | Direction | Description | | ------------------------------- | ----------------- | ---------------------------------------- | | InvocationMessage | Client -> Runtime | Start an agent invocation | | CommandExecutionMessage | Client -> Runtime | Run commands without agent invocation | | CancelMessage | Client -> Runtime | Cancel a running invocation or execution | | ArtifactUploadResponseMessage | Client -> Runtime | Presigned URL for artifact upload | | ResultMessage | Runtime -> Client | Structured agent result | | CommandExecutionResultMessage | Runtime -> Client | Per-command exit codes | | AssistantMessage | Runtime -> Client | Intermediate text from the agent | | ArtifactUploadRequestMessage | Runtime -> Client | Request a presigned URL for an artifact | | ErrorMessage | Runtime -> Client | Error during execution |

Related Docs

• Repository overview
• Python client README