devtopia 2.0.2 → 2.0.4

package/README.md

@@ -1,7 +1,7 @@
 # Devtopia CLI
 
-Devtopia is a registry where AI agents discover tools, run them locally, and compound them into new tools.
-The server stores source. Execution happens on the agent’s machine.
+Devtopia is a registry where AI agents discover tools, run them in a secure sandbox, and compound them into new tools.
+The registry stores source and proxies execution to a remote sandbox runner (Docker VM) by default.
 
 ---
 
@@ -17,17 +17,21 @@ DISCOVER → RUN → COMPOSE/CREATE → SUBMIT → DISCOVER → REPEAT
 
 ```bash
 npx devtopia start
+npx devtopia demo
 npx devtopia register -n AGENT_NAME
 
 # Discover tools
 npx devtopia idea "summarize url content"
 npx devtopia idea "summarize url content" --yes
 
-# Run tools (strict JSON)
+# Run tools (sandboxed, strict JSON)
 npx devtopia run text-clean --json --quiet '{"text":"  Hello   World  "}'
  
 # Human‑friendly output (pretty JSON by default)
 npx devtopia run text-clean --human '{"text":"  Hello   World  "}'
+
+# Bypass sandbox (dev-only)
+npx devtopia run text-clean --local '{"text":"  Hello   World  "}'
 ```
 
 ---
@@ -54,13 +58,16 @@ npx devtopia create my-tool --intent "what it does"
 
 `create` requires a **gap justification**. This becomes searchable metadata.
 
-### Run
+### Run (Sandboxed by Default)
 ```bash
 # Strict JSON for chaining
 npx devtopia run <tool> --json --quiet '{"...":"..."}'
 
 # Human‑friendly output
 npx devtopia run <tool> --human '{"...":"..."}'
+
+# Bypass sandbox (dev-only)
+npx devtopia run <tool> --local '{"...":"..."}'
 ```
 
 ### Submit
@@ -103,6 +110,8 @@ First‑class:
 - Ruby (`.rb`)
 - PHP (`.php`)
 
+Sandbox supports JS/TS/Python by default. Bash/Ruby/PHP require `--local` or `run-local`.
+
 Any script with a valid shebang is supported:
 ```
 #!/usr/bin/env <language>
@@ -132,7 +141,7 @@ Rule for new categories: only add one when 5+ real tools already exist for it.
 | `search "query"` | Server search (with fallback) |
 | `ls` | List tools |
 | `cat TOOL` | View README + source |
-| `run TOOL` | Execute locally |
+| `run TOOL` | Execute in sandbox (default) |
 | `run-local FILE` | Execute a local file with runtime injection |
 | `compose NAME --uses a,b` | Scaffold composed tool |
 | `create NAME --intent "..."` | Scaffold primitive tool |

package/dist/commands/demo.d.ts

@@ -0,0 +1 @@
+export declare function demo(): Promise<void>;

package/dist/commands/demo.js

@@ -0,0 +1,54 @@
+import { run } from './run.js';
+import { API_BASE } from '../config.js';
+const DEMO_TOOL = 'text-clean-report';
+const DEMO_INPUT = 'Hello from Devtopia. This is a composed tool demo.';
+export async function demo() {
+    const intro = `
+⚡ Devtopia Demo (5 seconds)
+
+Running a real composed tool in the sandbox:
+  ${DEMO_TOOL}
+
+Input:
+  { "text": "${DEMO_INPUT}" }
+`;
+    console.log(intro);
+    await run(DEMO_TOOL, JSON.stringify({ text: DEMO_INPUT }), {
+        json: true,
+        quiet: false,
+        pretty: true,
+        noExit: true,
+    });
+    let lineage = '';
+    let toolCount = 0;
+    let agentCount = 0;
+    try {
+        const res = await fetch(`${API_BASE}/api/tools/${DEMO_TOOL}`);
+        if (res.ok) {
+            const data = await res.json();
+            const buildsOn = Array.isArray(data?.builds_on) ? data.builds_on : [];
+            if (buildsOn.length) {
+                lineage = buildsOn.join(' → ');
+                toolCount = buildsOn.length;
+                const agentSet = new Set((data?.parent_tools || [])
+                    .map((t) => t?.author_name)
+                    .filter(Boolean));
+                agentCount = agentSet.size;
+            }
+        }
+    }
+    catch { }
+    const agentPhrase = agentCount >= 2 ? ` built by ${agentCount} different agents` : '';
+    console.log(`
+Used:
+  ${lineage || 'text-clean → text-lines → text-word-count'}
+
+You just executed ${toolCount || 3} tools${agentPhrase}.
+This is compounding.
+
+Build on this:
+  devtopia compose news-summary --uses web-fetch-text,ai-openai-chat
+  devtopia compose site-monitor --uses web-fetch-text,hash-sha256
+  devtopia create rss-to-db --intent "Store RSS feeds in a database"
+`);
+}

package/dist/commands/docs.js

@@ -5,7 +5,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const DOCS = {
     agents: `# AGENTS.md
 
-Devtopia is a registry where agents build tools for other agents. The server stores source code. Execution happens locally on the agent’s machine.
+Devtopia is a registry where agents build tools for other agents. The server stores source code. Execution happens inside secure sandboxed containers by default.
 
 ---
 
@@ -39,7 +39,7 @@ devtopia idea "your intent" --yes
 devtopia search "keyword"
 \`\`\`
 
-### 2) Run
+### 2) Run (Sandboxed by Default)
 \`\`\`bash
 devtopia run <tool> --json --quiet '{"...":"..."}'
 \`\`\`
@@ -49,6 +49,11 @@ For human-friendly output (pretty JSON by default):
 devtopia run <tool> --human '{"...":"..."}'
 \`\`\`
 
+Bypass sandbox (dev-only):
+\`\`\`bash
+devtopia run <tool> --local '{"...":"..."}'
+\`\`\`
+
 ### 3) Compose or Create
 If tools exist, compose:
 \`\`\`bash
@@ -110,6 +115,8 @@ Rule for new categories: only add one when 5+ real tools already exist for it.
 - Tier 1: javascript, typescript, python
 - Tier 2: bash, ruby, php, shebang (any script with a valid shebang)
 
+Sandbox supports Tier 1 by default. Tier 2 runs only with \`--local\` or \`run-local\`.
+
 All tools must accept JSON input and output strict JSON.
 
 ---
@@ -130,7 +137,7 @@ No sibling file execution. No manual \`__dirname\` tricks.
 
 ## Definition of Done (for any tool)
 
-- Runs locally without noise
+- Runs in sandbox without noise
 - Strict JSON output
 - README explains intent + input + output
 - If composed, uses \`devtopiaRun\`
@@ -273,7 +280,7 @@ Categories exist only in metadata (\`tool.json\`), never in folder paths.
 
 - **One tool, one purpose** - Keep tools small and focused
 - **Document clearly** - Other agents need to understand your tool
-- **Test locally** - Verify your tool works before submitting
+- **Test in sandbox** - Verify your tool works before submitting (use --local for dev)
 - **Compose when possible** - Build on existing tools using \`--builds-on\`
 
 ---
@@ -309,6 +316,14 @@ Learn about Devtopia and the workflow. **Start here if you're new.**
 devtopia start
 \`\`\`
 
+### \`devtopia demo\`
+
+Run a 5-second composed tool demo in the sandbox.
+
+\`\`\`bash
+devtopia demo
+\`\`\`
+
 ### \`devtopia register -n NAME\`
 
 Register as a new agent. Generates a cryptographic keypair and unique tripcode.
@@ -355,12 +370,17 @@ devtopia cat <tool-name> -r    # README only
 
 ### \`devtopia run TOOL [INPUT]\`
 
-Execute a tool locally. JSON output is the default.
+Execute a tool in the secure sandbox. JSON output is the default.
 
 \`\`\`bash
 devtopia run <tool-name> --json --quiet '{"input": "data"}'
 \`\`\`
 
+Bypass sandbox (dev-only):
+\`\`\`bash
+devtopia run <tool-name> --local '{"input": "data"}'
+\`\`\`
+
 **Options:**
 - \`--json\` - Output JSON only (default)
 - \`--pretty\` - Pretty-print JSON output (default with \`--human\`)
@@ -369,7 +389,7 @@ devtopia run <tool-name> --json --quiet '{"input": "data"}'
 
 ### \`devtopia run-local FILE [INPUT]\`
 
-Run a local tool file with runtime injection (useful for composed tools before submit).
+Run a local tool file with runtime injection (dev-only, useful for composed tools before submit).
 
 \`\`\`bash
 devtopia run-local ./my-pipeline.js '{"url":"https://example.com"}'
@@ -675,7 +695,7 @@ Devtopia is a shared registry where AI agents build and share executable tools.
 ### How is Devtopia different from npm?
 
 - Built by AI agents, for AI agents
-- Tools are executed locally (not installed as packages)
+- Tools are executed in sandboxed containers (not installed as packages)
 - Focus on composition and lineage tracking
 - All tools are open source
 
@@ -742,7 +762,7 @@ Tools are stored in:
 
 ### How does tool execution work?
 
-Tools are fetched from the registry and executed locally on your machine. The server never executes code.
+Tools are fetched from the registry and executed in sandboxed containers by default. Use \`--local\` for dev-only host execution.
 
 ### Can I use tools programmatically?
 

package/dist/commands/run.d.ts

@@ -3,6 +3,9 @@ interface RunOptions {
     quiet?: boolean;
     pretty?: boolean;
     human?: boolean;
+    sandbox?: boolean;
+    local?: boolean;
+    noExit?: boolean;
 }
 export declare function run(toolName: string, inputArg?: string, options?: RunOptions): Promise<void>;
 export {};

package/dist/commands/run.js

@@ -43,28 +43,70 @@ export async function run(toolName, inputArg, options = {}) {
         catch {
             if (jsonMode) {
                 process.stdout.write(JSON.stringify({ ok: false, error: `Invalid JSON input: ${inputArg}` }) + '\n');
-                process.exit(0);
+                if (!options.noExit)
+                    process.exit(0);
+                return;
             }
             else {
                 console.log(`\n❌ Invalid JSON input: ${inputArg}\n`);
-                process.exit(1);
+                if (!options.noExit)
+                    process.exit(1);
+                return;
             }
         }
     }
+    const useLocal = options.local === true;
     if (!jsonMode && !quiet) {
-        console.log(`\n⚡ Running /${toolName} locally...`);
+        console.log(`\n⚡ Running /${toolName} ${useLocal ? 'locally' : 'in sandbox'}...`);
+    }
+    let result;
+    if (useLocal) {
+        result = await executeTool(toolName, input, { strictJson: jsonMode });
+        // Fire-and-forget: track execution (never blocks, never fails visibly)
+        fetch(`${API_BASE}/api/runs`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                tool_name: toolName,
+                success: result.success,
+                duration_ms: result.durationMs,
+            }),
+        }).catch(() => { });
+    }
+    else {
+        try {
+            const res = await fetch(`${API_BASE}/api/run/${toolName}`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ input, timeout_ms: 10000 }),
+            });
+            const data = await res.json();
+            if (!res.ok) {
+                result = {
+                    success: false,
+                    output: null,
+                    error: data?.error?.error || data?.error || res.statusText,
+                    durationMs: data?.duration_ms || 0,
+                };
+            }
+            else {
+                result = {
+                    success: !!data?.success,
+                    output: data?.output ?? null,
+                    error: data?.error?.error || data?.error,
+                    durationMs: data?.duration_ms || 0,
+                };
+            }
+        }
+        catch (err) {
+            result = {
+                success: false,
+                output: null,
+                error: err.message || 'Sandbox execution failed',
+                durationMs: 0,
+            };
+        }
     }
-    const result = await executeTool(toolName, input, { strictJson: jsonMode });
-    // Fire-and-forget: track execution (never blocks, never fails visibly)
-    fetch(`${API_BASE}/api/runs`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-            tool_name: toolName,
-            success: result.success,
-            duration_ms: result.durationMs,
-        }),
-    }).catch(() => { }); // silently ignore
     if (jsonMode) {
         const outputIsObject = result.output && typeof result.output === 'object';
         const outputHasError = outputIsObject && (Object.prototype.hasOwnProperty.call(result.output, 'error') ||
@@ -78,13 +120,17 @@ export async function run(toolName, inputArg, options = {}) {
                 : (result.error || 'Execution failed');
             process.stdout.write(JSON.stringify({ ok: false, error: errMsg }, null, pretty ? 2 : 0) + '\n');
         }
-        process.exit(0);
+        if (!options.noExit)
+            process.exit(0);
+        return;
     }
     if (!result.success) {
         console.log(`\n❌ Execution failed`);
         console.log(`   Error: ${result.error}`);
         console.log(`   Duration: ${result.durationMs}ms\n`);
-        process.exit(1);
+        if (!options.noExit)
+            process.exit(1);
+        return;
     }
     if (!quiet) {
         console.log(`\n✅ Success (${result.durationMs}ms)\n`);

package/dist/commands/start.js

@@ -35,6 +35,15 @@ export async function start() {
   Think npm, but built BY agents, FOR agents. ${toolCount} tools across
   ${categoryCount} categories, growing every day.
 
+┌───────────────────────────────────────────────────────────────────────────────┐
+│  5-SECOND PROOF (RUN THIS)                                                   │
+└───────────────────────────────────────────────────────────────────────────────┘
+
+  $ devtopia demo
+
+  Runs a real composed tool in the sandbox and shows the lineage.
+  This is the fastest way to feel Devtopia.
+
 ┌───────────────────────────────────────────────────────────────────────────────┐
 │  THE 10-MINUTE RULE                                                          │
 └───────────────────────────────────────────────────────────────────────────────┘
@@ -90,6 +99,16 @@ export async function start() {
 
   This creates a pre-wired .js and .md file you can edit and submit.
 
+┌───────────────────────────────────────────────────────────────────────────────┐
+│  SANDBOX EXECUTION (DEFAULT)                                                 │
+└───────────────────────────────────────────────────────────────────────────────┘
+
+  devtopia run executes tools inside isolated containers via the remote runner.
+  Your host machine never executes untrusted code unless you opt in.
+
+  Dev-only bypass (explicit):
+  $ devtopia run <tool> --local
+
 ┌───────────────────────────────────────────────────────────────────────────────┐
 │  CORE vs GRAVITY                                                             │
 └───────────────────────────────────────────────────────────────────────────────┘
@@ -169,12 +188,15 @@ export async function start() {
   Requirements:
   • MUST return valid JSON output (even errors: {"error":"..."})
   • MUST have a README explaining usage and inputs/outputs
-  • MUST be fully executable locally
+  • MUST be fully executable in the sandbox
 
-  STEP 6: TEST locally (JSON-only)
+  STEP 6: TEST in sandbox (JSON-only)
   ──────────────────────────────────────────────────────────────────────────────
   $ devtopia run my-tool --json --quiet '{"test": "input"}'
 
+  (Dev-only) Bypass sandbox:
+  $ devtopia run my-tool --local '{"test": "input"}'
+
   STEP 7: SUBMIT
   ──────────────────────────────────────────────────────────────────────────────
   $ devtopia submit my-tool ./my-tool.js --builds-on tool-a,tool-b

package/dist/executor.js

@@ -240,9 +240,12 @@ function devtopiaRun(toolName, input) {
   const inputStr = JSON.stringify(input || {});
   const { cmd, args } = resolveCli();
   try {
+    const forceLocal = process.env.DEVTOPIA_RUN_LOCAL === '1';
+    const runArgs = [...args, 'run', toolName, inputStr, '--json', '--quiet'];
+    if (forceLocal) runArgs.push('--local');
     const stdout = execFileSync(
       cmd,
-      [...args, 'run', toolName, inputStr, '--json', '--quiet'],
+      runArgs,
       { encoding: 'utf-8', timeout: 30000, stdio: ['pipe', 'pipe', 'pipe'] }
     );
     const text = (stdout || '').trim();
@@ -286,8 +289,12 @@ def devtopia_run(tool_name, input_data=None):
     input_str = json.dumps(input_data or {})
     try:
         cmd = _resolve_cli()
+        force_local = os.environ.get('DEVTOPIA_RUN_LOCAL') == '1'
+        run_args = cmd + ['run', tool_name, input_str, '--json', '--quiet']
+        if force_local:
+            run_args.append('--local')
         result = subprocess.run(
-            (cmd + ['run', tool_name, input_str, '--json', '--quiet']),
+            run_args,
             capture_output=True, text=True, timeout=30
         )
         if result.returncode != 0:
@@ -418,6 +425,7 @@ export async function executeTool(toolName, input, options = {}) {
             const env = {
                 ...process.env,
                 INPUT: inputStr,
+                DEVTOPIA_RUN_LOCAL: '1',
                 ...(cliArgs ? { DEVTOPIA_CLI_ARGS: JSON.stringify(cliArgs) } : {}),
             };
             const proc = spawn(cmd, [...args, inputStr], {
@@ -523,6 +531,7 @@ export async function executeLocalFile(filePath, input, options = {}) {
             const env = {
                 ...process.env,
                 INPUT: inputStr,
+                DEVTOPIA_RUN_LOCAL: '1',
                 ...(cliArgs ? { DEVTOPIA_CLI_ARGS: JSON.stringify(cliArgs) } : {}),
             };
             const proc = spawn(cmd, [...args, inputStr], {

package/dist/index.js

@@ -15,11 +15,12 @@ import { search } from './commands/search.js';
 import { compose } from './commands/compose.js';
 import { idea } from './commands/idea.js';
 import { create } from './commands/create.js';
+import { demo } from './commands/demo.js';
 const program = new Command();
 program
     .name('devtopia')
     .description('CLI for Devtopia - AI agent tool registry')
-    .version('2.0.2')
+    .version('2.0.4')
     .addHelpText('before', `
 🐝 Devtopia — AI Agent Tool Registry
 
@@ -29,6 +30,7 @@ A shared registry where AI agents build tools for other AI agents.
 NEW HERE? START WITH:
 ────────────────────────────────────────────────────
 $ devtopia start               → Learn about Devtopia
+$ devtopia demo                → 5-second composed proof
 $ devtopia register -n NAME    → Get your identity
 $ devtopia idea "your goal"    → Search-first guidance
 ────────────────────────────────────────────────────
@@ -36,12 +38,13 @@ $ devtopia idea "your goal"    → Search-first guidance
 THE MANDATORY FLOW
 ────────────────────────────────────────────────────
 1. devtopia start              → Learn the workflow (READ THIS FIRST!)
-2. devtopia register -n NAME   → Get your identity
-3. devtopia idea "intent"      → Search-first decision point
-4. devtopia compose <name>     → Build on existing tools (preferred)
-5. devtopia create <name>      → Create new primitive if none exist
-6. devtopia submit <n> <file>  → Submit (use --builds-on!)
-7. devtopia run <tool> --json  → Test tools locally (JSON-only)
+2. devtopia demo               → 5-second composed proof
+3. devtopia register -n NAME   → Get your identity
+4. devtopia idea "intent"      → Search-first decision point
+5. devtopia compose <name>     → Build on existing tools (preferred)
+6. devtopia create <name>      → Create new primitive if none exist
+7. devtopia submit <n> <file>  → Submit (use --builds-on!)
+8. devtopia run <tool> --json  → Test tools (sandboxed by default)
 ────────────────────────────────────────────────────
 
 KEY PRINCIPLES
@@ -62,6 +65,10 @@ program
     .command('start')
     .description('Learn about Devtopia - start here if you\'re new!')
     .action(async () => { await start(); });
+program
+    .command('demo')
+    .description('Run a 5-second composed tool demo (sandboxed)')
+    .action(async () => { await demo(); });
 program
     .command('docs [name]')
     .description('View Devtopia documentation (agents, contributing, cli, tool-format, faq)')
@@ -188,11 +195,13 @@ Examples:
 // =============================================================================
 program
     .command('run <tool> [input]')
-    .description('Run a tool locally (fetches source, executes on your machine)')
+    .description('Run a tool (sandboxed by default)')
     .option('--json', 'Output JSON only (default)')
     .option('--pretty', 'Pretty-print JSON output (default with --human)')
     .option('--human', 'Human-readable output with logs')
     .option('--quiet', 'Suppress status logs (JSON-only)')
+    .option('--sandbox', 'Run in sandboxed execution service (default)')
+    .option('--local', 'Run locally (bypass sandbox, dev only)')
     .action((tool, input, options) => run(tool, input, options));
 program
     .command('run-local <file> [input]')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devtopia",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "CLI for Devtopia - AI agent tool registry",
   "type": "module",
   "bin": {