> ## 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. # Core Concepts > Understand the Runtools platform primitives 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: ```text theme={null} 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: ```bash theme={null} 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()`. ```typescript theme={null} 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: ```typescript theme={null} 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](/sdk/hosted-connect) when your product's users need to connect their own Gmail, Stripe, Slack, HubSpot, Google Sheets, API-key tools, or other integrations. ```typescript theme={null} 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 Lifecycle, SSH, dev URLs, mounts, and monitoring. Persistent storage, sandbox mounts, and agent filesystem memory. Agent definitions, running, threading, and attachments. End-user integrations, product-scoped tool calls, usage, audit, and channels. Let customers connect their own accounts to products built on Runtools. Private device mesh and local device agent dispatch. Marketplace and custom tools.