Core Concepts

Runtools is a small set of primitives that compose. Learn these seven and everything else — the SDK, the CLI, the dashboard — is just a different way to drive them.

Platform primitives

Primitive	What it means
Sandbox	A cloud environment for commands, SSH, dev servers, and agent work
Agent	A configured model, prompt, tool list, execution mode, and optional linked resources
Tool	A hosted integration action. Tools can be public marketplace tools or org-private custom tools
Workspace	Persistent org storage that can be mounted into sandboxes, used as filesystem memory for sandbox-backed agents, or attached to managed agents
Thread	A persisted conversation with durable event history, rollouts, and live WebSocket frames
RunMesh	Private device and sandbox mesh used for local device agents and private dispatch
Model tier	Platform models billed by token usage, or BYOK models that use customer-provided keys
Project	A dashboard grouping for resources inside one organization
Product app	A customer-facing app built on Runtools where each end user has app-scoped integrations, usage, audit, and channel identity

Project Layout

runtools init creates a deployable TypeScript project:

my-project/
  runtools.config.ts
  agents/example-agent.ts
  tools/example-tool.ts
  sandboxes/dev-env.ts
  package.json
  tsconfig.json

Deploy reads sandboxes/, tools/, and agents/ in that order, because agents can reference project sandboxes and deployed tools:

runtools deploy
runtools deploy --dry-run
runtools deploy --tools-only
runtools deploy --agents-only
runtools deploy --sandboxes-only

Managed sandboxes created by deploy are tracked with tags. If a sandbox config is removed later, deploy can keep it or destroy it with --prune.

Sandboxes

Sandboxes provide a Linux environment with root access, a workspace directory, optional persistent workspace mounts, public dev URLs, SSH, and optional browser desktop access.

State	Meaning
`pending` / `creating`	The sandbox record exists and startup is in progress
`running`	Ready for exec, SSH, URLs, and agent runs
`pausing` / `paused`	Lifecycle state is being preserved or already paused
`resuming`	Resume is in progress
`destroying` / `destroyed`	Deletion is in progress or complete
`failed` / `error` / `suspected_missing`	The service could not verify or complete the lifecycle step

Common templates:

Template	Use
`base-ubuntu`	Headless command-line development
`desktop-ubuntu`	Browser desktop and VNC-style access

Workspaces

Workspaces are persistent storage outside the sandbox lifecycle. When you mount a workspace into a sandbox, it appears as a filesystem at /workspace or a subpath such as /workspace/data. Sandbox-backed agents use the same mounted path as their persistent filesystem memory. The agent can edit files, create task notes, keep repo state, and produce artifacts inside /workspace; those files remain available for later runs even if the sandbox is paused, destroyed, or recreated with the same mount. Threads preserve conversation history. Workspaces preserve files.

Agents

Agents are created in the dashboard, via POST /v1/agents, or by deploying agents/*.ts files that call defineAgent().

import { defineAgent } from '@runtools-ai/sdk';

export default defineAgent({
  slug: 'code-assistant',
  name: 'Code Assistant',
  model: 'claude-sonnet-4',
  systemPrompt: 'You are a careful software engineer.',
  tools: ['exec_command', 'write_stdin', 'apply_patch', 'view_image', 'web_search'],
  sandbox: 'dev-env',
  maxIterations: 25,
});

Execution modes:

Mode	Use
`in_sandbox`	Runs against one linked sandbox. This is the default for deployed project agents
`managed`	Runs in the managed runtime with attached workspace/sandbox resources
`local-mac`	Local device runtime. Dispatches to a registered RunMesh device. Create or edit these from the dashboard/API today

Threads are shared across those modes. A run started from the dashboard, CLI, SDK, iOS, or desktop app writes the same durable thread events and live frames.

Threads

Thread history is canonical JSONL under workspace-backed storage. agent_threads and thread_rollouts are projections used for fast reads, compaction, and live status. Runtime-local caches are not authoritative. Durable frames include user messages, assistant messages, tool calls/results, run lifecycle, and compaction lifecycle. Token, reasoning, source, and tool-output deltas are transient WebSocket frames and are not written as JSONL.

RunMesh

RunMesh registers private devices and sandboxes as org-scoped nodes. Local device agents bind to a RunMesh device, so any client can start the agent while the work runs on that device.

Models

Agents can use Platform models or BYOK models. Platform model usage is billed by tokens through Runtools-managed capacity. BYOK usage uses customer-provided provider keys and is not charged as Platform inference.

Tools

Tools run on the Tools service and return structured results to agents or direct API callers. The public SDK surface is:

await rt.tools.marketplace();
await rt.tools.search('github');
await rt.tools.install('github');
await rt.tools.list();
await rt.tools.execute('github', {
  action: 'list_repos',
  params: {},
});

Custom tools are TypeScript files using defineTool() and are deployed with runtools deploy.

Product Apps

Product apps are for SaaS-style products built on Runtools. Your app keeps its own users and auth. Runtools receives a stable appId and externalUserId, then scopes tool credentials, agent runs, channel identities, usage, and audit to that product user. Use Hosted Connect when your product’s users need to connect their own Gmail, Stripe, Slack, HubSpot, Google Sheets, API-key tools, or other integrations.

await rt.tools.execute('gmail', {
  action: 'list_emails',
  params: { max_results: 10 },
  credentialScope: 'end_user',
  endUser: {
    appId: 'atlas',
    externalUserId: currentUser.id,
  },
});

End-user scoped tool calls never fall back to builder Connected Apps or org defaults.

Credentials

Runtools separates credentials by purpose:

Credential	Managed by
API keys	Credentials -> API Keys, `runtools auth keys`, `rt.auth.*`
OAuth connections	Connected Apps, `runtools oauth`, `rt.auth.*`
Product-user integrations	Hosted Connect, `rt.connect.*`, `endUser` on agents and tools
Secrets	Secrets page, `runtools secret`, `rt.secrets.*`
SSH keys	SSH Keys page, `runtools ssh-key`, `rt.sshKeys.*`

OAuth-enabled tools resolve tokens server-side from the caller’s connected account. Manual API-key tools can use per-request credentials, stored tool credentials, or named secrets.

Next Steps

Sandboxes

Lifecycle, SSH, dev URLs, mounts, and monitoring.

Workspaces

Persistent storage, sandbox mounts, and agent filesystem memory.

Agents

Agent definitions, running, threading, and attachments.

Product Apps

End-user integrations, product-scoped tool calls, usage, audit, and channels.

Hosted Connect

Let customers connect their own accounts to products built on Runtools.

RunMesh

Private device mesh and local device agent dispatch.

Tool Hub

Marketplace and custom tools.

Getting Started

Platform

Core Features

Advanced

Platform primitives

Project Layout

Sandboxes

Workspaces

Agents

Threads

RunMesh

Models

Tools

Product Apps

Credentials

Next Steps

Sandboxes

Workspaces

Agents

Product Apps

Hosted Connect

RunMesh

Tool Hub

​Platform primitives

​Project Layout

​Sandboxes

​Workspaces

​Agents

​Threads

​RunMesh

​Models

​Tools

​Product Apps

​Credentials

​Next Steps

Sandboxes

Workspaces

Agents

Product Apps

Hosted Connect

RunMesh

Tool Hub

Platform primitives

Project Layout

Sandboxes

Workspaces

Agents

Threads

RunMesh

Models

Tools

Product Apps

Credentials

Next Steps