Build a connector host
Write the program that redeems a one-time link, learns which plugin connectors to run on its machine, gets each one's key, and runs it with its settings and mapping.
A connector host is the program that runs a plugin's connectors on a machine the owner linked. Marfa doesn't publish one yet, and the connector kit doesn't take its key from a host, so a host makes the operations below itself.
Redeem the link
The owner gives the host a one-time link, such as https://marfa.example.com/connect#marfa_l1_…. The instance's address is the part before /connect, and the code is the part after the #. Send the code with no credential:
POST /connector-hosts/redeem
Content-Type: application/json
{ "code": "marfa_l1_4f4f4f4f…" }The answer holds the host's id, name and own key. Keep the key where only the host reads it. It holds connectors.host alone, which opens only the two operations below; every other answers 401. A link that ended, or was used, answers 404 connector_link_not_found, and the owner makes another with marfa hosts link.
Learn what to run
GET /connector-hosts/self
Authorization: Bearer $HOST_KEYconnectors lists each plugin connector assigned to the host, with its plugin, version, the plugin's connector section, key_minted, and what the owner asked of it: paused, and run_requested_at when the owner asked for a run now. Don't start a paused connector, and start one with a run requested without waiting for its schedule. Ask on start and from time to time: the owner moves connectors between hosts, and one that leaves the list has lost its key.
Get each connector's key
POST /connector-hosts/self/connectors/rss/key
Authorization: Bearer $HOST_KEYThe answer's key holds the connector's source, write on the type of each of its kinds, and write on each edge type its edge_types names. Each mint revokes the key minted before, so keep the key and mint again only when it's lost or refused. 404 plugin_not_found means the connector no longer runs here.
Run the connector with it
Start the connector with its key. It registers as any connector does, and then, on each run, it:
- Reads what the owner asked with
GET /plugins/{name}/connector, and stops ifpausedistrue. Marfa still takes its writes, so a run under way finishes cleanly. - Reads its settings with
GET /connectors/{id}/settings, which answers its secrets opened, and only to this key. A secret withunreadabletrueneeds the owner to set it again. - Reads its mapping with
GET /plugins/{name}/connector/mapping, and writes each enabled kind as the type and tier it names, filling each field from itsfrom,fixedortemplate. - Carries out each request under
rewrites: it rewrites its items on each kind's target type, then sends the request'snumbertoPOST /plugins/{name}/connector/mapping/rewrite/done. - Answers each pending preview from
GET /plugins/{name}/connector/previews: it renders the preview'skindunder itsmappingon the itemitem_idnames, or a recent one, and sendsresult, at most 64 KiB: the targettypeit rendered under, the fields inproperties, and optionally thetitleand thesource_itemit rendered. Otherwise it sends why aserror. A preview lasts 10 minutes. - Reports the run with
POST /connectors/{id}/runs, naming therun_requested_atit read, so the owner's request clears. A request made after it read one stays for the next run.
On a target type its key doesn't reach, the connector reads and writes only its own items, and the links from them of edge types its key reads. It lists them with any filter, reads each one's edges, versions, extensions and table rows, follows their events and settles their tombstones. Search, views, exports, a working copy and MCP's read tools answer by its key alone.
Its state document, problems and agreements stay with its source on the instance, so a connector moved to another host resumes where it stopped (Holds and retries).
The rules behind this page are in the plugins and connectors chapters of the contract.