# Bring in records from another service (/use/connect-a-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](/catalog/connectors) 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](/use/google-project). To write a connector for a service that isn't listed, see [Build a connector](/build/connector).

## Before you start [#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](/run/manage-keys#a-key-for-a-connector) explains.
* **Git, [Node.js](https://nodejs.org) 22.13 or later and [pnpm](https://pnpm.io/installation) 11** on the computer that runs the connector.
* **The connectors' source.** They're published as source in [withmarfa/marfa-connectors](https://github.com/withmarfa/marfa-connectors), with no package to install, so you build them from its `main` branch.

## Run one [#run-one]

The steps use the RSS connector, which needs no account.

### Build the connectors [#build-the-connectors]

```bash
git clone https://github.com/withmarfa/marfa-connectors.git
cd marfa-connectors
pnpm install --frozen-lockfile
pnpm build
```

The build compiles every connector in the repository.

### Make its key [#make-its-key]

Make a key that holds only what the connector writes. The RSS connector writes `rss.entry` items into the feed:

```bash
marfa keys create \
  --label rss --source rss --type-permission rss.entry=write \
  --metadata-permission types=write --default-tier feed
```

**Copy 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](/run/manage-keys) explains each option.

### Run it once [#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:

```bash
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 --once
```

Output:

```text
2026-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 0
```

A feed's address can hold a token, so keep `RSS_FEEDS` and the key out of any file in the checkout.

### Check what arrived [#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:

```bash
marfa connectors list
```

Output:

```text
id                                    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 0
```

The 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](/use/command-line) shows. The connector never moves anything there itself.

## Keep it running [#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 15m` in 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](https://github.com/withmarfa/marfa-connectors/blob/main/template/README.md#run-it) 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 [#when-a-run-fails]

`marfa connectors list` shows the reason in the `note` column, such as this answer to a key an app made:

```text
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](/run/troubleshooting/google-connectors).

## Stop or remove a connector [#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](/use/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.
