@kortix/sandbox 0.4.1 → 0.4.3

package/opencode/skills/KORTIX-deploy/references/freestyle-api.md

@@ -0,0 +1,279 @@
+# Freestyle Serverless Deployments - Full API Reference
+
+Complete reference for `freestyle.serverless.deployments.create()`.
+
+## Import
+
+```javascript
+import { freestyle, readFiles } from "freestyle-sandboxes"; // readFiles for local file deploys
+```
+
+Requires `FREESTYLE_API_KEY` environment variable.
+
+## Source Types (exactly one required)
+
+### Git Repository
+
+```typescript
+{
+  repo: "https://github.com/user/repo",  // public URL, authenticated URL, or freestyle repo ID
+  branch: "main",                         // optional, defaults to default branch
+  rootPath: "./apps/web",                 // optional, for monorepos
+}
+```
+
+Private repos: use `https://user:token@github.com/user/repo.git` or a Freestyle Git repo ID.
+
+### Inline Code
+
+```typescript
+{
+  code: `
+    import express from 'express';
+    const app = express();
+    app.get('/', (req, res) => res.send('Hello'));
+    app.listen(3000);
+  `,
+  nodeModules: {                          // required with code deploys
+    express: "^4.18.2",
+  },
+}
+```
+
+### Local Files (readFiles)
+
+```javascript
+import { readFiles } from "freestyle-sandboxes"; // NOT from /utils
+
+const files = await readFiles("./dist");  // reads dir, excludes node_modules, base64-encodes
+{
+  files,
+  entrypointPath: "server.js",           // required for file deploys - MUST be a Node.js server, not an HTML file
+}
+```
+
+`readFiles` automatically excludes `node_modules/` and handles binary files. The `entrypointPath` MUST point to a Node.js server file (e.g., Express/Hono) — pointing it at an HTML file will not serve sub-assets.
+
+### Tar URL
+
+```typescript
+{
+  tarUrl: "https://s3.example.com/signed-url/app.tar.gz",
+}
+```
+
+Useful when source is hosted externally (S3, GCS, etc).
+
+## Options
+
+### domains (required)
+
+```typescript
+domains: ["my-app.style.dev"]                    // free *.style.dev subdomain
+domains: ["app.style.dev", "app.yourdomain.com"] // multiple domains
+```
+
+Any unclaimed `*.style.dev` subdomain works instantly with SSL. Custom domains need verification first.
+
+### build
+
+```typescript
+build: true                              // auto-detect framework, run build
+build: {
+  command: "npm run build",              // custom build command
+  outDir: "dist",                        // build output directory
+  envVars: {                             // build-time env vars (NOT available at runtime)
+    NEXT_PUBLIC_API_URL: "https://api.example.com",
+    NODE_ENV: "production",
+  },
+}
+```
+
+Default: `false` (deploy files as-is). Set `true` for Next.js, Vite, and other frameworks requiring a build step. Freestyle auto-detects Next.js, Vite, and Expo.
+
+### entrypoint
+
+```typescript
+entrypoint: "server.js"                  // main file of your application
+```
+
+Auto-detected for Next.js, Vite, Expo. Specify manually for custom setups.
+
+### envVars
+
+```typescript
+envVars: {
+  API_KEY: "secret-value",               // available at RUNTIME only
+  DATABASE_URL: "postgres://...",
+}
+```
+
+NOT available at build time. For build-time vars, use `build.envVars`. Env vars are tied to deployments; to change them, create a new deployment.
+
+### nodeModules
+
+```typescript
+nodeModules: {
+  express: "^4.18.2",
+  cors: "^2.8.5",
+}
+```
+
+Only needed for `code` deploys. For git/file deploys, include your lockfile (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, or `bun.lock`) and Freestyle installs from it.
+
+### timeoutMs
+
+```typescript
+timeoutMs: 60000                         // milliseconds, idle timeout before scale-down
+```
+
+Timeout is from last TCP packet (not HTTP request), so WebSockets stay alive as long as you ping faster than the timeout.
+
+### networkPermissions
+
+```typescript
+networkPermissions: [
+  { action: "allow", domain: "api.stripe.com", behavior: "exact" },
+  { action: "allow", domain: ".*\\.amazonaws\\.com", behavior: "regex" },
+]
+```
+
+### await
+
+```typescript
+await: false                             // return immediately with deploymentId for polling
+```
+
+Default: `true` (waits for deployment to build and propagate). Set `false` to return immediately.
+
+```typescript
+// Polling pattern
+const { deploymentId } = await freestyle.serverless.deployments.create({
+  ...,
+  await: false,
+});
+const status = await freestyle.serverless.deployments.get({ deploymentId });
+```
+
+### waitForRollout
+
+```typescript
+waitForRollout: true                     // wait until deployment is fully serving traffic
+```
+
+### staticOnly
+
+```typescript
+staticOnly: true,
+publicDir: "dist",                       // directory with static files
+cleanUrls: true,                         // /about.html becomes /about
+```
+
+Serves files directly without a server entrypoint. For pure static sites.
+
+### headers
+
+```typescript
+headers: [
+  {
+    source: "^/assets/.*$",
+    headers: [{ key: "Cache-Control", value: "max-age=31536000, immutable" }],
+  },
+]
+```
+
+### redirects
+
+```typescript
+redirects: [
+  { source: "^/old-page$", destination: "/new-page", permanent: true },
+]
+```
+
+## Return Value
+
+```typescript
+const { deployment, domains } = await freestyle.serverless.deployments.create({...});
+
+deployment.deploymentId  // string - unique deployment ID
+domains                  // string[] - live URLs
+
+// With await: false
+const { deploymentId } = await freestyle.serverless.deployments.create({..., await: false});
+```
+
+## Custom Domains
+
+### Step 1: Verify ownership
+
+```typescript
+const { record, instructions } = await freestyle.domains.verifications.create({
+  domain: "example.com",
+});
+// Add TXT record: _freestyle_custom_hostname.example.com → <verification-code>
+```
+
+### Step 2: Complete verification
+
+```typescript
+await freestyle.domains.verifications.complete({ domain: "example.com" });
+```
+
+### Step 3: Configure DNS
+
+Point domain to Freestyle:
+- **APEX** (`example.com`): A record → `35.235.84.134`
+- **Subdomain** (`app.example.com`): A record for `app` → `35.235.84.134`
+- **Wildcard** (`*.example.com`): A record for `*` → `35.235.84.134`
+
+### Step 4: Deploy
+
+```typescript
+await freestyle.serverless.deployments.create({
+  ...,
+  domains: ["example.com"],
+});
+```
+
+## Framework Notes
+
+### Next.js
+
+Requires in `next.config.mjs`:
+```javascript
+const nextConfig = {
+  output: "standalone",        // required
+  images: { unoptimized: true }, // required (no Sharp on Freestyle)
+};
+export default nextConfig;
+```
+
+For local file deploys, after `npm run build`:
+```bash
+cp -r public .next/standalone/public
+cp -r .next/static .next/standalone/.next/static
+cp package-lock.json .next/standalone/package-lock.json
+```
+Then `readFiles(".next/standalone")` with `entrypointPath: "server.js"`.
+
+### Vite
+
+Auto-detected when deploying from git with `build: true`. For local file deploys, use an Express static server:
+
+```javascript
+import express from 'express';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const app = express();
+app.use(express.static(__dirname));
+app.get('*', (req, res) => res.sendFile(join(__dirname, 'index.html'))); // SPA fallback
+app.listen(3000);
+```
+
+> **WARNING**: Do NOT use `Deno.serve()` or Hono's `app.fire()`. Freestyle runs Node.js. Use `app.listen(3000)` (Express) or `serve({ fetch: app.fetch, port: 3000 })` from `@hono/node-server`.
+
+### Static Sites
+
+Static sites MUST have an Express/Hono Node.js server entrypoint. Use the same Express pattern as Vite above.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kortix/sandbox",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Kortix sandbox runtime — kortix-master, opencode config/agents/skills, and dependencies",
   "private": false,
   "scripts": {

package/patch-agent-browser.js

@@ -1,9 +1,16 @@
 const fs = require('fs');
+const { execSync } = require('child_process');
+
+// Auto-detect npm global modules directory
+const npmGlobalRoot = execSync('npm root -g').toString().trim();
+console.log('npm global root:', npmGlobalRoot);
+
+const agentBrowserDir = npmGlobalRoot + '/agent-browser/dist';
 
 // ── Patch 1: handleLaunch env var fallbacks ─────────────────────────────────
 // The Rust CLI sends a launch command to the Node.js daemon but doesn't
 // include executablePath/args/profile in the JSON. We inject env var fallbacks.
-const actionsFile = '/usr/lib/node_modules/agent-browser/dist/actions.js';
+const actionsFile = agentBrowserDir + '/actions.js';
 let actions = fs.readFileSync(actionsFile, 'utf8');
 
 const oldLaunch = [
@@ -44,7 +51,7 @@ console.log('PATCH 2 SKIPPED - upstream already allows localhost origins');
 // When AGENT_BROWSER_STREAM_PORT is set globally, ALL sessions try to bind
 // that port. Named sessions crash with EADDRINUSE. Fix: only the default
 // session uses the env var port; named sessions use the hash-based port.
-const daemonFile = '/usr/lib/node_modules/agent-browser/dist/daemon.js';
+const daemonFile = agentBrowserDir + '/daemon.js';
 let daemon = fs.readFileSync(daemonFile, 'utf8');
 
 const oldStreamPort = `const streamPort = options?.streamPort ??
@@ -85,7 +92,7 @@ console.log('PATCH 4 OK - auto-launch profile only for default session');
 // When using launchPersistentContext (profile mode), this.browser is null.
 // newTab() checks `!this.browser` and throws "Browser not launched".
 // Fix: also check this.contexts.length > 0 as an alternative.
-const browserFile = '/usr/lib/node_modules/agent-browser/dist/browser.js';
+const browserFile = agentBrowserDir + '/browser.js';
 let browser = fs.readFileSync(browserFile, 'utf8');
 
 const oldNewTabCheck = "if (!this.browser || this.contexts.length === 0) {\n            throw new Error('Browser not launched');\n        }\n        // Invalidate CDP session since we're switching to a new page";

package/services/KORTIX-presentation-viewer/run

@@ -1,37 +0,0 @@
-#!/usr/bin/with-contenv bash
-# KORTIX Presentation Viewer — s6 service
-#
-# Watches for presentations in /workspace/presentations/ and serves
-# the most recently updated one on port 3210.
-# If no presentation exists yet, waits until one appears.
-
-PRES_ROOT="/workspace/presentations"
-VIEWER="/opt/opencode/skills/KORTIX-presentation-viewer/serve.ts"
-PORT=3210
-
-wait_for_presentation() {
-    while true; do
-        if [ -d "$PRES_ROOT" ]; then
-            LATEST=$(find "$PRES_ROOT" -maxdepth 2 -name "metadata.json" -newer /tmp/.pv-last-check 2>/dev/null | head -1)
-            if [ -z "$LATEST" ]; then
-                LATEST=$(find "$PRES_ROOT" -maxdepth 2 -name "metadata.json" 2>/dev/null | head -1)
-            fi
-            if [ -n "$LATEST" ]; then
-                dirname "$LATEST"
-                return 0
-            fi
-        fi
-        sleep 3
-    done
-}
-
-touch /tmp/.pv-last-check
-
-echo "[KORTIX-pv] Waiting for a presentation in $PRES_ROOT ..."
-PRES_DIR=$(wait_for_presentation)
-echo "[KORTIX-pv] Serving: $PRES_DIR on port $PORT"
-
-touch /tmp/.pv-last-check
-
-exec s6-setuidgid abc \
-    /usr/local/bin/bun run "$VIEWER" "$PRES_DIR"

package/services/agent-browser-viewer/run

@@ -1,48 +0,0 @@
-#!/usr/bin/with-contenv bash
-# Agent Browser Viewer — s6 service
-#
-# Serves the browser viewer UI on port 9224.
-# - GET /           → viewer HTML
-# - GET /sessions   → JSON list of active sessions + stream ports
-
-echo "[agent-browser-viewer] Starting viewer on port 9224"
-
-exec s6-setuidgid abc \
-  node -e '
-    const http = require("http");
-    const fs = require("fs");
-    const path = require("path");
-
-    const html = fs.readFileSync("/opt/agent-browser-viewer/index.html");
-    const socketDir = process.env.AGENT_BROWSER_SOCKET_DIR || "/workspace/.agent-browser";
-
-    function getSessions() {
-      try {
-        const files = fs.readdirSync(socketDir);
-        const sessions = [];
-        for (const f of files) {
-          if (f.endsWith(".stream")) {
-            const name = f.replace(".stream", "");
-            const port = parseInt(fs.readFileSync(path.join(socketDir, f), "utf8").trim(), 10);
-            const hasSock = files.includes(name + ".sock");
-            if (port > 0 && hasSock) {
-              sessions.push({ name, port });
-            }
-          }
-        }
-        return sessions;
-      } catch(e) { return []; }
-    }
-
-    http.createServer((req, res) => {
-      if (req.url === "/sessions") {
-        res.writeHead(200, { "Content-Type": "application/json", "Cache-Control": "no-cache" });
-        res.end(JSON.stringify(getSessions()));
-      } else {
-        res.writeHead(200, { "Content-Type": "text/html", "Cache-Control": "no-cache" });
-        res.end(html);
-      }
-    }).listen(9224, "0.0.0.0", () => {
-      console.log("[agent-browser-viewer] Ready at http://0.0.0.0:9224");
-    });
-  '

package/services/kortix-master/run

@@ -1,16 +0,0 @@
-#!/usr/bin/with-contenv bash
-# Kortix Master — s6 service
-#
-# Reverse proxy that sits in front of OpenCode on port 8000.
-# All external traffic enters through Kortix Master, which proxies
-# to the OpenCode API server on localhost:4096.
-
-echo "[kortix-master] Starting on port 8000, proxying to OpenCode at localhost:4096"
-
-exec s6-setuidgid abc \
-  env HOME=/workspace \
-      KORTIX_MASTER_PORT=8000 \
-      OPENCODE_HOST=localhost \
-      OPENCODE_PORT=4096 \
-      PATH="/opt/bun/bin:/usr/local/bin:/usr/bin:/bin" \
-  /opt/bun/bin/bun run /opt/kortix-master/src/index.ts

package/services/lss-sync/run

@@ -1,22 +0,0 @@
-#!/usr/bin/with-contenv bash
-# lss-sync — File-watcher daemon that keeps the semantic search index in sync.
-#
-# Uses watchdog (inotify/FSEvents) to detect file changes in real time and
-# triggers re-indexing with debounce. Changes are picked up within seconds.
-#
-# Watches:
-#   /workspace       — User files and projects
-#   /workspace/.kortix — Agent memory
-
-exec s6-setuidgid abc \
-  env HOME=/workspace \
-      OPENAI_API_KEY="${OPENAI_API_KEY}" \
-      LSS_DIR=/workspace/.lss \
-      PATH="/lsiopy/bin:/usr/local/bin:/usr/bin:/bin" \
-  lss-sync \
-    --watch /workspace \
-    --exclude node_modules \
-    --exclude .git \
-    --exclude __pycache__ \
-    --startup-delay 15 \
-    --debounce 2

package/services/opencode-serve/run

@@ -1,25 +0,0 @@
-#!/usr/bin/with-contenv bash
-# OpenCode API Server — s6 service
-#
-# Runs `opencode serve` on port 4096 (internal only, proxied by kortix-master).
-# This is the headless API server, distinct from `opencode web` (the Web UI).
-
-# Wait a moment for filesystem to settle
-sleep 3
-
-cd /workspace
-
-# Ensure OpenCode data dirs exist and are owned by abc (guards against
-# Daytona race conditions where /workspace ownership may shift after startup.sh)
-mkdir -p /workspace/.local/share/opencode/log \
-         /workspace/.local/share/opencode/storage \
-         /workspace/.local/share/opencode/snapshot
-chown -R abc:abc /workspace/.local/share/opencode
-
-echo "[opencode-serve] Starting OpenCode API server on port 4096"
-
-exec s6-setuidgid abc \
-  env HOME=/workspace \
-      OPENCODE_CONFIG_DIR=/opt/opencode \
-      PATH="/opt/bun/bin:/usr/local/bin:/usr/bin:/bin" \
-  opencode serve --port 4096 --hostname 0.0.0.0

package/services/opencode-web/run

@@ -1,21 +0,0 @@
-#!/usr/bin/with-contenv bash
-# OpenCode Web UI — serves the web interface on port 3111
-#
-# Runs `opencode web` headless so it's accessible via the browser at
-# http://localhost:3111 (mapped from the container).
-
-cd /workspace
-
-# Ensure OpenCode data dirs exist and are owned by abc
-mkdir -p /workspace/.local/share/opencode/log \
-         /workspace/.local/share/opencode/storage \
-         /workspace/.local/share/opencode/snapshot
-chown -R abc:abc /workspace/.local/share/opencode
-
-exec s6-setuidgid abc \
-  env HOME=/workspace \
-      OPENCODE_CONFIG_DIR=/opt/opencode \
-      OPENCODE_SERVER_USERNAME= \
-      OPENCODE_SERVER_PASSWORD= \
-      PATH="/opt/bun/bin:/usr/local/bin:/usr/bin:/bin" \
-  opencode web --port 3111 --hostname 0.0.0.0