sandhop 0.1.0

package/dist/providers/vercel/index.js

@@ -0,0 +1,121 @@
+import { randomUUID } from "node:crypto";
+import { dirname } from "../../core/paths.js";
+import { destroyOrFalse } from "../destroy.js";
+import { toBuffer } from "../encode.js";
+import { requireCred } from "../index.js";
+import { lazyImport, lazyOnce } from "../lazy-import.js";
+const VERCEL_INSTALL_HINT = "The 'vercel' provider needs @vercel/sandbox. Run: npm i @vercel/sandbox";
+const VERCEL_PACKAGE = "@vercel/sandbox";
+const LIST_LIMIT = 100;
+const sandboxName = () => `sandhop-${randomUUID()}`;
+const isNotFoundError = (error) => {
+    if (!(error instanceof Error))
+        return false;
+    const httpError = error;
+    return httpError.status === 404 || httpError.statusCode === 404;
+};
+class VercelSandboxAdapter {
+    id;
+    sandbox;
+    host;
+    constructor(id, sandbox, host) {
+        this.id = id;
+        this.sandbox = sandbox;
+        this.host = host;
+    }
+    async uploadFile(path, data) {
+        const dir = dirname(path);
+        if (dir && dir !== "/")
+            await this.sandbox.mkDir(dir).catch(() => { });
+        await this.sandbox.writeFiles([
+            {
+                path,
+                content: toBuffer(data),
+            },
+        ]);
+    }
+    async uploadPath(remotePath, localPath) {
+        await this.sandbox.writeFiles([
+            {
+                path: remotePath,
+                content: toBuffer(this.host.readBytes(localPath)),
+            },
+        ]);
+    }
+    async exec(cmd) {
+        const result = await this.sandbox.runCommand("bash", ["-lc", cmd]);
+        return {
+            exitCode: result.exitCode,
+            stdout: await result.stdout(),
+            stderr: await result.stderr(),
+        };
+    }
+    async spawn(cmd) {
+        await this.sandbox.runCommand({
+            cmd: "bash",
+            args: ["-lc", cmd],
+            detached: true,
+        });
+    }
+    async exposePort(port) {
+        return { url: this.sandbox.domain(port) };
+    }
+    async destroy() {
+        await this.sandbox.stop();
+    }
+}
+export class VercelSandboxProvider {
+    name = "vercel";
+    host;
+    sdk;
+    constructor(host) {
+        this.host = host;
+        this.sdk = lazyOnce(() => lazyImport(VERCEL_PACKAGE, VERCEL_INSTALL_HINT));
+    }
+    async create(opts) {
+        const credentials = this.credentials();
+        const { Sandbox } = await this.sdk();
+        const name = sandboxName();
+        const sandbox = await Sandbox.create({
+            ...credentials,
+            name,
+            timeout: opts.timeoutMs,
+            ports: opts.ports ?? [7681],
+            runtime: "node22",
+        });
+        return new VercelSandboxAdapter(name, sandbox, this.host);
+    }
+    async connect(id) {
+        const credentials = this.credentials();
+        const { Sandbox } = await this.sdk();
+        return new VercelSandboxAdapter(id, await Sandbox.get({ ...credentials, name: id, resume: true }), this.host);
+    }
+    async list() {
+        const credentials = this.credentials();
+        const { Sandbox } = await this.sdk();
+        const sandboxes = [];
+        for await (const sandbox of await Sandbox.list({
+            ...credentials,
+            limit: LIST_LIMIT,
+        }))
+            sandboxes.push({
+                id: sandbox.name,
+                startedAt: new Date(sandbox.createdAt),
+            });
+        return sandboxes;
+    }
+    async destroy(id) {
+        const credentials = this.credentials();
+        const { Sandbox } = await this.sdk();
+        return destroyOrFalse(isNotFoundError, async () => {
+            await (await Sandbox.get({ ...credentials, name: id })).stop();
+        });
+    }
+    credentials() {
+        return {
+            token: requireCred(this.host, "vercel", "VERCEL_TOKEN"),
+            teamId: requireCred(this.host, "vercel", "VERCEL_TEAM_ID"),
+            projectId: requireCred(this.host, "vercel", "VERCEL_PROJECT_ID"),
+        };
+    }
+}

package/dist/transports/cloudflared.js

@@ -0,0 +1,42 @@
+import { shellQuote } from "../core/shell.js";
+const LOG_PATH = "/tmp/sandhop-cloudflared.log";
+export class CloudflaredTransport {
+    id = "cloudflared";
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    ttydBindAddress() {
+        return "127.0.0.1";
+    }
+    bootstrapSteps() {
+        return [
+            "$SUDO curl -fsSL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-${CF_ARCH} -o /usr/local/bin/cloudflared",
+            "$SUDO chmod +x /usr/local/bin/cloudflared",
+        ];
+    }
+    async expose(ctx) {
+        if (this.opts.token !== undefined)
+            return this.exposeNamed(ctx, this.opts.token);
+        return this.exposeQuick(ctx);
+    }
+    async exposeNamed(ctx, token) {
+        if (this.opts.hostname === undefined)
+            throw new Error("CLOUDFLARE_TUNNEL_HOSTNAME is required for a named cloudflared tunnel");
+        await ctx.sandbox.spawn(`cloudflared tunnel --no-autoupdate --protocol http2 run --token ${shellQuote(token)} > ${LOG_PATH} 2>&1`);
+        const result = await ctx.sandbox.exec(`bash -lc 'for i in $(seq 1 120); do grep -q "Registered tunnel connection" ${LOG_PATH} && exit 0; sleep 0.5; done; echo "cloudflared did not connect" >&2; cat ${LOG_PATH} >&2; exit 1'`);
+        if (result.exitCode !== 0)
+            throw new Error(result.stderr);
+        return { url: `https://${this.opts.hostname}` };
+    }
+    async exposeQuick(ctx) {
+        await ctx.sandbox.spawn(`cloudflared tunnel --no-autoupdate --protocol http2 --url http://localhost:${ctx.localPort} > ${LOG_PATH} 2>&1`);
+        const result = await ctx.sandbox.exec(`bash -lc 'for i in $(seq 1 120); do u=$(grep -oE "https://[a-z0-9-]+\\.trycloudflare\\.com" ${LOG_PATH} | head -1); [ -n "$u" ] && grep -q "Registered tunnel connection" ${LOG_PATH} && { echo "$u"; exit 0; }; sleep 0.5; done; cat ${LOG_PATH} >&2; exit 1'`);
+        if (result.exitCode !== 0)
+            throw new Error(result.stderr);
+        const url = result.stdout.trim();
+        if (url.length === 0)
+            throw new Error("cloudflared did not return a URL");
+        return { url };
+    }
+}

package/dist/transports/public.js

@@ -0,0 +1,13 @@
+export class PublicTransport {
+    id = "public";
+    ttydBindAddress() {
+        return "0.0.0.0";
+    }
+    bootstrapSteps() {
+        return [];
+    }
+    async expose(ctx) {
+        const exposed = await ctx.sandbox.exposePort(ctx.localPort);
+        return { url: exposed.url };
+    }
+}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,201 @@
+# Sandhop Architecture
+
+**Style:** modular monolith with a **hexagonal core** (ports & adapters), a **domain-service layer** (one cohesive `Service` per concern), and **fan-out/fan-in** parallel collection. Single package, library + CLI. No real microservices, no DI framework, no config sprawl.
+
+## Principles
+
+1. **Byte-exact transfer.** No truncation, compaction, summarization, or rewriting of any session/data. Move bytes as-is.
+2. **Language-agnostic.** Sandhop never inspects the project's language/build. It tars the working tree verbatim and resumes the agent. Nothing in `core` assumes JS/Python/etc.
+3. **Ports in the core, vendor SDKs only at the edges.** `core/` imports no provider SDK and never touches the real filesystem — those live behind `host` and `providers` adapters.
+4. **Transport as a port.** ttyd exposure is selected through a small transport adapter: provider-native public HTTPS by default, cloudflared when `--tunnel cloudflared` is requested.
+5. **One composition root.** `cli/main.ts` is the only place that selects a concrete provider + agent and wires services.
+
+## Folder structure
+
+```
+src/
+  index.ts                       # public library entry (re-exports)
+  cli/
+    main.ts                      # composition root: parse args, pick provider+agent, wire services, run
+    args.ts                      # parseArgs (binary flags only)
+  core/
+    ports/
+      provider.ts                # SandboxProvider, Sandbox, Capability, ExposedPort
+      transport.ts               # Transport turns local ttyd into a user-facing URL
+      agent.ts                   # Agent (declarative), AgentHostDeps, SessionRef, AuthBundle
+      host.ts                    # HostDeps: fs/exec/keychain surface (edge port)
+    services/
+      snapshot.ts                # SnapshotService  — tar the working tree, byte-exact
+      session.ts                 # SessionService   — locate the session transcript for cwd+agent
+      profile.ts                 # ProfileService   — collect portable agent config (no caches)
+      secrets.ts                 # SecretsService   — capture env vars referenced by MCP configs
+      mcp-code.ts                # McpCodeService   — package local-path MCP server roots
+      auth.ts                    # AuthService      — model credential as env token
+      version.ts                 # VersionService   — detect local CLI version
+      bootstrap.ts               # BootstrapService — render the in-sandbox restore script
+      teleport.ts                # TeleportService  — orchestrator (fan-out collection, fan-in, drive provider)
+    manifest.ts  encode.ts       # pure value types/helpers
+    errors.ts                    # formatErrorText / formatErrorStack
+  providers/
+    index.ts                     # provider registry + PROVIDER_INFO (setup creds)
+    e2b/  modal/  daytona/  vercel/   # SandboxProvider impls (lazy-loaded SDKs)
+    lazy-import.ts  encode.ts    # lazyOnce SDK loader; uploadFile bytes converter
+  transports/
+    public.ts                    # provider-native port exposure
+    cloudflared.ts               # quick/named Cloudflare Tunnel exposure
+  agents/
+    claude-code.ts  codex.ts     # declarative Agent records
+    index.ts                     # AGENTS registry, detectAgents()
+  host/
+    node.ts                      # HostDeps impl: node:fs, node:child_process, macOS `security`
+test/
+  conformance/provider.spec.ts   # one spec run against every provider + an in-memory fake
+  ...unit specs per service
+```
+
+**Boundary rule:** `core/` may import only from `core/`. `providers/*`, `transports/*`, and `host/node.ts` are edge adapters. `providers/*` and `host/node.ts` are the only modules that import vendor SDKs or `node:fs`/`node:child_process`. `cli/main.ts` wires them.
+
+## Ports
+
+```ts
+// core/ports/provider.ts
+export type Capability =
+  | "background-exec"
+  | "live-file-upload"
+  | "extend-timeout"
+  | "provider-auth-url";
+export interface RunResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+export interface CreateOptions {
+  image: string;
+  envs: Record<string, string>;
+  timeoutMs: number;
+}
+export interface ExposedPort {
+  url: string;
+  token?: string;
+  authGatedByProvider: boolean;
+}
+export interface Sandbox {
+  readonly id: string;
+  uploadFile(path: string, data: Uint8Array | string): Promise<void>;
+  exec(cmd: string): Promise<RunResult>; // foreground, captured
+  spawn(cmd: string): Promise<void>; // long-lived/background (gated by "background-exec")
+  exposePort(port: number): Promise<ExposedPort>;
+  setTimeout(timeoutMs: number): Promise<void>;
+  destroy(): Promise<void>;
+}
+export interface SandboxInfo {
+  id: string;
+  startedAt: Date;
+}
+export interface SandboxProvider {
+  readonly name: string;
+  readonly capabilities: ReadonlySet<Capability>;
+  create(opts: CreateOptions): Promise<Sandbox>;
+  connect(id: string): Promise<Sandbox>;
+  list(): Promise<SandboxInfo[]>;
+  destroy(id: string): Promise<boolean>;
+}
+```
+
+```ts
+// core/ports/transport.ts
+export interface TransportContext {
+  sandbox: Sandbox;
+  localPort: number;
+  user: string;
+  pass: string;
+}
+export interface TransportResult {
+  url: string;
+}
+export interface Transport {
+  readonly id: "public" | "cloudflared";
+  ttydBindAddress(): string;
+  bootstrapSteps(): string[];
+  expose(ctx: TransportContext): Promise<TransportResult>;
+}
+```
+
+```ts
+// core/ports/host.ts  — the only fs/exec surface the services see (real impl in host/node.ts)
+export interface HostDeps {
+  env: Record<string, string | undefined>;
+  home: string;
+  readFile(path: string): string | null;
+  readBytes(path: string): Uint8Array;
+  exists(path: string): boolean;
+  walk(dir: string): string[];
+  statMtimeMs(path: string): number;
+  keychain(service: string): string | null;
+  exec(bin: string, args: string[]): string; // throws on failure
+  tarGz(cwd: string, entries: string[], outPath: string): Promise<void>;
+}
+```
+
+```ts
+// core/ports/agent.ts — agents are DATA; services hold the behavior
+export type AgentId = "claude-code" | "codex";
+export interface SessionRef {
+  sessionId: string;
+  transcriptPath: string;
+  transcriptName: string;
+}
+export interface AuthBundle {
+  envs: Record<string, string>;
+  files: { path: string; content: string }[];
+}
+export interface Agent {
+  readonly id: AgentId;
+  readonly pkg: string; // npm package
+  readonly bin: string; // CLI binary name (fixes version-detect hardcoding)
+  detectVersionArgs: string[]; // e.g. ["--version"]
+  parseVersion(output: string): string; // semver extraction
+  sessionsRoot(home: string): string; // where transcripts live
+  matchSession(home: string, cwd: string): SessionRef[]; // discovery (uses HostDeps via service)
+  profilePaths(home: string): string[]; // portable config files/dirs to ship (NO plugins/caches/sessions)
+  mcpConfigPaths(home: string, cwd: string): string[]; // files SecretsService scans for env refs
+  mcpEnvRefs(configText: string): string[]; // extract referenced env-var NAMES from a config file
+  authEnv(deps: AgentHostDeps): AuthBundle; // model credential as env (+ portable cred files)
+  installCmd(version: string): string;
+  preSeed(remoteProj: string): string[]; // fresh-machine trust/onboarding, keyed to sandbox cwd
+  remoteTranscriptPath(remoteEnc: string, transcriptName: string): string;
+  resumeCmd(sessionId: string, remoteProj: string): string;
+}
+export type AgentHostDeps = Pick<
+  HostDeps,
+  "env" | "home" | "readFile" | "keychain" | "exec"
+>;
+```
+
+## Services (the "service structs")
+
+Each is a small struct constructed with its deps; methods are reusable. Pure where possible.
+
+- **SnapshotService(host)** — `build(cwd, outPath)`: full byte-exact tar of `cwd` (`["."]`, no excludes, no size cap). Language-agnostic.
+- **SessionService(host, agent)** — `latest(cwd)` / `byId(cwd, id)`: discover the transcript via the agent's `matchSession`.
+- **ProfileService(host, agent)** — `build(outPath)`: tar the agent's `profilePaths` (settings, CLAUDE.md/AGENTS.md, commands/prompts, plugins, rules/skills/agents/output-styles, MCP defs). Excludes caches and all sessions except the target. Returns null if nothing.
+- **McpCodeService(host, agent)** — `plan(cwd)` / `build(cwd, outPath)`: classify MCP servers, package local-path project roots, remap host-home paths to sandbox-home paths, capture sourced files, and produce install commands for sandbox dependency reinstalls.
+- **SecretsService(host, agent)** — `collect(cwd, inputs?)`: scan `mcpConfigPaths`, extract referenced env-var names via `agent.mcpEnvRefs`, add MCP-code env refs and sourced files, and capture their values from `host.env`. Returns `{ envs, files }`. **This replaces the `~/.env.d` assumption** — general, captures only what the user's MCP configs reference.
+- **AuthService(host, agent)** — `extract()`: model credential → env (token/api key) + any portable cred files (e.g. Codex `auth.json` when file-store). Fails loudly if none.
+- **VersionService(host, agent)** — `detect()`: run `agent.bin agent.detectVersionArgs`, `agent.parseVersion`. Fails loudly.
+- **BootstrapService(agent)** — `render(manifest, opts)`: the in-sandbox script (install pinned version, ttyd install, optional transport bootstrap steps, profile extract, preSeed, bundle extract, place transcript; NO data mutation). Sources captured secret env into the agent's runtime.
+- **TeleportService(provider, agent, services)** — `run(cwd, opts)`: **fan-out** (Promise.all) the collection services (snapshot, session, profile, secrets, auth, version) → **fan-in** assemble manifest + uploads → create sandbox → upload (bundle, profile) → exec bootstrap (assert restore marker) → spawn ttyd (basic auth) on the transport-selected bind address → `transport.expose` → return `{ url, user, pass, sandboxId }`.
+
+## Security model (default)
+
+- Auth + captured MCP secrets travel as e2b `envs` / `uploadFile` over **TLS**; never in the project tar, never logged.
+- Access: **HTTPS + ttyd basic auth** (random per-session password) by default. `--tunnel cloudflared` binds ttyd to loopback and returns either a quick tunnel URL protected by ttyd Basic Auth or a named Cloudflare Access hostname.
+- Sandbox is single-tenant + ephemeral (auto-killed at timeout).
+- Secrets shipped are only those the user's MCP configs reference (SecretsService) — nothing broad like a whole secret directory.
+
+## Out of scope / documented limits
+
+- Plugins/skills under `~/.claude/plugins` are shipped with file-backed uploads.
+- Local-path MCP server roots are shipped when they can be classified from MCP config; dependency directories are reinstalled rather than copied.
+- Codex resume requires the same org/credential that created the rollout (encrypted reasoning is org-bound); ship `auth.json` (file-store) for the same account.
+- Providers: e2b, Modal, Daytona, and Vercel Sandbox ship today behind one `SandboxProvider` port + registry, selected by `--provider`. Adapters lazy-load their SDK (optional deps) and are stateless. Providers with no browser-friendly native expose (Daytona's token-gated preview) use the `cloudflared` transport.

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "sandhop",
+  "version": "0.1.0",
+  "description": "Teleport live local Claude Code and Codex sessions to auth-gated cloud sandbox terminals.",
+  "type": "module",
+  "bin": {
+    "sandhop": "dist/cli/main.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TalkingComputers/sandhop.git"
+  },
+  "license": "MIT",
+  "author": "Talking Computers",
+  "keywords": [
+    "claude-code",
+    "codex",
+    "e2b",
+    "sandbox",
+    "terminal",
+    "agent",
+    "teleport",
+    "ttyd"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "plugin",
+    "docs/ARCHITECTURE.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "dev": "tsx src/cli/main.ts"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.5.1",
+    "e2b": "^2.27.0",
+    "p-limit": "^7.3.0",
+    "smol-toml": "^1.6.1",
+    "tar": "^7.5.16"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.0"
+  },
+  "optionalDependencies": {
+    "@daytonaio/sdk": "^0.184.0",
+    "@vercel/sandbox": "^2.1.0",
+    "modal": "^0.7.6"
+  }
+}

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "sandhop",
+  "version": "0.1.0",
+  "description": "Teleport your live local Claude Code / Codex session to a cloud sandbox and continue in the browser.",
+  "commands": ["./commands/sandhop.md"]
+}

package/plugin/commands/sandhop.md

@@ -0,0 +1,13 @@
+---
+description: Teleport this session to a cloud sandbox and return a browser URL
+---
+
+Run the Sandhop engine to teleport THIS session to the cloud, then give the user the URL and auth.
+
+Steps:
+
+1. Run: `sandhop push --cwd "$(pwd)"`
+2. The command prints `SANDHOP_URL <url>` and `SANDHOP_AUTH sandhop:<pass>` immediately, then starts background enrichment for profile, skills, and MCP servers. Extract both.
+3. Reply immediately with exactly: "Your session is live: <url> — log in with user `sandhop`, password `<pass>`. Profile/skills/MCP are still enriching in the background; check `/tmp/sandhop-enrich.log` in the session if asked." — nothing else.
+
+If the command exits non-zero, show the user its stderr verbatim and stop.

package/plugin/prompts/sandhop.md

@@ -0,0 +1,7 @@
+Teleport the current Codex session to a cloud sandbox.
+
+Run this shell command from the current working directory:
+
+sandhop push --agent codex --cwd "$(pwd)"
+
+It prints `SANDHOP_URL <url>` and `SANDHOP_AUTH sandhop:<pass>` immediately, then starts background enrichment for profile, skills, and MCP servers. Report both immediately as: "Your session is live: <url> — log in with user `sandhop`, password `<pass>`. Profile/skills/MCP are still enriching in the background; check `/tmp/sandhop-enrich.log` in the session if asked." If it fails, show the stderr.