Skip to content

Examples

These examples are published as part of the public Sandbox Loom documentation so consumers can inspect the exact source before running anything. The source is included from the repository’s examples/ directory at build time; no private-repository links are required.

Run the offline verification matrix from the repository root:

Verify all offline examples
bin/sandbox-loom examples check

The OpenAI example is live-provider-only and is skipped unless SANDBOX_LOOM_RUN_LIVE_EXAMPLES=1 is explicitly set. Never publish or commit API keys.

The examples progress from offline local capabilities to workflow composition, repair and acceptance, protected operations, and explicitly opt-in provider access. Use them as executable design references: each example shows a different authority, verification, or evidence boundary rather than merely a different syntax for running a command.

1. Hello workspace — Ruby gateway API

examples/01_hello_workspace.rb
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
# frozen_string_literal: true

require "fileutils"
require "tmpdir"
require "gateway"

ROOT = File.expand_path("..", __dir__)
registry = PolicyEngine::Registry.load(File.join(ROOT, "specifications/sandbox/v0.2/capability-registry-v0.2.yaml"))
policy = PolicyEngine::Policy.load(File.join(ROOT, "specifications/sandbox/v0.2/autonomous-development.yaml"))
audit = PolicyEngine::MemoryAuditLog.new
evaluator = PolicyEngine::Evaluator.new(registry: registry, policy: policy, audit_log: audit)

Dir.mktmpdir("sandbox-loom-example") do |root|
  workspace = File.join(root, "workspace")
  gateway = Gateway::Filesystem.new(workspace_root: workspace, evaluator: evaluator, sandbox_id: "example-1", profile: policy.profile)
  gateway.write("/workspace/message.txt", "hello from the gateway")
  puts gateway.read("/workspace/message.txt")
  puts "audit_events=#{audit.events.length}"
end

2. Verify a file — YAML workflow

examples/02_verify_file.yml
1
2
3
4
5
6
7
8
# yaml-language-server: $schema=../specifications/workflows/v0.1/workflow.schema.json
version: "0.1"
workflow: verify-file
profile: autonomous-development
tasks:
  - id: verify
    action: verify
    checks: [file_exists, content_present]

3. Dependencies — Ruby DSL

examples/03_dependencies.rb
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# frozen_string_literal: true

require "json"
require "workflow"

document = Workflow::DSL.define("dependency-composition", profile: "autonomous-development") do
  task :inspect, action: "gateway.git.status"
  task :implement, action: "executor.request"
  task :verify, action: "verify", checks: %i[test build lint]
  after :inspect, :implement
  after :implement, :verify
end

plan = Workflow::Planner.new(validator: Workflow::Validator.new).plan(document)
puts JSON.pretty_generate(plan)

4. Quality loop — repair and acceptance

examples/04_quality_loop.rb
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
# frozen_string_literal: true

require "development_loop"

attempts = 0
runner = DevelopmentLoop::Runner.new(
  planner: ->(context) { { steps: [context[:specification][:objective]] } },
  implementer: ->(_context) { { changed_files: ["/workspace/service.rb"] } },
  verifier: lambda do |_context|
    attempts += 1
    { success: attempts > 1, checks: [{ name: :test, status: attempts > 1 ? "passed" : "failed" }] }
  end,
  repairer: ->(context) { { repair: "retry verification", previous_attempt: context[:failure][:repair_count] } },
  checkpoint_store: DevelopmentLoop::MemoryCheckpointStore.new
)

result = runner.run(
  { id: "quality-loop", objective: "verify a service change", acceptance_criteria: ["tests pass"] },
  run_id: "quality-loop-run"
)
puts "status=#{result[:status]} repair_count=#{result[:evidence][:repair_count]}"

5. Snapshot and restore — Ruby gateway API

examples/05_snapshot_restore.rb
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# frozen_string_literal: true

require "fileutils"
require "tmpdir"
require "gateway"

ROOT = File.expand_path("..", __dir__)
registry = PolicyEngine::Registry.load(File.join(ROOT, "specifications/sandbox/v0.2/capability-registry-v0.2.yaml"))
policy = PolicyEngine::Policy.load(File.join(ROOT, "specifications/sandbox/v0.2/autonomous-development.yaml"))
audit = PolicyEngine::MemoryAuditLog.new
evaluator = PolicyEngine::Evaluator.new(registry: registry, policy: policy, audit_log: audit)

Dir.mktmpdir("sandbox-loom-snapshot") do |root|
  workspace = File.join(root, "workspace")
  snapshots = File.join(root, "snapshots")
  options = { evaluator: evaluator, sandbox_id: "example-5", profile: policy.profile }
  filesystem = Gateway::Filesystem.new(workspace_root: workspace, **options)
  snapshots_api = Gateway::Snapshots.new(workspace_root: workspace, snapshot_root: snapshots, **options)
  filesystem.write("/workspace/state.txt", "before")
  snapshot_id = snapshots_api.create
  filesystem.write("/workspace/state.txt", "after")
  snapshots_api.restore(snapshot_id)
  puts "restored=#{filesystem.read('/workspace/state.txt')}"
end

6. Feature-branch push — brokered YAML plan

examples/06_feature_branch_push.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# yaml-language-server: $schema=../specifications/workflows/v0.1/workflow.schema.json
version: "0.1"
workflow: feature-branch-push
profile: autonomous-development
tasks:
  - id: push
    action: broker.git.push_feature
    with:
      branch: agent/example
      remote: origin

7. Protected operation — approval boundary

examples/07_protected_operation.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# yaml-language-server: $schema=../specifications/workflows/v0.1/workflow.schema.json
version: "0.1"
workflow: protected-operation
profile: autonomous-development
tasks:
  - id: approval
    action: approval.request
    approval: true
    with:
      operation: protected-branch-push

8. Invalid workflow — fail-closed validation

examples/08_invalid_workflow.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# yaml-language-server: $schema=../specifications/workflows/v0.1/workflow.schema.json
version: "0.1"
workflow: invalid-cycle
profile: autonomous-development
tasks:
  - id: first
    action: verify
    after: [second]
  - id: second
    action: verify
    after: [first]

9. Autonomous feature — realistic YAML workflow

examples/09_autonomous_feature.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# yaml-language-server: $schema=../specifications/workflows/v0.1/workflow.schema.json
version: "0.1"
workflow: autonomous-feature
profile: autonomous-development
limits:
  max_tasks: 10
  max_retries: 2
tasks:
  - id: inspect
    action: gateway.git.status
  - id: implement
    action: executor.request
    after: [inspect]
    with:
      operation: implement-feature
  - id: verify
    action: verify
    after: [implement]
    checks: [test, build, lint]
    retry: 1
  - id: checkpoint
    action: checkpoint
    after: [verify]
  - id: review
    action: approval.request
    after: [checkpoint]

10. Deterministic coding agent

Workflow:

examples/10_coding_agent_feature/workflow.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
# yaml-language-server: $schema=../../specifications/workflows/v0.1/workflow.schema.json
version: "0.1"
workflow: coding-agent-feature
profile: autonomous-development
tasks:
  - id: inspect
    action: executor.request
    with:
      operation: inspect_repository
  - id: implement
    action: executor.request
    after: [inspect]
    with:
      operation: implement_feature
  - id: verify_initial
    action: verify
    after: [implement]
    checks: [greeting_content]
  - id: repair
    action: executor.request
    after: [verify_initial]
    with:
      operation: repair
  - id: verify_final
    action: verify
    after: [repair]
    checks: [greeting_content]
  - id: checkpoint
    action: checkpoint
    after: [verify_final]

Runner:

examples/10_coding_agent_feature/run.rb
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
# frozen_string_literal: true

require "json"
require "tmpdir"
require "coding_agent"
require "development_loop"
require "gateway"
require "workflow"

ROOT = File.expand_path("../..", __dir__)
registry = PolicyEngine::Registry.load(File.join(ROOT, "specifications/sandbox/v0.2/capability-registry-v0.2.yaml"))
policy = PolicyEngine::Policy.load(File.join(ROOT, "specifications/sandbox/v0.2/autonomous-development.yaml"))
audit = PolicyEngine::MemoryAuditLog.new
evaluator = PolicyEngine::Evaluator.new(registry: registry, policy: policy, audit_log: audit)
workflow = Workflow::Loader.load(File.join(__dir__, "workflow.yml"))

Dir.mktmpdir("sandbox-loom-coding-agent") do |root|
  gateway = Gateway::Filesystem.new(workspace_root: File.join(root, "workspace"), evaluator: evaluator, sandbox_id: "coding-agent-sandbox", profile: policy.profile)
  agent = CodingAgent::Deterministic.new(gateway: gateway)
  checkpoints = DevelopmentLoop::MemoryCheckpointStore.new
  verification_attempts = 0
  handlers = {
    "executor.request" => lambda do |task:, context:|
      agent.request(operation: task.fetch("with").fetch("operation"), context: context)
    end,
    "verify" => lambda do |task:, context:|
      verification_attempts += 1
      content = gateway.read("/workspace/greeting.txt") rescue ""
      { task: task.fetch("id"), checks: task.fetch("checks"), success: content == "hello from the coding agent\n", attempt: verification_attempts }
    end,
    "checkpoint" => ->(task:, context:) { { task: task.fetch("id"), run_id: context.fetch(:run_id) } }
  }

  result = Workflow::Executor.new(
    planner: Workflow::Planner.new(validator: Workflow::Validator.new(registry: registry, policy: policy)),
    handlers: handlers,
    checkpoint_store: checkpoints
  ).run(workflow, run_id: "coding-agent-run")
  final_verification = result.fetch(:results).fetch("verify_final").fetch(:result)
  raise "coding-agent example was not accepted" unless result[:status] == :completed && final_verification[:success]

  puts JSON.pretty_generate(status: "accepted", agent_events: agent.events.length, policy_decisions: audit.events.count { |event| event[:event_type] == "decision" }, checkpoints: checkpoints.all(run_id: "coding-agent-run").length, final_check: final_verification[:success])
end

11. OpenAI Responses agent — opt-in live provider

Workflow:

examples/11_openai_responses_agent/workflow.yml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# yaml-language-server: $schema=../../specifications/workflows/v0.1/workflow.schema.json
version: "0.1"
workflow: openai-responses-inspection
profile: autonomous-development
tasks:
  - id: inspect
    action: executor.request
    with:
      operation: model.inspect_workspace
      provider: openai.responses
  - id: checkpoint
    action: checkpoint
    after: [inspect]

Runner:

examples/11_openai_responses_agent/run.rb
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
# frozen_string_literal: true

require "fileutils"
require "json"
require "tmpdir"
require "coding_agent"
require "gateway"

ROOT = File.expand_path("../..", __dir__)
api_key = ENV.fetch("OPENAI_API_KEY") { abort "OPENAI_API_KEY is required" }
model = ENV.fetch("SANDBOX_LOOM_OPENAI_MODEL") { abort "SANDBOX_LOOM_OPENAI_MODEL is required" }
endpoint = ENV.fetch("SANDBOX_LOOM_OPENAI_ENDPOINT", CodingAgent::OpenAIResponsesTransport::DEFAULT_ENDPOINT)

registry = PolicyEngine::Registry.load(File.join(ROOT, "specifications/sandbox/v0.2/capability-registry-v0.2.yaml"))
policy = PolicyEngine::Policy.load(File.join(ROOT, "specifications/sandbox/v0.2/autonomous-development.yaml"))
audit = PolicyEngine::MemoryAuditLog.new
evaluator = PolicyEngine::Evaluator.new(registry: registry, policy: policy, audit_log: audit)

Dir.mktmpdir("sandbox-loom-openai") do |root|
  workspace = File.join(root, "workspace")
  FileUtils.mkdir_p(workspace)
  File.write(File.join(workspace, "README.md"), "Sandbox Loom workspace\n")
  options = { evaluator: evaluator, sandbox_id: "openai-example-sandbox", profile: policy.profile }
  gateway = Gateway::Filesystem.new(workspace_root: workspace, **options)

  tools = {
    "workspace.read" => ->(arguments, _context) { gateway.read(arguments.fetch(:path)) }
  }
  tool_definitions = [
    {
      type: "function",
      name: "workspace.read",
      description: "Read a file inside the declared workspace.",
      parameters: {
        type: "object",
        properties: { path: { type: "string", description: "An absolute virtual workspace path." } },
        required: ["path"],
        additionalProperties: false
      },
      strict: true
    }
  ]
  transport = CodingAgent::OpenAIResponsesTransport.new(
    api_key: api_key,
    model: model,
    endpoint: endpoint,
    tool_definitions: tool_definitions
  )
  result = CodingAgent::ProviderAdapter.new(transport: transport, tools: tools).run(
    session_id: "openai-example-session",
    prompt: "Inspect /workspace/README.md with the workspace.read tool and summarize its contents."
  )

  puts JSON.pretty_generate(
    status: result.fetch(:status),
    run_id: result.fetch(:run_id),
    event_count: result.fetch(:events).length,
    audit_decisions: audit.events.count { |event| event[:event_type] == "decision" },
    note: "The API key is not included in this output."
  )
end

Run the live example only with an explicitly configured API key and model, as described in the example README. The credential is read from the environment and is never part of the displayed source or workflow.