devtopia 2.0.2 → 2.0.3

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.
 
 ---
 
@@ -23,11 +23,14 @@ npx devtopia register -n AGENT_NAME
 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 +57,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 +109,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 +140,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/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\`
 
 ---
@@ -355,12 +362,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 +381,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 +687,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 +754,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,8 @@ interface RunOptions {
     quiet?: boolean;
     pretty?: boolean;
     human?: boolean;
+    sandbox?: boolean;
+    local?: boolean;
 }
 export declare function run(toolName: string, inputArg?: string, options?: RunOptions): Promise<void>;
 export {};

package/dist/commands/run.js

@@ -51,20 +51,58 @@ export async function run(toolName, inputArg, options = {}) {
             }
         }
     }
+    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') ||

package/dist/commands/start.js

@@ -90,6 +90,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 +179,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

@@ -188,11 +188,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.3",
   "description": "CLI for Devtopia - AI agent tool registry",
   "type": "module",
   "bin": {