Programs

A program is code that runs on one machine all the time, listens and acts: a small job that tells you when a file lands in a folder, checks whether a site is up or watches a log file. The agent writes its code and you publish it. A program runs only on your own device: your computer with Orbi Node's sandbox mode on, or a server of your own linked to Orbi. To watch something on the internet regularly, set up a scheduled flow.

#Where a program lives

A program belongs to a space, and everyone who reads that space sees the program's page. Its code is not in Files: every release keeps its own code. So nobody, neither a person nor another agent, can change the code of a running program without a new release. You read the code on the program's page, under Code in the Advanced section. It comes with the orbi.manifest file, which says what the program needs: the machine it runs on, the folders it reads and writes, the internet addresses it reaches, the Orbi connections it uses and how much memory it takes. A program gets only what its manifest says.

A program runs on one device, so it is listed under that device: on the Devices screen, pick the device and open the Programs tab.

A program comes about in two ways: you tell an agent what you want, or you pick a ready-made one. To change its code you also tell an agent what you want; the new release is published with your approval.

#Writing a program with an agent

Tell the agent in a chat what you want, and name the device the program should run on. The agent writes the program in a folder of its computer on that device and runs it there for a while with the real data. In that run the program sends no events; it notes the ones it would send. Work that reads the machine (container state, logs, CPU and memory) really runs, so the agent sees the real container names on the device. Work that changes something, such as restarting a container, is not done in the trial, only noted. Then a confirmation card appears in the chat: the permissions the program asks for and what happened in the trial are open, and the code is one click away. For each action on the machine the card shows Orbi's own record: really read from the machine in the trial, not done in the trial, only noted or never tried. The output the agent wrote sits apart under The agent's note; Orbi does not check it. On a shared device, an agent that does not work for the device's owner does not read the machine in the trial, and the card says so. When the program is published, a small flow is also set up for each piece of news it sends, to notify you, as with ready-made programs. Confirm the card and the program is published. If you are not the device's owner, the release waits for them; they are notified and approve it on the program's page.

#Ready-made programs

A simple job needs no agent. The Programs tab under a machine has four ready-made programs: they tell you when a folder changes, when a line is added to a file, when a site goes down and when the CPU, memory or disk runs high. In the form you pick the folder, the file or the address, the threshold and how often to check; Orbi writes the code. The line program's pattern is a regular expression, for example ERROR|FATAL. The CPU, memory and disk program also asks how long the measurement must stay above the threshold, and checks at most every two minutes. If the machine is yours, the program is published and starts at once; otherwise the release waits for the machine's owner. The form also sets up a small flow for each event: when the event arrives, the flow says what happened in one sentence and that sentence reaches you as a notification. Change or delete the flow on the Flows screen; each event uses one small agent run.

#Manifest

orbi.manifest is a JSON file. An example:

{
  "version": 1,
  "shape": "program",
  "name": "Report counter",
  "host": "@device.ibrahim.mac",
  "folders": [{ "label": "Reports", "access": "read" }],
  "run": { "cmd": ["python3", "main.py"] },
  "events": [{ "name": "count_changed", "schema": { "type": "object", "properties": { "count": { "type": "integer" } } } }],
  "tools": [{ "name": "list_reports", "description": "Lists the files in the Reports folder", "cmd": ["python3", "tool_list.py"] }],
  "network": { "allow": ["example.com"] },
  "limits": { "memoryMb": 256 }
}

• host: the program's device, @device.<person>.<device>.
• folders: the label of each folder to mount, as the device names it, and read or read_write.
• run: the command that runs all the time. A program that only offers tools leaves it out.
• events: the events it may send; with a schema, the data must match it.
• tools: the tools it offers agents; the command reads the input as JSON and writes its answer.
• network.allow: the internet addresses it may reach.
• hostActions: the actions the program may take on its machine; each names the action, the target and an hourly limit (maxPerHour). For example { "action": "service_restart", "target": "compose:prod/api", "maxPerHour": 3 }. The program asks with orbi host_action. Today there are machine_metrics, docker_status, docker_logs, local_port and service_restart (Orbi Node 0.6.0). Orbi Node 0.7.0 adds compose_scale: the program may change how many containers a Compose service runs, but only within the range the manifest gives, for example { "action": "compose_scale", "target": "compose:prod/api", "maxPerHour": 4, "replicas": { "min": 2, "max": 6 } }. A request outside the range is refused; widening the range asks for approval again. Starting new services is not open to programs. A program that reaches the limit stops and a card opens for you.
• limits: memory (MB) and CPUs.

A manifest with a mistake is not published; the error names the field that is wrong.

#Releases

Every publish of a program is a release: it keeps the code and the manifest together. An agent writes the new release and asks for approval; what runs is the last approved release. Releases are listed on the page, and Go back to this returns to an earlier one.

#Stopping and deleting

Stop on the program's page stops it on its device; it stays off until you press Start. To remove a program for good, choose Delete the program from the page's ⋯ menu. It stops on its device, its Orbi access closes and the notice flows that only listen to it are deleted too. Its code and release history are kept for 30 days, then removed for good. The people who may delete a program are those who may publish it: its owner, the device's owner and the workspace admins.

#Approval

A release that asks for more permissions than the one that runs waits for approval: a new folder, writing to a folder, a new internet address, more memory or another machine. The first release asks for approval too. The owner of the program's device approves.

The approver is notified; the approval and the difference in permissions are on the program's page. Until it is approved the earlier release runs, and a first release does not start. A release that asks for no more, or gives permissions up, goes through without waiting.

#Running

An approved release starts running on the program's machine. The program's page shows its state, its latest output and the Stop and Start buttons. A program runs on an isolated computer: its code is read-only, the folders its manifest names are mounted under /mnt/<folder name>, and it has a small working area. A program reaches only the internet addresses in its manifest's network.allow list and Orbi; using Orbi connections (MCP servers, connectors) comes with the next release.

A program that ends is started again on its own. If it ends three times in a row it stops and a card opens for you, with the machine it stopped on, its last output and a link to the program's page. The card goes to the board you chose in the Crash card row of the program's page, or else to the first board of the program's space. If the program crashes again while the card is open, no new card opens; the same card gets a comment. Look at the output, fix it, publish a new version or go back to an earlier release; you can also give the card to an agent.

A program waits while its device is not connected and comes back on its own when it is. If the device's agent computers are all in use, the program takes the place of a chat nobody has written in for a few minutes and starts at once; without such a chat it starts on its own when a place frees up. That chat carries on where it left off at its next message.

#Events

When a program sees something, it sends Orbi an event: the orbi emit_event command takes the event's name and data. The event must be named in the manifest's events list; if it has a schema (JSON Schema) there, the data must match it. A program sends at most 30 events a minute and 500 a day.

Flows listen to events. Ask an agent for a flow such as "when this program sends this event, ..."; the agent ties the flow's trigger to the program and the event's name. The flow runs once for each event and sees its data.

#Tools

Each tool in the manifest's tools list appears to agents as <program>__<tool> while the program runs. For example, the list_reports tool of the "Rapor sayacı" program becomes rapor_sayaci__list_reports. When an agent calls it, the tool runs on the program's computer: the input arrives as JSON on the command's input, and what the command writes goes back to the agent. An agent sees only the tools of programs in spaces you can read; when the program stops, its tools go too.