Actual Budget Server

Fiscal lets agents manage your budget through the fscl CLI, but sometimes you want a visual dashboard with charts, graphs, and a calendar view of your transactions. Actual Budget provides exactly that. This guide walks you through setting up an Actual Budget server and connecting it to Fiscal.

Why run a server?

Without a server, Fiscal stores your budget locally and everything works fine. Adding a server gives you:

• A web dashboard at http://localhost:5006 for visual budgeting
• Sync between the CLI and the web UI, so changes in either show up in both
• Multi-device access if you expose the server on your network

Start the server

This command starts the Actual Budget server in Docker:

docker run --restart=unless-stopped -d \
  -p 5006:5006 \
  -v ~/actual-data:/data \
  --name actual-budget \
  actualbudget/actual-server:26.8.1

The image tag matches the Actual API version bundled with Fiscal. Actual releases its API, web client, and server together, so Fiscal and the server should run the same version. Run fscl status to see both versions and whether they match.

The -v ~/actual-data:/data flag saves your data to a directory on your machine. Without it, your data only exists inside the container and is lost when the container is removed.

Verify the server is running

The container runs in the background, so check its logs:

docker logs actual-budget

You should see output like:

Listening on :::5006...

Set your password

Open http://localhost:5006 in your browser. On first visit, Actual Budget asks you to create a password. Enter it and confirm.

There is no username, just a single server-wide password. Keep it safe. There's no recovery flow, though you can reset it with --reset-password if you have server access.

Connect Fiscal to the server

Pass the server URL and the password you just created:

fscl budgets create "My Budget" --mode local
fscl budgets push \
  --server-url http://localhost:5006 \
  --password YOUR_PASSWORD

This creates the budget locally, then uploads it to the server. If you already have a local budget, run only fscl budgets push.

To avoid passing credentials every time, add them to your config or environment:

# Environment variables
export FISCAL_SERVER_URL=http://localhost:5006
export FISCAL_PASSWORD=YOUR_PASSWORD

Or in ~/.config/fscl/config.json:

{
  "serverUrl": "http://localhost:5006",
  "password": "YOUR_PASSWORD"
}

Open the dashboard

Navigate to http://localhost:5006 and log in with your password. You'll see your budget, accounts, transactions, and reports, all synced with what Fiscal manages on the CLI.

Changes flow both ways: edits in the web UI appear in fscl commands, and CLI changes appear in the dashboard after a sync.

Stopping and restarting

# Stop the server
docker stop actual-budget
 
# Start it again (data persists in the volume)
docker start actual-budget

To remove and recreate:

docker rm actual-budget
# Re-run the docker run command from above

Updating

Upgrade Fiscal first, then move the server to the matching version. The bundled version is shown by fscl status as cli.api_version.

docker pull actualbudget/actual-server:<version from fscl status>
docker stop actual-budget && docker rm actual-budget
# Re-run the docker run command from above with the new tag

The pinned server does not update on its own. Check for new Fiscal releases periodically and upgrade the pair together.