Compute Workspace

Sandbox

Run an imported skill against one stored input in an isolated sandbox, and get back an output_key you can feed to the next run.

Overview

A sandbox run executes one skill against one stored input and returns a single output_key. The run is synchronous, the request returns once the skill finishes (server-capped at 120s), and the returned key is already scoped under your workspace prefix, so it auto-registers into Storage and is itself a valid next input_key.

The skill must be imported into your workspace first. See Managed Skills to discover and import a skill from a GitHub repo before running it here.

Run a skill

POST/api/v1/dedicated-tasks/run

Parameter	Type	Description
`business_profile_id`required	string	Active workspace id.
`skill`required	string	Imported skill slug, e.g. evidence-clip.
`input_key`required	string	Storage key of the input. Must be scoped under this workspace’s own prefix.
`params`	object	Skill parameters as key/value pairs.

The response carries status, the skill’s assistant_text, and the generated output_key (error is set when the run does not complete).

curl

curl -X POST http://localhost:8080/api/v1/dedicated-tasks/run \
  -H "Content-Type: application/json" \
  -d '{
    "business_profile_id": "<workspace-id>",
    "skill": "evidence-clip",
    "input_key": "<workspace-id>/inputs/clip.mp4",
    "params": { "start": "1", "end": "4" }
  }'

CLI

# Run an imported skill against a stored input, in an isolated sandbox
stimulir sandbox run evidence-clip \
  --input-key <workspace-id>/inputs/clip.mp4 \
  -P start=1 -P end=4

SDK

from stimulir_cli.sdk import StimulirClient

client = StimulirClient()
result = client.sandbox.run(
    "evidence-clip",
    workspace_id="<workspace-id>",
    input_key="<workspace-id>/inputs/clip.mp4",
    params={"start": 1, "end": 4},
)
print(result["status"], result["output_key"])

Capture the output_key in a shell

--output-key-only prints nothing but the bare output_key on success (and exits non-zero on failure), so you can capture it into a variable and chain runs by hand.

bash

KEY=$(stimulir sandbox run evidence-clip \
  --input-key <workspace-id>/inputs/clip.mp4 --output-key-only)

# Feed it straight into the next run
stimulir sandbox run privacy-layer --input-key "$KEY"

Pipe several skills

pipe runs an ordered list of skills, threading each step’s output_key into the next step’s input_key. It short-circuits on the first step that does not complete, returning the results gathered so far. A best-effort pre-flight rejects any slug not imported into the workspace before anything runs.

Per-step params attach to the slug with a colon: slug:key=value,key2=value2.

CLI

# Each --step's output feeds the next; repeat --step in order
stimulir sandbox pipe \
  --step privacy-layer \
  --step capture-traces \
  --input-key <workspace-id>/uploads/raw.jsonl

# With per-step params, and only the final output_key printed
stimulir sandbox pipe \
  --step privacy-layer:mode=strict \
  --step capture-traces \
  --input-key <workspace-id>/uploads/raw.jsonl \
  --output-key-only

SDK

from stimulir_cli.sdk import SandboxPipeError

try:
    results = client.sandbox.pipe(
        ["privacy-layer", {"skill": "capture-traces", "params": {}}],
        input_key="<workspace-id>/uploads/raw.jsonl",
        workspace_id="<workspace-id>",
    )
    final_key = results[-1]["output_key"]
except SandboxPipeError as exc:
    # exc.results holds the per-step results up to the failing step
    print("pipe stopped at", exc.skill)

Each step is a separate synchronous run in its own sandbox, the pipe is a client-side chain of run calls, not a server-side job.

List past runs

GET/api/v1/dedicated-tasks

Lists the most-recent runs for the active workspace, skill, status, duration, and start time. This is the same history shown in the Sandbox panel of the Compute Workspace, where each dedicated-task run appears with its skill, status, and output.

bash

stimulir sandbox list

Isolation

Every run executes in its own isolated sandbox, an AWS Lambda MicroVM (Firecracker), with the skill’s coding tools running inside it and the input pulled from your workspace storage. The sandbox is dedicated to that single run and torn down once the task completes. Runs do not share filesystem or process state; the only thing that survives a run is the output_key written back to Storage.

Overview#

Run a skill#

Capture the output_key in a shell#

Pipe several skills#

List past runs#