Actual Budget

Plan your budget and track spending with local-first finances.

Choose your deployment and the way you want to use Selfhost. The instructions below follow that choice.

Deployment Use Selfhost with

Set up Actual Budget

Editable Compose files in your own directory.

Create a server password through Actual, then import or create your budget.
For OIDC, restrict the provider application to your intended server owner before connecting it.

selfhost app --directory ./actual-budget init actual-budget

Initialization writes portable files and does not start the app. Review compose.yaml, the private .env and any files in files/, then start it:

selfhost app --directory ./actual-budget start

No Selfhost dashboard or background service is needed. You can also start these files directly:

cd actual-budget
docker compose -f compose.yaml up -d

Connect an existing installation

Use Existing apps → Link an app in the dashboard, or the CLI’s existing-app commands. Choose Actual Budget, its URL and, optionally, its exact Docker container on a connected server.

Save existing.json with your app URL. Add server_id and container for container inspection and actions.

{
  "profile": "actual-budget",
  "name": "Actual Budget",
  "url": "https://app.example.com"
}

selfhost existing link --file existing.json
selfhost existing list
selfhost existing inspect EXISTING_ID

Linking enables the existing-app profile’s supported inspection and actions. It does not import Compose or attach the new-deployment settings and onboarding profiles described below.

Existing app commands, permissions and unlinking

Before configuring integrations

OpenID configuration keeps password login available. User creation remains manual.
The first OpenID login becomes server owner. Selfhost cannot assign or transfer that role.
Back up /data including both server account data and budget files.

Actual Budget integrations

Compose service: actual-budget. These operations use the profile saved when this deployment is created.

The first person to sign in with OpenID becomes the server owner. Restrict the identity-provider application to the intended owner before enabling OpenID, and verify ownership before allowing other accounts. Selfhost does not assign this role.

Native settings

Changes use the app’s Compose environment. Unrelated settings are preserved.

Supported fields (9)

Allowed login methods login-methods: Comma-separated methods: password,openid. Only use header with an explicitly trusted authentication proxy. string
OpenID public URL public-url: string
OIDC discovery document discovery-url: Complete /.well-known/openid-configuration URL. string
OIDC client ID client-id: string
OIDC client secret client-secret: secret
Require OpenID login enforce-openid: The first OpenID user becomes server owner. Keep password login until the intended owner has signed in successfully. stringChoices: true, false
Create OIDC accounts user-creation: Manual requires pre-created users; the first OIDC login establishes ownership. stringChoices: manual, login
Token lifetime token-expiration: Seconds, never, or openid-provider. string
Upload limit in MB file-limit: string

Save a JSON map of the field IDs you want to change as changes.json. Replace FIELD_ID with an ID from the supported fields above, and use its declared value type. Review the plan and replace REVIEWED_REVISION with the revision it returns.

{
  "FIELD_ID": "YOUR_VALUE"
}

selfhost app --directory ./actual-budget config actual-budget
selfhost app --directory ./actual-budget plan actual-budget changes.json
selfhost app --directory ./actual-budget apply actual-budget changes.json --revision REVIEWED_REVISION

Saved changes need service recreation to become active. Existing interpolated environment values stay under your control in .env or Compose.

Identity provider login

Selfhost can register a client with a supported provider and configure this app. Callback path: /openid/callback.

No administrator role is assigned by Selfhost. Check the app’s first-login policy and retain a local recovery account.

Save connection.json and replace the URLs. Supply SELFHOST_IDP_TOKEN privately in your shell.

{
  "provider": "zitadel",
  "issuer": "https://identity.example.com",
  "app_url": "https://app.example.com",
  "name": "Actual Budget"
}

selfhost app --directory ./actual-budget connect-account actual-budget connection.json
selfhost app --directory ./actual-budget connect-plan actual-budget connection.json
selfhost app --directory ./actual-budget connect actual-budget connection.json --revision REVIEWED_REVISION

Test sign-in in a separate browser session. HTTPS domains and HTTP loopback development origins are supported by Selfhost; the chosen app and provider must also accept the resulting callback. Provider permissions, localhost and recovery.

App configuration reference

Versions and updates

This deployment uses the following images. Existing projects retain their saved recipe and images. A new catalogue version does not silently update them.

actual-budget: actualbudget/actual-server:26.9.0

Review compatibility and back up app data before an update. Choose an image version and review the change.

Keep control of your setup

Selfhost remains optional. Your app runs using ordinary Compose files, its own settings and persistent data. Keep the Compose project name and volumes to preserve storage. Configuration exports and setting backups do not include application data.

Standalone CLI guide · Backups and removal · Actual Budget documentation