> ## Documentation Index
> Fetch the complete documentation index at: https://redbark.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Actual Budget

> Connect supported bank accounts to a self-hosted Actual Budget instance through Redbark's SimpleFIN integration.

[Actual Budget](https://actualbudget.org/) ships SimpleFIN as one of its built-in bank-sync providers. Redbark implements SimpleFIN with Australian Open Banking data, so Actual can pull your accounts, balances and transactions with a single setup token and no extra container to run.

<Info>
  The native integration needs Actual `24.10.0` or later. If you're on an older version, update Actual first, or use the [legacy container](#legacy-the-actual-sync-container) below.
</Info>

## Prerequisites

* A running [Actual Budget](https://actualbudget.org/) instance, self-hosted or on Actual Cloud
* A Redbark account with connected bank accounts
* A Redbark **Developer** or **Professional** plan (trials included)

## Setup

<Steps>
  <Step title="Generate a SimpleFIN setup token">
    Log into [Redbark](https://app.redbark.com/settings/api-mcp), go to **Settings > API & MCP**, and generate a SimpleFIN setup token. Name it after the instance you're connecting.

    The token is shown once, can be claimed once, and expires in 7 days if unused.
  </Step>

  <Step title="Configure SimpleFIN in Actual">
    In Actual, open **Settings**, scroll to **Bank Sync**, and click **Set up** under SimpleFIN.

    Actual's dialog describes SimpleFIN as a North American service. Paste your Redbark setup token in the Token field anyway and click **Save and continue**. Actual claims the token and receives its own private, read-only credentials.
  </Step>

  <Step title="Link your accounts">
    Click **Link bank account**. Actual lists every account Redbark can see, with live balances. For each one you want, click **Set up bank sync**, point it at an existing Actual account or create a new one, and set a starting date and opening balance.

    Set the starting date to a few months back rather than leaving it open. It keeps the first sync quick.
  </Step>

  <Step title="Sync">
    Actual pulls transactions immediately, then on every sync after that. Transactions carry stable imported IDs, so re-syncs update rather than duplicate.
  </Step>
</Steps>

## How it behaves

* Balances and transactions are proxied live from your bank at the moment Actual asks. Redbark keeps no copy.
* Deduplication uses an `imported_id` of `redbark:<transaction_id>`, so running sync as often as you like never creates duplicates.
* Only banking accounts are served over SimpleFIN. Brokerage accounts connected to Redbark are not exposed.
* Revoking Actual's token from **Settings > API & MCP** cuts its access immediately without touching your bank consent or any other connected app.

Protocol details, limits and query parameters are in the [SimpleFIN reference](/docs/api-reference/simplefin).

## Legacy: the actual-sync container

<Warning>
  The standalone [actual-sync](https://github.com/redbark-co/actual-sync) container is **deprecated** now that Actual reaches Redbark over SimpleFIN. It still works and existing setups can keep running, but it won't get new features. New setups should use the SimpleFIN integration above.
</Warning>

Actual Budget sync runs as a standalone Docker container that pulls transactions from the Redbark API and imports them directly into your Actual Budget server. Everything below is kept for existing users of the container.

<Info>
  This tool uses the Redbark REST API, which is in **beta**. Behaviour may change as the API evolves.
</Info>

### Prerequisites

* A running [Actual Budget](https://actualbudget.org/) server
* Docker installed on your machine or server
* A Redbark account with connected bank accounts
* A Redbark API key

### Setup

<Steps>
  <Step title="Get a Redbark API key">
    <Info>
      **Plan required:** Developer or Professional. API access is not available on the Saver plan.
    </Info>

    Log into [Redbark](https://app.redbark.com/settings/api-mcp), go to **Settings > API & MCP**, and create a new key. Copy it. It is only shown once.
  </Step>

  <Step title="Find your Redbark account IDs">
    Run the tool with `--list-redbark-accounts` to see your connected accounts and their IDs:

    ```bash theme={null}
    docker run --rm \
      -e REDBARK_API_KEY=YOUR_API_KEY \
      ghcr.io/redbark-co/actual-sync:latest \
      --list-redbark-accounts
    ```
  </Step>

  <Step title="Find your Actual Budget account IDs">
    Run with `--list-actual-accounts` to see your Actual Budget accounts:

    ```bash theme={null}
    docker run --rm \
      -e ACTUAL_SERVER_URL=http://localhost:5006 \
      -e ACTUAL_PASSWORD=your-password \
      -e ACTUAL_BUDGET_ID=your-budget-sync-id \
      -v actual-sync-data:/app/data \
      ghcr.io/redbark-co/actual-sync:latest \
      --list-actual-accounts
    ```

    You can also find account IDs in the Actual Budget web UI by copying the UUID from the account URL.
  </Step>

  <Step title="Create your account mapping">
    Map each Redbark account to an Actual Budget account using the format `redbark_id:actual_id`, comma-separated:

    ```
    ACCOUNT_MAPPING=rbk-acc-1:actual-acc-1,rbk-acc-2:actual-acc-2
    ```
  </Step>

  <Step title="Configure environment variables">
    Create a `.env` file with your configuration:

    ```bash theme={null}
    REDBARK_API_KEY=YOUR_API_KEY
    ACTUAL_SERVER_URL=http://localhost:5006
    ACTUAL_PASSWORD=your-password
    ACTUAL_BUDGET_ID=1cfdbb80-6274-49bf-b0c2-737235a4c81f
    ACCOUNT_MAPPING=rbk-acc-1:actual-acc-1,rbk-acc-2:actual-acc-2
    ```
  </Step>

  <Step title="Dry run">
    Preview what would be imported without writing any changes:

    ```bash theme={null}
    docker run --rm --env-file .env \
      -v actual-sync-data:/app/data \
      ghcr.io/redbark-co/actual-sync:latest --dry-run
    ```
  </Step>

  <Step title="Sync">
    Run the sync:

    ```bash theme={null}
    docker run --rm --env-file .env \
      -v actual-sync-data:/app/data \
      ghcr.io/redbark-co/actual-sync:latest
    ```
  </Step>
</Steps>

### Configuration

#### Environment variables

| Variable                     | Required | Default                   | Description                                    |
| ---------------------------- | -------- | ------------------------- | ---------------------------------------------- |
| `REDBARK_API_KEY`            | Yes      |                           | Your Redbark API key (`YOUR_API_KEY`)          |
| `ACTUAL_SERVER_URL`          | Yes      |                           | URL of your Actual Budget server               |
| `ACTUAL_PASSWORD`            | Yes      |                           | Actual Budget server password                  |
| `ACTUAL_BUDGET_ID`           | Yes      |                           | Budget sync ID (Settings > Advanced in Actual) |
| `ACCOUNT_MAPPING`            | Yes      |                           | Account mapping (`redbark_id:actual_id,...`)   |
| `REDBARK_API_URL`            | No       | `https://api.redbark.com` | Redbark API base URL                           |
| `ACTUAL_ENCRYPTION_PASSWORD` | No       |                           | E2E encryption password if enabled             |
| `ACTUAL_DATA_DIR`            | No       | `/app/data`               | Local cache directory for Actual's SQLite DB   |
| `SYNC_DAYS`                  | No       | `30`                      | Number of days of history to sync              |
| `LOG_LEVEL`                  | No       | `info`                    | `debug`, `info`, `warn`, or `error`            |
| `DRY_RUN`                    | No       | `false`                   | Set to `true` to preview without importing     |

#### CLI flags

| Flag                        | Description                                    |
| --------------------------- | ---------------------------------------------- |
| `--list-redbark-accounts`   | List Redbark accounts and their IDs            |
| `--list-redbark-categories` | List Redbark transaction categories            |
| `--list-actual-accounts`    | List Actual Budget accounts and their IDs      |
| `--dry-run`                 | Preview what would be imported without writing |
| `--days <n>`                | Override number of days to sync                |
| `--help`                    | Show help message                              |

### Running with Docker

#### Docker run

```bash theme={null}
docker run --rm \
  --env-file .env \
  -v actual-sync-data:/app/data \
  ghcr.io/redbark-co/actual-sync:latest
```

The `/app/data` volume caches the Actual Budget SQLite database locally. Mount a persistent volume so it doesn't re-download the full budget every run.

#### Docker Compose

```yaml theme={null}
services:
  redbark-actual-sync:
    image: ghcr.io/redbark-co/actual-sync:latest
    restart: "no"
    environment:
      - REDBARK_API_KEY=YOUR_API_KEY
      - ACTUAL_SERVER_URL=http://actual-server:5006
      - ACTUAL_PASSWORD=your-actual-password
      - ACTUAL_BUDGET_ID=your-budget-sync-id
      - ACCOUNT_MAPPING=redbark-acc-id:actual-acc-id
    volumes:
      - actual-sync-data:/app/data

  actual-server:
    image: actualbudget/actual-server:latest
    ports:
      - "5006:5006"
    volumes:
      - actual-data:/data

volumes:
  actual-sync-data:
  actual-data:
```

#### Kubernetes CronJob

```yaml theme={null}
apiVersion: batch/v1
kind: CronJob
metadata:
  name: redbark-actual-sync
spec:
  schedule: "0 */6 * * *"
  jobTemplate:
    spec:
      template:
        spec:
          restartPolicy: OnFailure
          containers:
            - name: sync
              image: ghcr.io/redbark-co/actual-sync:latest
              envFrom:
                - secretRef:
                    name: redbark-actual-sync-secrets
              volumeMounts:
                - name: data
                  mountPath: /app/data
          volumes:
            - name: data
              persistentVolumeClaim:
                claimName: redbark-actual-sync-data
```

### Scheduling

Use cron or your orchestrator's scheduling to run syncs automatically:

```bash theme={null}
# Sync every 6 hours
0 */6 * * * docker run --rm --env-file /home/user/.redbark-sync.env -v actual-sync-data:/app/data ghcr.io/redbark-co/actual-sync:latest >> /var/log/redbark-sync.log 2>&1
```

### How deduplication works

Each transaction is imported with an `imported_id` of `redbark:<transaction_id>`. Actual Budget's `importTransactions()` uses this to detect duplicates:

1. If a transaction with the same `imported_id` exists, it updates instead of creating a duplicate
2. If no `imported_id` match, Actual falls back to fuzzy matching on amount + date + payee

You can run the sync as often as you want. Duplicates are never created.

### Exit codes

| Code | Meaning                                                 |
| ---- | ------------------------------------------------------- |
| 0    | Sync completed successfully                             |
| 1    | Sync completed with errors (some transactions failed)   |
| 2    | Configuration error (missing env vars, invalid mapping) |
| 3    | Connection error (cannot reach Redbark or Actual)       |

### Troubleshooting

**Connection refused to Actual server**
Make sure your Actual Budget server is running and reachable from the Docker container. If both services are in the same Docker Compose stack, use the service name (e.g. `http://actual-server:5006`) rather than `localhost`.

**Budget not found**
Double-check your `ACTUAL_BUDGET_ID`. This is the **sync ID** found in Actual under Settings > Advanced, not the budget name.

**Encryption password required**
If you've enabled end-to-end encryption in Actual Budget, set the `ACTUAL_ENCRYPTION_PASSWORD` environment variable to your encryption passphrase.

**Self-signed certificates**
For Actual servers behind self-signed TLS certificates, set `NODE_EXTRA_CA_CERTS=/path/to/cert.pem` in the container environment.

**Version mismatch**
The tool automatically detects your Actual server version and downloads a matching client library. If you see version errors, make sure the `/app/data` volume is mounted so the cached client persists between runs.

### Security

<Info>
  Your Redbark API key is only sent over HTTPS. Never bake secrets into Docker images. Use `--env-file`, Docker Secrets, or Kubernetes Secrets. The tool caches your Actual budget locally in `ACTUAL_DATA_DIR`, so encrypt the Docker volume on shared infrastructure.
</Info>

### Source code

The sync tool is open source: [github.com/redbark-co/actual-sync](https://github.com/redbark-co/actual-sync)