Watch Directory

GET /v1/agents/runtime/{runtime_id}/files/watch Streams filesystem change notifications as Server-Sent Events. The watch is backed by the guest kernel’s inotify interface, so events are delivered as the kernel observes them rather than by polling: there is no scan interval and no CPU cost while the tree is idle. Use this to react to a build writing artefacts, an agent editing source files, or a long running job dropping results into a directory.

from gravixlayer import GravixLayer

client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"
sandbox = client.runtime.create()  # defaults to template="base-small"
sandbox.file.create_directory("/workspace/out")

for event in sandbox.file.watch("/workspace/out", recursive=True):
    if event.type == "start":
        print("watch armed")
        sandbox.file.write("/workspace/out/done.txt", "ok\n")
        continue
    print(event.type, event.path, event.new_path)
    if event.name == "done.txt":
        break

sandbox.kill()

import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"
const sandbox = await client.runtime.create(); // defaults to template="base-small"
await sandbox.file.createDirectory('/workspace/out');

for await (const event of sandbox.file.watch('/workspace/out', { recursive: true })) {
  if (event.type === 'start') {
    console.log('watch armed');
    await sandbox.file.write('/workspace/out/done.txt', 'ok\n');
    continue;
  }
  console.log(event.type, event.path, event.newPath);
  if (event.name === 'done.txt') break;
}

await sandbox.kill();

gravixlayer runtime files watch "$RT" /workspace/out --recursive

curl -N "https://api.gravixlayer.ai/v1/agents/runtime/$RT/files/watch?path=/workspace/out&recursive=true" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"

Parameters

Parameter	Type	Required	Description
`path`	string	Yes	Directory to watch
`recursive`	boolean	No	Also watch subdirectories, including ones created later. Defaults to `false`

Events

Each SSE frame carries one JSON object.

Field	Type	Description
`type`	string	`start`, `create`, `write`, `remove`, `rename` or `chmod`
`name`	string	Base name of the affected entry
`path`	string	Absolute path of the affected entry
`new_path`	string	Destination path, populated only for `rename`
`watcher_id`	string	Identifier of the underlying guest watcher
`timestamp`	integer	Event time in Unix nanoseconds

The first event is always start. It confirms the watch is armed; only changes that occur after start are guaranteed to be observed. Arm the watch before triggering the work you want to observe.

data: {"type":"start","watcher_id":"w-3f1a","path":"/workspace/out"}

data: {"type":"create","name":"part-0.json","path":"/workspace/out/part-0.json","timestamp":1760000000123456789}

data: {"type":"write","name":"part-0.json","path":"/workspace/out/part-0.json","timestamp":1760000000987654321}

data: {"type":"rename","name":"part-0.json","path":"/workspace/out/part-0.json","new_path":"/workspace/out/final.json","timestamp":1760000001000000000}

Behaviour notes

Writes are coalesced. A burst of writes to the same file within a short window is reported as a single write, so a large file copy does not produce thousands of events.
Renames are paired. A move within the watched tree is reported once as rename with both path and new_path, not as a separate remove and create.
The stream is open ended. Iterate for as long as you want notifications and break out to stop watching; the underlying HTTP response and the guest watcher are released when you do.
Recursive watches cover new subdirectories. Directories created after the watch is armed are picked up automatically.

Getting Started

Runtime

Support

Parameters

Events

Behaviour notes

​Parameters

​Events

​Behaviour notes

Parameters

Events

Behaviour notes