Start a monitor

curl --request POST \
  --url https://api.example.com/v1/sessions/{sessionId}/monitors \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "tests",
  "command": "go test ./... -run Ledger",
  "filter": "^(FAIL|ok)"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/sessions/{sessionId}/monitors"

	payload := strings.NewReader("{\n  \"name\": \"tests\",\n  \"command\": \"go test ./... -run Ledger\",\n  \"filter\": \"^(FAIL|ok)\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: 'tests', command: 'go test ./... -run Ledger', filter: '^(FAIL|ok)'})
};

fetch('https://api.example.com/v1/sessions/{sessionId}/monitors', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/sessions/{sessionId}/monitors"

payload = {
    "name": "tests",
    "command": "go test ./... -run Ledger",
    "filter": "^(FAIL|ok)"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "name": "tests",
  "command": "go test ./... -run Ledger",
  "startedBy": "model",
  "startedAt": "2026-08-23T12:01:03.000Z"
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

Start a monitor

Runs command under the session’s repository and streams what it says into the conversation as it happens — batched on the pauses between bursts, so one test failure is one piece of news rather than forty lines. The monitor is announced in the transcript, listed until it is stopped, and killed with the host. A name already in use in this session is refused rather than replaced. It runs on the session’s own machine, in its tree, and never wakes it: a session whose container is not running, whose environment this host does not hold, or one bound to none on a hosted home, is refused 422 and nothing starts.

POST

sessions

{sessionId}

monitors

Start a monitor

curl --request POST \
  --url https://api.example.com/v1/sessions/{sessionId}/monitors \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "tests",
  "command": "go test ./... -run Ledger",
  "filter": "^(FAIL|ok)"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/sessions/{sessionId}/monitors"

	payload := strings.NewReader("{\n  \"name\": \"tests\",\n  \"command\": \"go test ./... -run Ledger\",\n  \"filter\": \"^(FAIL|ok)\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: 'tests', command: 'go test ./... -run Ledger', filter: '^(FAIL|ok)'})
};

fetch('https://api.example.com/v1/sessions/{sessionId}/monitors', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/sessions/{sessionId}/monitors"

payload = {
    "name": "tests",
    "command": "go test ./... -run Ledger",
    "filter": "^(FAIL|ok)"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "name": "tests",
  "command": "go test ./... -run Ledger",
  "startedBy": "model",
  "startedAt": "2026-08-23T12:01:03.000Z"
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}

Autorizações

Authorization

string

header

obrigatório

Enforced on every transport, with no exempt operation. A person's request must carry a JWT issued by the configured identity provider, which the host verifies itself against that issuer's key set: signature, issuer, expiry, and the person and organisation it names. Requests without a valid one receive 401 NRY-0011 — except a request with no token on a laptop's socket from the OS user the kernel names as the host's own, which is that machine's user.

Parâmetros de caminho

sessionId

string<uuid>

obrigatório

The session's id.

Corpo

application/json

A request to run a watcher. Monitors started this way are recorded as the person's; the model starts its own through its tool.

name

string

obrigatório

The watcher's name. Bounded to what a URL path segment carries unchanged, because this same name is the address the request that stops the watcher is sent to.

Required string length: 1 - 64

Pattern: ^[A-Za-z0-9][A-Za-z0-9._-]*$

command

string

obrigatório

Required string length: 1 - 4096

filter

string

Maximum string length: 512

wake

boolean

padrão:false

Whether the watcher's output starts a turn on the conversation while nothing runs in it, paid by whoever started the watcher. Off, the output waits for the next turn. Nothing caps how many turns in a row it wakes: whoever turned wake on stops the watcher or turns it off. A turn under a spend ceiling, or holding only some of the tools, cannot start a watcher with wake on.

Resposta

The monitor, now running.

One long-running watcher a session is keeping beside its conversation.

name

string

obrigatório

Unique within its session; this is what stops it.

command

string

obrigatório

What runs, under the session's repository.

startedBy

enum<string>

obrigatório

Which hand reached the switch. Both may, and the registry treats them identically; this says which one it was, so the model knows before it stops something it did not start.

Opções disponíveis:

model,

user

startedAt

string<date-time>

obrigatório

filter

string

A regular expression keeping only the output lines that match it. Absent means every line.

Visão geral

Host

Sessões

Mensagens

Eventos

Lanes

Monitores

Agentes

Skills e comandos

Permissões

Peers

Pacotes

Extensões

Workflows

Agendamentos

Provedores

Registros

Ambientes

Compartilhamento

Refinamentos

Plataforma

Tratamento de erros

Start a monitor

Autorizações

Parâmetros de caminho

Corpo

Resposta