Login
Protocol version 2: whole messages
Login

These examples use the protocol. Capital words are placeholders; replace them before sending.

Words in capitals stand for values: a login, a server-code (40 lower-case hex digits), a hash (40 or 64), a path or a program. Everything else is as it would be sent.

A build, from a pattern holding its content; create adds to and clone:

{
  "ocx": 2,
  "to": "LAB-USER",
  "run": {
    "clone": "SERVER-CODE",
    "objective": "build trunk for the lab board and send the image",
    "workspace": [
      {"step": "directory", "at": "$$root$$/$$process_user$$/projects/$$repository_name$$/$$run$$"},
      {"step": "files", "of": "trunk", "into": "$$workspace$$/tree"}
    ],
    "sandbox": {
      "uid": 1000, "gid": 1000, "linux_capabilities": [], "network": false,
      "isolate_terminal": true, "ends_with_parent": true,
      "proc": "/proc", "dev": "/dev", "tmp": "/tmp",
      "read_only": ["/usr", "/etc/alternatives"], "read_write": ["$$workspace$$"],
      "homes": [], "created_files": []
    },
    "limits": {"wall": "1h", "cpu": 3000, "processes": 256, "file_size": "2G"},
    "process": {
      "user": "BUILD-USER",
      "command": ["make", "-C", "$$tree$$", "image"],
      "env": {"PATH": "/usr/bin:/bin", "HOME": "$$workspace$$"},
      "verdict": true,
      "unversioned_files": [{"at": "$$workspace$$/tree/out/board.img", "as": "builds/board.img"}]
    }
  }
}

A session of an agent that answers each post, from another pattern: the envelope is the same; only the content differs, and layer 2 reads none of it.

{
  "ocx": 2,
  "to": "AGENT-CLONE-USER",
  "run": {
    "clone": "SERVER-CODE",
    "objective": "answer each post in this thread about the parser",
    "workspace": [
      {"step": "directory", "at": "$$root$$/$$process_user$$/projects/$$repository_name$$/$$run$$"},
      {"step": "password"},
      {"step": "clone", "into": "$$workspace$$/clone"},
      {"step": "checkout", "of": "trunk", "into": "$$workspace$$/tree"}
    ],
    "sandbox": {
      "uid": 1000, "gid": 1000, "linux_capabilities": [], "network": true,
      "isolate_terminal": true, "ends_with_parent": true,
      "proc": "/proc", "dev": "/dev", "tmp": "/tmp",
      "read_only": ["/usr", "/bin", "/lib", "/etc/resolv.conf", "/etc/ssl/certs", "$$release$$"],
      "read_write": ["$$workspace$$"],
      "homes": ["/root/.claude"], "created_files": []
    },
    "limits": {"wall": "8h"},
    "process": {
      "user": "AGENT-USER",
      "command": ["AGENT-PROGRAM", "AGENT-ARGUMENTS"],
      "cwd": "$$tree$$",
      "session": true, "hears": ["PERSON-USER"], "deliveries": "start"
    }
  }
}

Their answers, each a reply where the run is:

{"ocx": 2, "re": "RUN-HASH", "started": {"values": {"workspace": "..."}, "limits": {"wall": "8h"}}}
{"ocx": 2, "re": "RUN-HASH", "stop": {}}
{"ocx": 2, "re": "RUN-HASH", "ended": {"outcome": "stopped"}}

OCX on the clone whose server-code the run's clone gives, acting as the run's to, takes each; every other repository does nothing with it. Layer 2 carries, addresses and answers both without reading run; layer 3 enforces each one's sandbox, limits and steps.

A message of a kind OCX does not read rides the same envelope. Here, for illustration only, a person asks a reviewing agent for a verdict, and it answers; no command, workspace or sandbox is involved, and OCX's readers pass both by:

{"ocx": 2, "to": "REVIEWER-USER", "review": {"checkin": "CHECK-IN-HASH", "objective": "PATH-OF-THE-OBJECTIVE"}}
{"ocx": 2, "re": "REVIEW-REQUEST-HASH", "reviewed": {"verdict": "pass", "note": "ONE LINE"}}

Layer 2 finds each, says who sent it, whom the request asks and what the answer answers, and leaves the content for a reader of that kind; it reads neither content. These kinds are illustrations, not built-in requests or session deliveries.

A node is the host running the daemon, named by hostname; neither login in these messages names a node. publish is built. Watchers write ended with outputs hashes before logs, files and verdicts; see completion.