Skip to content

runtimeuse

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

runtimeuse

README.md

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