run(command: string): Promise<string>

execute(request: ExecutionRequest, context: SecurityContext): Promise<ExecutionResult>

export type SandboxTier =
  | "none"
  | "parseOnly"
  | "processLimited"
  | "tempWorkspace"
  | "container"
  | "vm"
  | "remoteIsolated";

export type ExecutionPolicy = {
  enabled: boolean;
  tier: SandboxTier;
  trustMode: "trusted" | "restricted" | "untrusted";
  commands: CommandPolicy;
  filesystem: FilesystemPolicy;
  environment: EnvironmentPolicy;
  network: ExecutionNetworkPolicy;
  resources: ResourceLimitPolicy;
  logging: ExecutionLoggingPolicy;
  audit: ExecutionAuditPolicy;
};

export type CommandPolicy = {
  allow: AllowedCommand[];
  denyPatterns: string[];
  allowShell: boolean;
};

export type AllowedCommand = {
  command: string;
  allowedSubcommands?: string[];
  allowedArgs?: ArgPolicy[];
  trustModes: Array<"trusted" | "restricted" | "untrusted">;
  requiresFixture?: boolean;
};

export type FilesystemPolicy = {
  workspaceMode: "tempEmpty" | "tempCopy" | "repoReadOnly" | "repoWritable";
  allowedReadGlobs: string[];
  allowedWriteGlobs: string[];
  deniedGlobs: string[];
  followSymlinks: boolean;
  maxWrittenBytes: number;
};

export type ExecutionNetworkPolicy = {
  allowNetwork: boolean;
  allowLoopback: boolean;
  allowMockServer: boolean;
  allowedHosts: string[];
  blockPrivateNetworks: boolean;
};

export type ResourceLimitPolicy = {
  timeoutMs: number;
  maxOutputBytes: number;
  maxFileBytes?: number;
  maxMemoryMb?: number;
  maxProcessCount?: number;
};

export type ExecutionRequest = {
  id: string;
  purpose:
    | "exampleVerification"
    | "codeSampleVerification"
    | "formatting"
    | "gitRead"
    | "pluginHook"
    | "mockServer"
    | "diagnostic";
  command: string;
  args: string[];
  cwd?: string;
  input?: string;
  env?: Record<string, string>;
  trust: "trusted" | "restricted" | "untrusted";
  expected?: ExpectedExecutionResult;
  source?: {
    pageId?: PageId;
    blockId?: string;
    sourceRefs?: SourceRef[];
  };
};

export type ExecutionResult = {
  id: string;
  requestId: string;
  status: "passed" | "failed" | "blocked" | "timeout" | "error";
  exitCode?: number;
  signal?: string;
  durationMs: number;
  stdoutPreview: string;
  stderrPreview: string;
  diagnostics: Diagnostic[];
  artifacts: ExecutionArtifact[];
  audit: ExecutionAuditRecord;
};

export type ExecutionAuditRecord = {
  executionId: string;
  purpose: ExecutionRequest["purpose"];
  command: string;
  argsHash: string;
  trustMode: "trusted" | "restricted" | "untrusted";
  tier: SandboxTier;
  policyHash: string;
  startedAt: string;
  endedAt: string;
  status: ExecutionResult["status"];
};

exec(`docforge build ${userProvidedFlags}`)

spawn("docforge", ["build", "--strict"], { shell: false })

|
&&
;
`...`
$(...)
> file
< file
2>&1

{
  "allow": [
    { "command": "docforge", "trustModes": ["trusted", "restricted"] },
    { "command": "node", "trustModes": ["trusted"] },
    { "command": "python", "trustModes": ["trusted"] },
    { "command": "javac", "trustModes": ["trusted"] },
    { "command": "go", "trustModes": ["trusted"] },
    {
      "command": "git",
      "allowedSubcommands": ["diff", "status", "rev-parse", "show", "ls-files"],
      "trustModes": ["trusted", "restricted", "untrusted"]
    }
  ]
}

sudo
rm
chmod
chown
curl|sh
wget|sh
ssh
scp
kubectl delete
terraform destroy
docker
npm install
pnpm install
pip install

export type ArgPolicy =
  | { type: "literal"; value: string }
  | { type: "oneOf"; values: string[] }
  | { type: "pattern"; regex: string }
  | { type: "pathWithin"; root: "workspace" | "project" };

const gitPolicy: AllowedCommand = {
  command: "git",
  allowedSubcommands: ["diff", "status", "rev-parse", "show", "ls-files"],
  trustModes: ["trusted", "restricted", "untrusted"],
};

git push
git commit
git config
git credential
git checkout
git clean

export async function prepareTempWorkspace(input: {
  projectRoot: string;
  policy: FilesystemPolicy;
  fixturePath?: string;
}): Promise<SandboxWorkspace> {
  const root = await createTempDirectory("docforge-exec-");
  const home = path.join(root, ".home");
  await fs.mkdir(home, { recursive: true });

  if (input.fixturePath) {
    await copyDirectory(input.fixturePath, root, {
      deniedGlobs: input.policy.deniedGlobs,
      followSymlinks: input.policy.followSymlinks,
    });
  }

  return { root, home, cleanup: true };
}

export function assertInsideRoot(root: string, target: string): void {
  const realRoot = fs.realpathSync(root);
  const realTarget = fs.realpathSync(target);

  if (!realTarget.startsWith(realRoot + path.sep) && realTarget !== realRoot) {
    throw new SecurityError(`Path escapes root: ${target}`);
  }
}

../../.ssh/id_rsa
/tmp/outside
/absolute/path

followSymlinks=false

warning execution.filesystem.symlinkSkipped
Skipped symlink because sandbox policy does not follow symlinks.

error execution.filesystem.symlinkOutsideRoot
Symlink target escapes sandbox root.

export function minimalEnv(workspace: SandboxWorkspace): Record<string, string> {
  return {
    PATH: safeExecutionPath(),
    HOME: workspace.home,
    TMPDIR: path.join(workspace.root, ".tmp"),
    CI: "1",
    DOCFORGE_EXAMPLE_MODE: "1",
  };
}

GITHUB_TOKEN
NPM_TOKEN
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
GOOGLE_APPLICATION_CREDENTIALS
AZURE_CLIENT_SECRET
KUBECONFIG
SSH_AUTH_SOCK
OPENAI_API_KEY
ANTHROPIC_API_KEY

export function sanitizeExecutionOutput(raw: string): SanitizedOutput {
  const findings = scanSecretLikeText(raw);
  const redacted = redactSecretFindings(raw, findings);

  return {
    text: truncate(redacted, 16 * 1024),
    diagnostics: findings.map((finding) => ({
      code: "execution.secret.output",
      severity: "error",
      category: "security",
      message: "Execution output contained a secret-like value and was redacted.",
    })),
  };
}

docker run --rm \
  --network none \
  --memory 512m \
  --cpus 1 \
  --read-only \
  --user 1000:1000 \
  -v /tmp/docforge-workspace:/workspace:rw \
  -w /workspace \
  docforge-runner:node20 \
  node example.js

export type ContainerSandboxPolicy = {
  image: string;
  network: "none" | "restricted" | "bridge";
  readOnlyRootFilesystem: boolean;
  memoryMb: number;
  cpus: number;
  user: string;
  mounts: Array<{
    source: string;
    target: string;
    mode: "ro" | "rw";
  }>;
  timeoutMs: number;
};

{
  "network": "none",
  "readOnlyRootFilesystem": true,
  "memoryMb": 512,
  "cpus": 1,
  "user": "1000:1000"
}

export async function runProcess(plan: ExecutionPlan): Promise<ExecutionResult> {
  const started = Date.now();
  const stdout = new BoundedBuffer(plan.maxOutputBytes);
  const stderr = new BoundedBuffer(plan.maxOutputBytes);

  const child = spawn(plan.command, plan.args, {
    cwd: plan.cwd,
    env: plan.env,
    shell: false,
    stdio: ["pipe", "pipe", "pipe"],
  });

  child.stdout.on("data", (chunk) => stdout.append(chunk));
  child.stderr.on("data", (chunk) => stderr.append(chunk));

  const timeout = setTimeout(() => {
    killProcessTree(child.pid);
  }, plan.timeoutMs);

  const exit = await waitForExit(child).finally(() => clearTimeout(timeout));

  const safeStdout = sanitizeExecutionOutput(stdout.toString());
  const safeStderr = sanitizeExecutionOutput(stderr.toString());

  return {
    id: plan.id,
    requestId: plan.requestId,
    status: exit.timedOut ? "timeout" : exit.code === 0 ? "passed" : "failed",
    exitCode: exit.code,
    signal: exit.signal,
    durationMs: Date.now() - started,
    stdoutPreview: safeStdout.text,
    stderrPreview: safeStderr.text,
    diagnostics: [...safeStdout.diagnostics, ...safeStderr.diagnostics],
    artifacts: [],
    audit: buildAuditRecord(plan, exit),
  };
}

{
  "resources": {
    "timeoutMs": 10000,
    "maxOutputBytes": 16384
  }
}

error execution.timeout
Command timed out after 10000ms and was terminated.

docforge dev --once

export async function verifyCliExample(
  example: ExtractedCodeExample,
  ctx: VerificationContext
): Promise<ExampleVerificationResult> {
  const request = createExecutionRequestFromExample(example);
  const result = await ctx.executionManager.execute(request, ctx.securityContext);

  return mapExecutionToExampleResult(example, result);
}

export type MockServerPolicy = {
  host: "127.0.0.1";
  maxRequests: number;
  maxRequestBodyBytes: number;
  maxResponseBodyBytes: number;
  timeoutMs: number;
};

export type ApiProxyPolicy = {
  enabled: boolean;
  allowedHosts: string[];
  blockPrivateNetworks: boolean;
  maxRequestBytes: number;
  maxResponseBytes: number;
  timeoutMs: number;
  redactHeaders: string[];
};

localhost
127.0.0.0/8
10.0.0.0/8
172.16.0.0/12
192.168.0.0/16
169.254.0.0/16
metadata service IPs

export type PluginManifest = {
  id: string;
  version: string;
  permissions: Array<
    | "readProject"
    | "writeDocs"
    | "network"
    | "executeCommands"
    | "readKnowledgeStore"
  >;
};

export type PluginContext = {
  readArtifact(id: ArtifactId): Promise<SourceArtifact>;
  writeGeneratedPage(page: PageIr): Promise<void>;
  execute(request: PluginExecutionRequest): Promise<ExecutionResult>;
};

git diff
git status --porcelain
git rev-parse
git show
git ls-files

git push
git commit
git checkout
git clean
git config
git credential

export function resolveExecutionPolicy(input: {
  config: NormalizedConfig;
  securityContext: SecurityContext;
  cliOverrides: CliOverrides;
}): ExecutionPolicy {
  const defaults = defaultExecutionPolicy();
  const configured = merge(defaults, input.config.execution);
  const overridden = applyCliOverrides(configured, input.cliOverrides);
  return applySecurityModeRestrictions(overridden, input.securityContext);
}

ciUntrustedPr:
- execution tier forced to parseOnly
- plugins disabled
- network disabled
- package manager commands denied

Blocked example execution

Example: /quickstart#install
Command: curl
Reason: network commands are disabled by execution policy.

To keep this example, mark it verify="none" with a reason, or verify it with an OpenAPI mock sample.

export type SafeExecutionReport = {
  schemaVersion: "safe-execution-report/v1";
  policyHash: string;
  executions: ExecutionResult[];
  summary: {
    total: number;
    passed: number;
    failed: number;
    blocked: number;
    timeout: number;
  };
};

docforge examples verify --report .docforge/reports/examples.json
docforge execution report

fixtures/sandbox/
  safe-docforge-command/
  blocked-rm-rf/
  blocked-curl-pipe-shell/
  blocked-env-secret/
  timeout-command/
  output-too-large/
  symlink-outside-root/
  unexpected-write/
  network-denied/

it("blocks rm -rf", async () => {
  const result = await runSandboxFixture("blocked-rm-rf");

  expect(result.status).toBe("blocked");
  expect(result.diagnostics).toContainEqual(
    expect.objectContaining({ code: "execution.command.notAllowed" })
  );
});

it("redacts secret-like output", async () => {
  const result = await runSandboxFixture("prints-secret");

  expect(result.stdoutPreview).not.toContain("sk_live_");
  expect(result.diagnostics).toContainEqual(
    expect.objectContaining({ code: "execution.secret.output" })
  );
});

it("does not follow symlink outside workspace", async () => {
  const result = await runSandboxFixture("symlink-outside-root");

  expect(result.diagnostics).toContainEqual(
    expect.objectContaining({ code: "execution.filesystem.symlinkOutsideRoot" })
  );
});

export type PlatformProcessManager = {
  spawn(plan: ExecutionPlan): ChildProcessHandle;
  killTree(pid: number): Promise<void>;
  commandExists(command: string): Promise<boolean>;
};

LLM writes shell command -> tool executes it.

LLM may produce structured draft -> deterministic verifier decides whether code block is runnable -> execution policy authorizes.