Bring in records from another service
Run one of the connectors Marfa ships, so your tasks, events, highlights or feeds arrive in your feed and stay up to date.
A connector is a small program you run yourself that reads another service and writes what it finds into your feed, under a type of its own. Some also carry your changes back, such as a Todoist task you complete in Marfa. The server never runs one. Running one takes three things: you build it from source on a computer with Git, Node.js and pnpm; you make its key on the machine your server runs on; and you run it there or on any computer that can reach your instance, with the key and the service's credentials in its environment.
Each connector has a page in the Catalog that says what it reads, what it writes back, and the settings and key it needs.
A Google connector also needs a Google Cloud project of your own first: Create a Google Cloud project for Google connectors. To write a connector for a service that isn't listed, see Build a connector.
Before you start
- The CLI signed in with Full access, on any computer, to make the connector's key, as A key for a connector explains.
- Git, Node.js 22.13 or later and pnpm 11 on the computer that runs the connector.
- The connectors' source. They're published as source in withmarfa/marfa-connectors, with no package to install, so you build them from its
mainbranch.
Run one
The steps use the RSS connector, which needs no account.
Build the connectors
git clone https://github.com/withmarfa/marfa-connectors.git
cd marfa-connectors
pnpm install --frozen-lockfile
pnpm buildThe build compiles every connector in the repository.
Make its key
Make a key that holds only what the connector writes. The RSS connector writes rss.entry items into the feed:
marfa keys create \
--label rss --source rss --type-permission rss.entry=write \
--metadata-permission types=write --default-tier feedCopy the key from the answer, because Marfa shows it once, and keep it in your password manager. --metadata-permission types=write lets the connector add its type the first time it starts. Each connector's Catalog page has the command for its own key, and the connector refuses a key that holds more or less than it needs, naming what to change. Manage keys explains each option.
Run it once
In a terminal of its own, so the connector's key doesn't replace your own, give it your instance's address, its key and its settings, then run it with --once. RSS_FEEDS holds one feed on each line:
export MARFA_API_URL=https://marfa.example.com
export MARFA_API_KEY=<the connector's key>
export RSS_FEEDS='https://example.org/feed.xml
news=https://example.com/atom.xml'
node connectors/rss/dist/main.js --once2026-11-19T00:15:49.402Z info registered as 01a1f125-53b5-77aa-84a7-d453cd05ce6e
2026-11-19T00:15:49.536Z info run succeeded: created 2, updated 0, archived 0, unchanged 0, skipped 0A feed's address can hold a token, so keep RSS_FEEDS and the key out of any file in the checkout.
Check what arrived
Back in your own terminal, list your connectors. Each shows its last run and what that run did, or why it failed:
marfa connectors listid source name last run finished note
01a1f125-53b5-77aa-84a7-d453cd05ce6e rss rss succeeded 2026-11-19T00:15:49.536Z created 2, updated 0, archived 0, unchanged 0, skipped 0The new entries are in your feed: marfa items list --type rss.entry lists them. Keep the ones you want by moving them to your library, as Work from the command line shows. The connector never moves anything there itself.
Keep it running
A connector run once takes in what's there now. To keep up with the service, run it again and again:
- Leave it running with
--every 15min place of--once. It reads the service every 15 minutes, never starts a run while one is still going, and waits longer after a run that failed. - Run it from a scheduler with
--once, such as cron, launchd or a scheduled container. The template's README has a launchd file and a container image.
Run one copy of each connector. A second copy under the same key waits under --every, and exits under --once. The connector keeps its place in the service on your instance, not in a file, so a new process, or one on another computer, carries on from the last run.
A run with --once ends with one of these codes, for a scheduler to act on:
| Code | Meaning |
|---|---|
0 | The run succeeded, or the connector was stopped cleanly. |
1 | The run failed, or the connector couldn't start, such as on a key it refuses. |
2 | A setting is missing or malformed. The log names the setting, never its value. |
A failed run loses nothing, and the next run reads the service again.
When a run fails
marfa connectors list shows the reason in the note column, such as this answer to a key an app made:
01a1f124-aaa3-70f3-8ed9-61eb7b6509d4 rss rss failed 2026-11-19T00:11:14.480Z the key 01a1f124-95ba-777f-8c8f-4e4d26707dc1 is refused: an app made it, and it stays that app's. Mint the connector a key of its own as connectors/rss/README.md says.marfa connectors runs <connector-id> lists its recent runs, each with what it did or what went wrong, and marfa connectors get <connector-id> shows the problems it reports now, such as a service that no longer lets it in. For a Google connector, see Google connectors.
Stop or remove a connector
- To stop it, stop its process or take it out of its scheduler. Nothing on your instance changes, and its items stay.
- To cut it off, revoke its key with
marfa keys revoke <key-id>, as See and cut access shows. It can't write again with that key. - To start it again from the beginning, run
marfa connectors state delete <connector-id>. Its next run reads the whole service again. - To remove it from the list, run
marfa connectors delete <connector-id>. This deletes its registration and its runs, but keeps its place in the service, for a later key under the same source.
None of these moves the connector's items to the bin. To remove them, move them to the bin as you would any item.