Maybe — User Guide

Maybe is a self-hosted personal finance application — "the OS for your personal finances." It brings every account you own (bank accounts, credit cards, investments, crypto, loans, real estate, vehicles) into one place, tracks every transaction, categorizes your spending, plans budgets, charts your net worth over time, and includes an optional AI assistant that can answer questions about your own financial data. You run it on your own machine or server with Docker, so your data stays with you.

Note

The Maybe project reached its final public release (v0.6.0) and is no longer actively maintained by the original team. The application is fully functional and free to self-host under the AGPLv3 license. This guide documents the app as it exists at that release so you can run and use it confidently.

This guide is for people who want to use Maybe: install it, connect or enter accounts, and manage their money day to day. For architecture, the full environment-variable reference, deployment, and security hardening, see the companion Maybe — Administrator & Developer Guide.

1. Quick Start

Maybe is a web application you host yourself. The fastest path is Docker Compose: one command pulls the official image and starts the web app, a background worker, PostgreSQL, and Redis. You then open http://localhost:3000 in a browser and create your account.

What Maybe does

• One dashboard for everything — net worth, assets vs. liabilities, and a cash-flow Sankey diagram across all your accounts.
• Every account type — checking/savings, credit cards, investments, crypto, loans, properties, vehicles, and custom "other" assets and liabilities.
• Transactions — add manually, import from CSV, or sync automatically from banks via Plaid. Categorize, tag, split income vs. expense, and match transfers.
• Budgets — set monthly budgeted spending and expected income per category.
• Rules — automatically categorize, tag, or rename transactions as they arrive.
• Investments — track holdings, record trades (buys/sells), and value assets.
• AI Assistant — chat with an assistant that can read your accounts and transactions to answer questions (optional, requires an OpenAI key).
• Multi-currency — over 160 currencies including major fiat, crypto, and precious metals, with historical exchange-rate conversion.
• Multi-user "family" — invite household members; data is shared at the family level with role-based access.

Prerequisites

• A machine with Docker Engine installed and running (Linux, macOS, or Windows).

Start the app in two commands

# Download the sample Compose file from the Maybe repository
curl -o compose.yml https://raw.githubusercontent.com/maybe-finance/maybe/main/compose.example.yml

# Pull the image and start the app
docker compose up

[+] Running 4/4
 ✔ Container maybe-db-1      Healthy
 ✔ Container maybe-redis-1   Healthy
 ✔ Container maybe-web-1     Started
 ✔ Container maybe-worker-1  Started

Open http://localhost:3000, click create your account, enter your email and a password, and you are in.

Tip

Out of the box the sample Compose file works with zero configuration — it ships with a default SECRET_KEY_BASE and database password baked in. That is fine for a local trial. If you expose Maybe beyond your own machine, set your own secrets first — see Section 2 and the Admin Guide's Configuration Reference.

What to try next

• Add your first account (Section 4.1).
• Import a CSV of past transactions (Section 4.7).
• Create a monthly budget (Section 4.5).
• Turn on the AI assistant (Section 4.8).

2. Installation

Maybe is distributed as a single Docker image, ghcr.io/maybe-finance/maybe, published to the GitHub Container Registry. The recommended and supported way to run it is Docker Compose.

System requirements

Note

The Compose stack runs four services: web (the Rails app), worker (the Sidekiq background processor), db (PostgreSQL), and redis. The worker is required — account syncing, imports, AI responses, and scheduled jobs all run there.

Step-by-step setup

1. Install Docker and confirm it works:

   docker run hello-world
   

2. Create a working directory for the app:

   mkdir -p ~/docker-apps/maybe
   cd ~/docker-apps/maybe
   

3. Download the sample Compose file:

   curl -o compose.yml https://raw.githubusercontent.com/maybe-finance/maybe/main/compose.example.yml
   

4. (Recommended for anything but a local trial) Create an .env file with your own secrets:

   touch .env
   

   Generate a strong secret key:

   openssl rand -hex 64
   

   3f9c1e... (128 hex characters)
   

   If you do not have openssl, this works with no external tools:

   head -c 64 /dev/urandom | od -An -tx1 | tr -d ' \n' && echo
   

   Put your values in .env:

   SECRET_KEY_BASE="paste-the-generated-string-here"
   POSTGRES_PASSWORD="choose-a-database-password"
   

5. Start the app:

   docker compose up
   

6. Open http://localhost:3000 and create your account on the login page.

7. Run it in the background once you are happy:

   # Stop the foreground process with Ctrl+C, then:
   docker compose up -d
   docker compose ls
   

Important

The very first account you register becomes a family admin. There is no separate setup wizard for the server — the first sign-up owns the instance. Protect those credentials and consider enabling two-factor authentication (Section 4.10) right away.

Verify the install

After docker compose up, the database container reports healthy and the web container serves the login screen. You can confirm the app is alive at any time:

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000/up

200

Tip

The /up path is a built-in health check that returns 200 when the app boots cleanly and 500 otherwise. It is handy for uptime monitors and load balancers.

Keeping Maybe updated

By default your instance does not auto-update. To pull the latest image:

cd ~/docker-apps/maybe
docker compose pull              # fetch the newest published image
docker compose build             # rebuild with updates
docker compose up --no-deps -d web worker   # restart with the new version

To pin to a specific channel, edit the image: line in compose.yml:

image: ghcr.io/maybe-finance/maybe:latest   # latest commit
# or
image: ghcr.io/maybe-finance/maybe:stable   # latest tagged release

Warning

Because the project is no longer actively maintained, latest and stable may not change going forward. Pin to a tag you have tested rather than assuming new updates will arrive.

3. Configuration

Most configuration is done with environment variables at deploy time (the Admin Guide covers every one). This section covers the settings you change from inside the app, under the Settings menu.

In-app settings

The Self-Hosting settings page

On a self-hosted instance, Settings → Self-Hosting exposes options that only make sense when you run the server:

• Require invite for signup — when on, new users can only register with a valid invite code, so a public URL can't be used to create accounts by strangers.
• Require email confirmation — when on, email address changes must be confirmed by clicking a link (requires SMTP to be configured).
• Synth API key — paste a Synth key here to enable historical exchange rates and security prices. You can set it here instead of via an environment variable.
• Clear cache — admins can purge cached exchange rates, security prices, and computed balances, then trigger a fresh sync.

Note

A data provider (Synth) is only required if you hold investments/trades or use more than one currency — Maybe needs it to fetch historical security prices and exchange rates. A single-currency, cash-only setup works without any external provider.

User-facing environment variables you might set

These are the variables most users touch; the Admin Guide lists the rest.

Important

Enabling OPENAI_ACCESS_TOKEN means AI features (chat and AI-assisted rules) call OpenAI and will incur costs on your OpenAI account. Set spending limits on your OpenAI account before turning it on.

See the Admin Guide for the complete configuration reference, including database, storage (S3/Cloudflare R2), Plaid, encryption keys, and monitoring variables.

4. Core Usage

Maybe organizes your finances around a few simple concepts:

• An Account is one thing you own or owe (a checking account, a credit card, a house). Every account has a type and a running balance.
• An Entry is a dated event on an account. The three kinds of entry are a Transaction (money in/out), a Trade (buying/selling a security), and a Valuation (a stated balance on a date).
• Categories, Tags, and Merchants describe your transactions.
• A Budget sets monthly targets per category.
• A Rule automates how incoming transactions are categorized or tagged.
• A Family is your household — all data is shared among the family's users.

4.1 Adding accounts

From the dashboard or the Accounts page you can add any of these account types:

To add a manual account, choose the type, give it a name and currency, and set its starting balance. For properties and vehicles you'll enter a value (and, for properties, an address) through a short wizard.

Tip

Accounts have three live states: active, draft (still being set up, e.g. a property mid-wizard), and disabled (hidden from totals but kept for history). Use Toggle active on an account to disable it instead of deleting, so your past data stays intact.

Connecting a bank automatically (Plaid)

If your administrator has configured Plaid (US and/or EU credentials), you can link a real bank: choose Connect account, pick your institution, and complete the secure Plaid flow. Maybe then syncs balances and transactions automatically in the background.

Note

Plaid is optional and requires Plaid API credentials set by whoever runs the server. Without Plaid, you add accounts and transactions manually or by CSV import — every feature still works.

Syncing

• Sync one account: open the account and choose Sync.
• Sync everything: use Sync all on the Accounts page.

Syncs run as background jobs; balances and charts refresh when they finish.

4.2 Recording transactions

A Transaction is income or an expense on an account. Create one with New transaction: pick the account, date, amount, and a name. Choose whether it is an inflow (income) or outflow (expense) — Maybe stores the sign for you. You can also set a category, a merchant, tags, and notes.

Editing a transaction lets you change any of these fields. When you re-categorize a transaction, Maybe may offer to create a rule so similar future transactions are categorized the same way automatically (see Section 4.6).

Tip

Use Exclude on a transaction to keep it out of budgets and reports (useful for internal transfers you track manually, or reimbursements).

Searching and filtering

The Transactions page supports rich filtering: by account, category, merchant, tag, type (income/expense), date range, amount, and free-text search across the name, notes, and merchant. Your last set of filters is remembered as you navigate.

4.3 Categories

Categories group your spending and income. A fresh family can bootstrap a sensible default set with one click, including:

Each category has a color and an icon. You can create your own, nest subcategories one level deep (a subcategory must share its parent's income/expense classification), and delete categories — when you delete one you choose a replacement category for its transactions.

Note

Categories are limited to two levels (a parent and its subcategories). This keeps reports and the cash-flow diagram readable.

4.4 Tags and merchants

• Tags are free-form labels you attach to transactions (e.g. vacation-2025, reimbursable). Manage them under Settings; each has a color.
• Merchants ("family merchants") are the businesses you transact with. Maybe can auto-detect merchants on imported transactions, and you can create your own with a name and color.

4.5 Budgets

Budgets are monthly. Open Budgets and Maybe takes you to the current month, creating ("bootstrapping") it on demand. For each month you set:

• Expected income for the month, and
• Budgeted spending per category.

The budget view then shows actual spending against your targets, with recent transactions per category. Use the month picker to move between months or plan ahead.

Tip

You don't have to budget every category. Set targets on the few that matter; the rest roll up into your overall spending view.

4.6 Rules — automating categorization

A Rule watches your transactions and applies actions when conditions match. Today rules operate on transactions.

• Conditions test things like the transaction's name, amount, or merchant. You can combine several conditions, including one level of compound (grouped) conditions.
• Actions change the transaction — for example set its category, set a tag, or rename it. Every rule needs at least one action.

Create a rule under Rules → New, define conditions and actions, then confirm. Activating a rule with Apply runs it against your existing matching transactions in the background and keeps applying to new ones.

Note

When you manually change a transaction's category, Maybe may prompt you to turn that change into a category rule — a quick way to build up automation from your real edits. You can dismiss these prompts or disable them in preferences.

4.7 Importing data from CSV

Bring in history from another app or your bank's export. Go to Imports → New, choose the import type, optionally attach it to an account, and upload your CSV. The import runs as a guided flow:

1. Upload the file (a sample CSV is available to show the expected shape).
2. Configure / map your columns to Maybe's fields. Maybe may suggest a template you can apply with one click (including a dedicated Mint import path).
3. Clean and review the parsed rows.
4. Confirm the mappings, then Publish — the import processes in the background.

If something looks wrong after publishing, use Revert to undo the import.

Warning

Imports have a maximum row count. If your file is too large you'll see a message like "Your import exceeds the maximum row count" — split the file and import in batches.

4.8 The AI Assistant

Maybe includes an optional AI assistant you chat with in natural language. Because it can call tools that read your own accounts and transactions, it can answer questions like "How much did I spend on Food & Drink last month?" grounded in your real data.

To use it:

1. Your administrator sets OPENAI_ACCESS_TOKEN on the server (required on self-hosted instances).
2. Enable AI for your user (the AI sidebar/features appear once AI is available).
3. Start a New chat, type a message, and the assistant streams its response. You can rename chats, retry the last response, and keep multiple conversations.

Caution

The assistant sends prompts (which can include details about your finances) to OpenAI, and usage bills your OpenAI account. Only enable it if you're comfortable with both. Set OpenAI spend limits beforehand.

4.9 Investments, holdings, and trades

For Investment and Crypto accounts, Maybe tracks holdings (what you own) derived from trades (your buys and sells).

• Record a trade: open the account and add a trade — choose a security (search by ticker), quantity, price, and date. A buy adds to your position; a sell reduces it. You can also record account fees or cash withdrawals from the same form.
• Holdings are computed from your trades and current prices; the account page shows current positions sorted by value.
• Valuations let you assert an account's value on a date directly (useful for assets you don't trade, like a property or a manually tracked portfolio).

Note

Historical security prices and non-base-currency conversions require a data provider (Synth). Without one, you can still record trades and valuations, but historical price charts won't populate.

4.10 Securing your account (two-factor authentication)

Under Settings → Security you can enable two-factor authentication (MFA) using any TOTP authenticator app (Google Authenticator, 1Password, Authy, etc.):

1. Choose Enable MFA. Maybe shows a QR code (issuer "Maybe Finance").
2. Scan it in your authenticator app and enter the 6-digit code to confirm.
3. Maybe displays 8 one-time backup codes — save them somewhere safe. Each works once if you lose your device.

After enabling, you'll enter a code from your app at every login.

Warning

Store your backup codes before leaving the setup screen. If you lose your authenticator and have no backup codes, you can be locked out of your account.

4.11 Households: inviting family members

Your data lives under a Family. Admins can invite others to share it:

• Hosted/SMTP setups: Settings → Profile → invite sends an email invitation.
• Self-hosted without email: generate invite codes (Settings) and share them out of band; new users register with a code.

Roles are member, admin, and super admin. Admins can invite and remove members and start data exports; a regular member uses the shared data without managing the family.

Note

You cannot remove yourself, and the last admin in a family with other users cannot be deactivated — this prevents a family from being left without an owner.

4.12 Exporting your data

Admins can produce a full export under Settings → Profile → Export. Maybe builds a downloadable ZIP of your family's data in the background; when it's ready you'll be able to download it from the same page. This is the clean way to take your data elsewhere or keep an off-app backup.

4.13 The dashboard and reports

The home dashboard gives you the whole picture:

• Net worth and a balance sheet (assets vs. liabilities) across all visible accounts.
• A cash-flow Sankey diagram showing income flowing into spending categories and surplus, for a selectable period (default: last 30 days).
• Per-account sparklines and balance charts.
• A changelog view that pulls the latest release notes.

4.14 Multi-currency

Pick your family's base currency; all totals are reported in it. Maybe supports over 160 currencies — every major fiat currency plus crypto (BTC, USDC) and precious metals (gold, silver, platinum, palladium). Amounts in other currencies are converted using historical exchange rates (via Synth) so past balances stay accurate.

5. Common Tasks

Short, goal-oriented recipes. Each assumes you're signed in.

Add your first checking account

1. Go to Accounts → New and choose Depository.
2. Name it, pick your currency, and enter the current balance.
3. Save. The account appears on your dashboard and starts contributing to net worth.

If it fails: make sure name, balance, and currency are all filled — all three are required.

Import a year of transactions from a CSV

1. Imports → New, choose the transaction import type and the target account.
2. Upload your CSV; download the sample first if you're unsure of the format.
3. Map your columns (or apply a suggested template), review the cleaned rows, and Confirm.
4. Publish and wait for the background import to finish.

If it fails: if you see a max-row-count error, split the CSV and import in parts; use Revert to undo a bad import.

Build a monthly food budget

1. Open Budgets (it lands on the current month).
2. Set Expected income for the month.
3. Set Budgeted spending on Food & Drink (and any other categories).
4. Track actuals vs. target as the month progresses.

Auto-categorize a recurring charge

1. Find one example transaction and set its category.
2. When prompted, choose to create a rule (or go to Rules → New).
3. Add a condition on the merchant or name, add a set category action, and Confirm, then Apply.

Turn on the AI assistant

1. Ask your admin to set OPENAI_ACCESS_TOKEN on the server (and set OpenAI spend limits).
2. Enable AI for your user, open New chat, and ask a question about your data.

Enable two-factor authentication

1. Settings → Security → Enable MFA.
2. Scan the QR code in your authenticator app and confirm with the 6-digit code.
3. Save the 8 backup codes.

Invite a partner to share finances (no email server)

1. Settings, generate an invite code (self-hosted only).
2. Share the code with them.
3. They register at your instance using the code and immediately see the shared family data.

Connect a real bank (if Plaid is configured)

1. Accounts → Connect account.
2. Select your institution and complete the Plaid login.
3. Maybe imports balances and transactions and keeps them in sync.

Reset just the financial data (keep your login)

Admins can clear cached market data and trigger a fresh sync from Settings → Self-Hosting → Clear cache. For a deeper reset of accounts/categories/budgets, see your admin — that is a destructive operation handled server-side.

Export everything for backup

1. Settings → Profile → Export (admin only).
2. Wait for the ZIP to build, then download it.

Update your instance to the latest image

cd ~/docker-apps/maybe
docker compose pull && docker compose build
docker compose up --no-deps -d web worker

6. Troubleshooting

Error: ActiveRecord::DatabaseConnectionError

Cause: Docker initialized the PostgreSQL volume earlier with a different database role/password than your current configuration — common after a failed first start.

Solution (first-time users only — this deletes the database):

docker compose down
docker volume rm maybe_postgres-data
docker compose up
docker exec -it maybe-postgres-1 psql -U maybe -d maybe_production -c "SELECT 1;"

Prevention: decide on your POSTGRES_PASSWORD before the first up, and don't change it after the volume is created without also resetting the volume.

Caution

Removing the maybe_postgres-data volume permanently deletes all your Maybe data. Only do this on a fresh install you don't mind wiping.

The app won't load and mentions a Redis configuration error

Cause: the web app can't reach Redis, which the background worker and live updates depend on.

Solution: ensure the redis service is running (docker compose ps) and that REDIS_URL points at it (the sample Compose file sets redis://redis:6379/1). Restart with docker compose up -d.

Prevention: keep the redis service in your Compose file; don't remove it.

Page loads but balances and imports never update

Cause: the worker (Sidekiq) service isn't running. Syncs, imports, AI responses, and scheduled jobs all run there.

Solution: confirm the worker is up (docker compose ps) and restart it: docker compose up -d worker.

Prevention: always run both web and worker — the app is incomplete without the worker.

Error: Your import exceeds the maximum row count

Cause: the CSV you uploaded has more rows than a single import allows.

Solution: split the file into smaller CSVs and import them one at a time.

Prevention: export in yearly or monthly chunks from your source app.

Error: Cannot delete a linked account

Cause: the account is connected through Plaid and can't be deleted directly.

Solution: remove the Plaid connection for that institution (delete the linked item from the Accounts page), or disable the account instead of deleting it.

Prevention: use Toggle active / disable to hide accounts you no longer use; reserve deletion for manual accounts.

"You cannot delete this holding"

Cause: the holding belongs to a Plaid-synced account and is managed by the sync, not by you.

Solution: holdings on linked accounts update through Plaid; remove the trade or the connection rather than the holding.

Prevention: manage positions manually only on manual investment/crypto accounts.

AI chat says AI features are not enabled

Cause: either AI isn't enabled for your user, or (on self-hosted) no OPENAI_ACCESS_TOKEN is set on the server.

Solution: ask your admin to set OPENAI_ACCESS_TOKEN, then enable AI for your user.

Prevention: confirm both the server key and your user's AI setting before relying on the assistant.

Password rejected when registering

Cause: Maybe enforces password strength on signup.

Solution: use a password that is at least 8 characters and includes an uppercase letter, a lowercase letter, a number, and a special character.

Prevention: pick a strong passphrase up front; a password manager helps.

Investment charts are empty / exchange rates missing

Cause: no data provider is configured, so Maybe can't fetch historical prices or exchange rates.

Solution: add a Synth API key under Settings → Self-Hosting (or via SYNTH_API_KEY).

Prevention: if you hold investments or use multiple currencies, set up Synth when you install.

Email features (password reset, reports) don't send

Cause: SMTP isn't configured.

Solution: set SMTP_ADDRESS, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, SMTP_TLS_ENABLED, and EMAIL_SENDER. A free Resend tier works well.

Prevention: configure SMTP at install time if you want email confirmation, password resets, or emailed reports.

Diagnostic checklist

• [ ] All four containers (web, worker, db, redis) are up and healthy.
• [ ] http://localhost:3000/up returns 200.
• [ ] SECRET_KEY_BASE and POSTGRES_PASSWORD are set consistently.
• [ ] The worker container is running (or background tasks stall).
• [ ] SYNTH_API_KEY is set if you use investments or multiple currencies.
• [ ] OPENAI_ACCESS_TOKEN is set if you want the AI assistant.

7. FAQ

Q: Is Maybe free?

Yes. It's open source under the AGPLv3 license and free to self-host. The original hosted/managed service is separate; self-hosting has no subscription — billing is disabled on self-hosted instances.

Q: Is the project still maintained?

The original team has stepped back; v0.6.0 was the final public release. The code is fully functional and you're free to run or fork it under the AGPLv3. (Note the "Maybe" name and logo are trademarks and can't be used in forks.)

Q: Do I have to connect my bank?

No. Bank syncing via Plaid is optional and requires Plaid credentials. You can add accounts and transactions manually or by CSV import and use every other feature.

Q: Where is my data stored?

In the PostgreSQL database that runs in your Docker stack, on your own machine or server. Uploaded files (like exports and logos) are stored on disk by default, or in S3/Cloudflare R2 if your admin configures it.

Q: How do I back up my data?

Two ways: use Settings → Profile → Export for a portable ZIP, and/or back up the PostgreSQL volume at the server level (see the Admin Guide).

Q: Can multiple people share one instance?

Yes — invite members to your family. Everyone in the family shares the same accounts and data, with member/admin/super-admin roles.

Q: What currencies are supported?

Over 160, including all major fiat currencies, crypto (BTC, USDC), and precious metals. Set your base currency under preferences.

Q: Do I need an OpenAI account?

Only if you want the AI assistant or AI-assisted rules. Everything else works without it. AI usage bills your OpenAI account, so set spend limits.

Q: Why are my historical balances or stock prices blank?

You likely don't have a data provider configured. Add a Synth API key to fetch historical exchange rates and security prices.

Q: How do I change the port?

Set the PORT variable (and/or adjust the ports: mapping in compose.yml) if something else already uses 3000.

Q: How do I update?

docker compose pull && docker compose build && docker compose up --no-deps -d web worker. Pin the image: tag if you want to control exactly which version you run.

Q: I forgot my password — how do I reset it?

Use the Forgot password link on the login page. This requires SMTP to be configured so Maybe can email you the reset link.

Q: Is there an API?

Yes. Maybe has a developer API (/api/v1) with OAuth and personal API keys. Create a key under Settings → API Key. See the Admin Guide for endpoints, scopes, and rate limits.

Q: Can I run this without Docker?

The supported self-hosting path is Docker Compose. A from-source developer setup exists for contributors (Ruby + PostgreSQL), but for using the app, Docker is the way.