8.3The local agent

While the desktop app is running it serves a small HTTP API on localhost, and only on localhost. It is how tooling on the same machine asks the app to do things without holding any cloud credentials of its own.

That indirection is the design. An editor plugin that talked to our servers directly would need its own key, its own device binding, its own retry logic, and its own copy of the sync rules. Talking to the running app instead means it inherits all of that for free, and there is exactly one implementation of "what does a pull do" on the machine.

Discovery

The app writes ~/.usourcecontrol/agent.json — %USERPROFILE%\.usourcecontrol\agent.json on Windows — containing the port it is listening on and a bearer token. The token is regenerated on every launch, so anything talking to the agent must read the file rather than remember a value.

$ PORT=$(node -p "require(process.env.HOME + '/.usourcecontrol/agent.json').port")
$ TOKEN=$(node -p "require(process.env.HOME + '/.usourcecontrol/agent.json').token")

$ curl -sS -X POST "http://127.0.0.1:$PORT/v1/status" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"paths":["Content/Maps/MainLevel.umap"]}'

{"files":[{"path":"Content/Maps/MainLevel.umap","status":"modified",
  "lockedBy":"Sarah Chen","outOfDate":false}]}

What it exposes

For coding agents specifically, see section 3.5.