Sandcastle

SUPERSERVE_API_KEY=ss_live_...
ANTHROPIC_API_KEY=sk-ant-...

node_modules
.env
.sandcastle/logs
.sandcastle/worktrees

import { execFile } from "node:child_process"
import { randomUUID } from "node:crypto"
import { mkdir, readFile, stat, writeFile } from "node:fs/promises"
import { dirname } from "node:path"
import { promisify } from "node:util"

import {
  createIsolatedSandboxProvider,
  type ExecResult,
  type IsolatedSandboxHandle,
  type IsolatedSandboxProvider,
} from "@ai-hero/sandcastle"
import { Sandbox, type SandboxCreateOptions } from "@superserve/sdk"

export interface SuperserveOptions extends Partial<
  Omit<SandboxCreateOptions, "envVars">
> {
  /** Environment variables to set in every sandbox. */
  env?: Record<string, string>
  /** Timeout for each command, including the agent run. Defaults to 1 hour. */
  commandTimeoutMs?: number
}

const WORKTREE = "/home/user/workspace"

// Quote a value for /bin/sh.
const quote = (value: string) => `'${value.replaceAll("'", `'\\''`)}'`

const execFileAsync = promisify(execFile)

/** A Sandcastle sandbox provider that runs each agent in a Superserve sandbox. */
export const superserve = (
  options: SuperserveOptions = {},
): IsolatedSandboxProvider => {
  const { env, commandTimeoutMs = 60 * 60_000, ...createOptions } = options
  // Send heartbeat updates with the same API key and URL as Sandbox.create.
  const connection = { apiKey: options.apiKey, baseUrl: options.baseUrl }

  return createIsolatedSandboxProvider({
    name: "superserve",
    // Commands run as root. Claude Code accepts --dangerously-skip-permissions
    // as root only when IS_SANDBOX is set.
    env: { IS_SANDBOX: "1", ...env },

    async create({ env: sandboxEnv }): Promise<IsolatedSandboxHandle> {
      // The run owns its sandbox while it updates the heartbeat tag (Unix
      // time in ms). cleanup.ts deletes only sandboxes with a stale heartbeat.
      const metadata = { sandcastle: "true", ...createOptions.metadata }
      const lease = () => ({
        ...metadata,
        "sandcastle-heartbeat": String(Date.now()),
      })

      const sandbox = await Sandbox.create({
        name: `sandcastle-${randomUUID().slice(0, 8)}`,
        // Pause the sandbox after 10 minutes with no command, to stop billing
        // for it. The next command resumes it.
        idleTimeoutSeconds: 10 * 60,
        ...createOptions,
        metadata: lease(),
        envVars: sandboxEnv,
      })

      // Update the heartbeat every minute until close(), also while the
      // sandbox is paused. updateById does not resume a paused sandbox.
      const heartbeat = setInterval(() => {
        Sandbox.updateById(sandbox.id, { metadata: lease() }, connection).catch(
          () => {},
        )
      }, 60_000)
      heartbeat.unref()

      // Run a setup command and throw its stderr when it fails.
      const sh = async (command: string) => {
        const { stderr, exitCode } = await sandbox.commands.run(command, {
          timeoutMs: commandTimeoutMs,
        })
        if (exitCode !== 0) throw new Error(stderr.trim() || command)
      }

      try {
        await sh(`mkdir -p ${WORKTREE}`)
      } catch (error) {
        clearInterval(heartbeat)
        await sandbox.kill()
        throw error
      }

      return {
        worktreePath: WORKTREE,
        sandboxId: sandbox.id,

        async exec(command, opts = {}): Promise<ExecResult> {
          let script = command
          if (opts.stdin !== undefined) {
            // Write stdin to a file and redirect it into the command.
            const path = `/tmp/sandcastle-stdin-${randomUUID()}`
            await sandbox.files.write(path, opts.stdin)
            script = `{ rm -f ${path}; ${command}\n} < ${path}`
          }

          // Stream every command. A streamed command stays connected while
          // the agent works, and Sandcastle reads the agent's output by line.
          let partial = ""
          const { stdout, stderr, exitCode } = await sandbox.commands.run(
            script,
            {
              cwd: opts.cwd ?? WORKTREE,
              user: opts.sudo ? "root" : undefined,
              timeoutMs: commandTimeoutMs,
              onStdout: (data) => {
                const lines = (partial + data).split("\n")
                partial = lines.pop() ?? ""
                for (const line of lines) opts.onLine?.(line)
              },
              onStderr: () => {},
            },
          )
          if (partial) opts.onLine?.(partial)
          return { stdout, stderr, exitCode }
        },

        async copyIn(hostPath, sandboxPath) {
          if (!(await stat(hostPath)).isDirectory()) {
            await sandbox.files.write(sandboxPath, await readFile(hostPath))
            return
          }
          // Send a directory as a tar archive and unpack it in the sandbox.
          const { stdout: archive } = await execFileAsync(
            "tar",
            ["-czf", "-", "-C", hostPath, "."],
            { encoding: "buffer", maxBuffer: 1024 ** 3 },
          )
          const path = `/tmp/sandcastle-${randomUUID()}.tar.gz`
          await sandbox.files.write(path, archive)
          await sh(
            `mkdir -p ${quote(sandboxPath)} && tar -xzf ${path} -C ${quote(sandboxPath)} && rm -f ${path}`,
          )
        },

        async copyFileOut(sandboxPath, hostPath) {
          await mkdir(dirname(hostPath), { recursive: true })
          await writeFile(hostPath, await sandbox.files.read(sandboxPath))
        },

        async close() {
          clearInterval(heartbeat)
          await sandbox.kill()
        },
      }
    },
  })
}

import { claudeCode, run } from "@ai-hero/sandcastle"

import { superserve } from "./superserve.ts"

const result = await run({
  agent: claudeCode("claude-sonnet-4-6"),
  sandbox: superserve({
    fromTemplate: "superserve/claude-code",
    secrets: { ANTHROPIC_API_KEY: "anthropic-key" },
  }),
  prompt:
    "Add fizzbuzz.py that prints FizzBuzz for 1 to 15. Run it with python3, then commit it.",
})

console.log(`Branch: ${result.branch}`)
for (const { sha } of result.commits) console.log(`Commit: ${sha}`)

import { codex, run } from "@ai-hero/sandcastle"

import { superserve } from "./superserve.ts"

const result = await run({
  agent: codex("gpt-5.5"),
  sandbox: superserve({
    fromTemplate: "superserve/node-22",
    // Codex reads its API key from CODEX_API_KEY in exec mode.
    secrets: { CODEX_API_KEY: "openai-key" },
  }),
  hooks: {
    sandbox: {
      onSandboxReady: [
        { command: "npm install -g @openai/codex", timeoutMs: 300_000 },
      ],
    },
  },
  prompt:
    "Add fizzbuzz.js, a Node.js version of fizzbuzz.py. Run it with node, then commit it.",
})

console.log(`Branch: ${result.branch}`)
for (const { sha } of result.commits) console.log(`Commit: ${sha}`)