Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runtools.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Platform Primitives

PrimitiveWhat it means
SandboxA cloud environment for commands, SSH, dev servers, and agent work
AgentA configured model, prompt, tool list, execution mode, and optional linked resources
ToolA hosted integration action. Tools can be public marketplace tools or org-private custom tools
WorkflowA graph of nodes with draft/published versions, runs, cron triggers, webhook triggers, and approval resume
WorkspacePersistent org storage that can be mounted into sandboxes, used as filesystem memory for sandbox-backed agents, or attached to managed agents
ProjectA dashboard grouping for resources inside one organization

​
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 the tools/, sandboxes/, and agents/ folders in that order: 
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.
StateMeaning
pending / creatingThe sandbox record exists and startup is in progress
runningReady for exec, SSH, URLs, and agent runs
pausing / pausedLifecycle state is being preserved or already paused
resumingResume is in progress
destroying / destroyedDeletion is in progress or complete
failed / error / suspected_missingThe service could not verify or complete the lifecycle step
Common templates:
TemplateUse
base-ubuntuHeadless command-line development
desktop-ubuntuBrowser 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/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:
ModeUse
in_sandboxRuns against one linked sandbox. This is the default for deployed project agents
managedRuns in the managed runtime with attached workspace/sandbox resources
local-macDispatches to a registered RunMesh device

​
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.

​
Credentials

Runtools separates credentials by purpose:
CredentialManaged by
API keysDashboard API Keys, runtools auth keys, rt.auth.*
OAuth connectionsConnected Apps, runtools oauth, rt.auth.*
SecretsSecrets page, runtools secret, rt.secrets.*
SSH keysSSH 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.

​
Workflows

Workflows are versioned graph orchestrations. You can save drafts, publish, run, inspect events, create cron/webhook triggers, and resume approval waits: 
await rt.workflows.save({ name: 'Review PR', graph });
await rt.workflows.publish('review-pr', { visibility: 'org' });
const run = await rt.workflows.run('review-pr', { prompt: 'Review PR #123' });
await rt.workflows.events(run.runId);

​
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.

Tool Hub

Marketplace and custom tools.

Workflows

Cron and webhook workflow triggers.