Sirloop

Docs

Tutorial — your first agent run

Dispatch a coding-agent run from the dashboard, then again over the HTTP API, and watch both stream live.

This tutorial walks you through the core Sirloop loop once, end to end: check what Sirloop can drive, dispatch a run, watch it stream, and read back the result. Five minutes, one prompt, two ways to send it.

You'll need a working install (see getting started) with at least one coding agent CLI detected, and curl — on Windows 10+ that ships in the box.

1. See what Sirloop found

Sirloop drives the coding agent CLIs on your machine. Ask the API which ones it sees:

curl http://127.0.0.1:8080/api/frameworks
{
  "frameworks": [
    { "name": "claude", "display": "Claude Code", "installed": true,
      "found": true, "models": ["fable", "opus"], "agents": ["claude", "Explore"] },
    { "name": "opencode", "display": "opencode", "installed": true,
      "found": true, "models": ["opencode/big-pickle"] }
  ]
}

Anything with "installed": true is something you can dispatch to. If the list is empty, install a coding agent CLI first and restart Sirloop.

Loopback only. Every control endpoint requires the call to come from the same machine, with a localhost / 127.0.0.1 host header. Other computers on your LAN get 403 — the API is yours alone.

2. Dispatch from the dashboard

Open http://127.0.0.1:8080 and use the composer in the center column:

  1. Target — pick new claude run (or whichever agent you saw in step 1).
  2. Working dir — point it at a small folder you don't mind an agent touching; a scratch repo is perfect.
  3. Prompt — something tiny and checkable, like:
Read the README in this folder and write a one-paragraph summary
to summary.txt.
  1. Press Send.

An agent card springs to life on the left, and events start streaming into the feed — tool calls, file edits, the run finishing. That live column is the product's heartbeat: nothing polls, everything arrives as it happens.

3. Dispatch the same run over the API

Everything the dashboard did, you can do from a terminal. The dispatch endpoint is POST /api/instruct:

curl -X POST http://127.0.0.1:8080/api/instruct \
  -H "Content-Type: application/json" \
  -d "{\"tool\": \"claude\", \"prompt\": \"Read the README and write a one-paragraph summary to summary.txt.\", \"cwd\": \"C:\\dev\\scratch\"}"

The response is deliberately tiny:

{ "ok": true, "run_id": "r-8f31c2" }

Hold on to that run_id. Missing tool or prompt is a 400; dispatching to an agent that is disabled is a 400 too; if the agent is currently usage-limited you still get ok, plus a warning field telling you when it's projected to reset.

4. Watch it live

Check the run in the snapshot:

curl http://127.0.0.1:8080/api/state

GET /api/state returns the full hub snapshot — agents, recent events, the last 30 runs, flows, schedules, projects. It's the "what is true right now" call, safe to poll as often as you like.

For the live wire, open the event stream:

curl -N http://127.0.0.1:8080/api/stream

The first frame is hello carrying the full snapshot (the same JSON as /api/state); after that you receive typed deltas as things happen:

event: agent_event   a tool call was relayed
event: run           a run changed state (started, finished, failed)
event: paused        an agent was paused or resumed
event: catalog       the model catalog changed
...

A : ping comment arrives every 15 seconds of silence so idle connections stay honest. This one stream is what the dashboard, the CLI, and the mobile bridge all subscribe to — there is no second, hidden channel.

5. Read back the result

With the run_id from step 3:

curl http://127.0.0.1:8080/api/runs/r-8f31c2

That's the durable record of the run — status, events, timing. Unknown ids are a plain 404, so scripts can probe without fear.

Where to go next

  • The full route table — reads, control, flows, schedules, projects — is in the HTTP API reference.
  • Back in the dashboard, try the same prompt as a flow (the composer's flow target) so it becomes a saved, re-runnable unit.

← All docs