Run logs

Pass logging to run(). Here Sandcastle writes a run log and forwards each agent stream event to your own code:

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

const result = await run({
  agent: claudeCode("claude-opus-4-8"),
  sandbox: docker(),
  promptFile: ".sandcastle/prompt.md",
  logging: {
    type: "file",
    path: ".sandcastle/logs/my-run.log",
    onAgentStreamEvent: (event) => {
      console.log(event.iteration, event.type);
    },
  },
});

console.log(result.logFilePath); // ".sandcastle/logs/my-run.log"

The logging option

• { type: "file", path } is log-to-file mode, and the default: without logging, Sandcastle writes a run log under .sandcastle/logs/. result.logFilePath is its path.
• { type: "stdout" } is terminal mode.
• onAgentStreamEvent is only available in log-to-file mode. It fires for each text chunk, tool call, and raw stdout line the agent produces. Errors thrown by the callback are swallowed so a broken forwarder cannot kill the run.
• verbose: true adds every raw stdout line the agent emits: to the log file in log-to-file mode, interleaved with the human-readable output, and to stdout in terminal mode. Intended for debugging stuck or unexpected agent behaviour.
• name sets a display name for the run, shown as a prefix in log output.

Related terms

• Iterations: each agent stream event carries its iteration number
• Init: the config directory, whose .gitignore ignores logs/
• run() reference: the logging option in full