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.

​
1. Create an API Key

Create an account at runtools.ai, open Dashboard -> API Keys, and create a key for local development. 
export RUNTOOLS_API_KEY=rt_live_xxx
API keys are secrets. Keep them on the server side and never commit them to source control.

​
2. Use the CLI

The CLI package is not published to npm yet. During early access, run it from the repo: 
cd runtools-cli
npm install
npm run build
node dist/index.js --help
If you are working inside the local repo, the development command is: 
bun run src/index.ts --help

​
3. Sign In

runtools login

# Or store an API key for scripts and CI.
runtools auth set-key "$RUNTOOLS_API_KEY"
Check the active identity: 
runtools auth status
runtools auth whoami

​
4. Create a Sandbox

runtools sandbox create --name my-first-sandbox --template base-ubuntu
runtools sandbox list
Run a command: 
runtools sandbox exec my-first-sandbox "echo Hello from Runtools"
Connect with SSH: 
runtools ssh-key add my-laptop --file ~/.ssh/id_ed25519.pub
runtools sandbox ssh my-first-sandbox

​
5. Add Persistent Files For Agents

If an agent should keep project state between runs, create a workspace and mount it into the sandbox. The mounted workspace is the agent’s persistent filesystem memory. 
curl -X POST https://api.runtools.ai/v1/workspaces \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Project","slug":"my-project"}'
Use the returned workspace ID when creating a sandbox: 
runtools sandbox create \
  --name my-agent-sandbox \
  --template base-ubuntu \
  --mount 9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e:/workspace
An agent linked to my-agent-sandbox can read and write /workspace. Those files remain available for future runs.

​
6. Use the SDK

The SDK package is also not published to npm yet. In this multi-repo workspace, link it locally or use the local file dependency used by the CLI. 
import { RunTools } from '@runtools/sdk';

const rt = new RunTools({ apiKey: process.env.RUNTOOLS_API_KEY });

const sandbox = await rt.sandbox.create({
  name: 'sdk-demo',
  template: 'base-ubuntu',
});

await sandbox.waitForReady();

const result = await sandbox.exec('pwd && ls -la', { cwd: '/workspace' });
console.log(result.stdout);

await sandbox.destroy();

​
7. Expose a Dev Server

Start a server in the sandbox, then ask Runtools for the protected URL: 
runtools sandbox exec my-first-sandbox "cd /workspace && npm run dev -- --host 0.0.0.0"
runtools sandbox url my-first-sandbox --port 3000 --open

​
8. Pause or Destroy

Pause keeps the environment available for later while stopping active compute use: 
runtools sandbox pause my-first-sandbox
runtools sandbox resume my-first-sandbox
Destroy removes the sandbox: 
runtools sandbox destroy my-first-sandbox --force

​
Next Steps

Sandboxes

Learn lifecycle, SSH, dev URLs, mounts, and monitoring.

Agents

Define and run agents.

Tool Hub

Install, execute, and publish tools.

CLI Reference

See every implemented command group.