Troubleshoot a self-hosted instance

Start by finding whether the problem is installation, the web/API service, the worker, authentication or the agent runtime. Restarting everything can hide the first useful error, so read status and recent logs first.

Collect the first useful evidence

ficus server list
ficus server status
ficus server logs -n 100

If you have several local instances, add --instance <label> to each status or log command. Confirm the checkout root and URL are the ones you meant to inspect.

Narrow the logs when needed:

ficus server logs -c api -n 100
ficus server logs -c worker -n 100
ficus server logs -f

Stop following with Ctrl+C. This leaves Ficus running. For the default port, curl -i http://localhost:3000/health checks whether Core answers. /health never touches the database, so it can report ok while database-backed pages fail; curl -i http://localhost:3000/health/db returns 200 when Core can query its database and 503 when it can’t. An unauthenticated request to a protected /api/ route can return 401 even when the service is healthy.

Setup stops before it finishes

Docker is unavailable

Run docker info. If it fails, start Docker Desktop or the Docker daemon and rerun setup from the same checkout. Host runtime still needs Docker when you use setup’s managed PostgreSQL database. Choosing host only removes the container requirement for agent commands.

An existing PostgreSQL server is supported through --database-url; it must already be reachable. Do not delete a database container or volume to fix a connection error.

No runtime was chosen

A noninteractive install needs an explicit runtime. --yes alone is insufficient:

ficus server install --runtime host --yes

For an existing checkout:

bun run setup -- --runtime host

If setup says k8s or vm needs a separate deployment, follow the runtime choices instead of substituting an arbitrary environment value.

The service manager is unavailable

On macOS, the default launchd setup requires a logged-in desktop session. On Linux, the default systemd-user setup requires a working user bus. Run setup in that user’s session rather than under a different account. Check any linger warning if services disappear after logout.

Use ficus server setup --help to inspect the supported supervisor options. An existing installation cannot switch supervisors in place: unregister it with ficus server uninstall, then rerun setup with the new supervisor. Unregistering preserves its data.

A port is already in use

Check ficus server list for another installation first. For a fresh checkout, select another base port:

bun run setup -- --runtime host --port 3100

Setup also derives the worker and event ports from that base. To run a second permanent instance, use a separate checkout and an instance label; changing only the browser port is not enough to separate databases and data directories.

The page does not open

If status reports stopped services, run ficus server start, then inspect the API logs. If they exit again, fix the reported startup error before retrying.

If /health responds but the browser page is absent, check FICUS_SERVE_WEB and the web build. From the correct checkout:

bun run build:web
ficus server restart

For remote access, confirm the proxy reaches the API and forwards /ws as well as /ws/*. See runtime and access. Worker ports are not substitutes for the browser endpoint.

Login or CLI authentication fails

• The initial password no longer works: after an administrator registers a passkey, use passkey login. The setup password is a bootstrap credential.

• Passkey registration fails behind a proxy: verify the HTTPS address, the Public address in Settings → Administration → Server address, and FICUS_WEB_ORIGIN if set. FICUS_WEB_ORIGIN must contain an origin with no path. Passkeys only work on the hostname they were made on. To use a passkey at a new hostname, add one from Settings → Account → Passkeys → Add a passkey for another address.

• The CLI returns 401: run ficus auth status to see its backend and credential source, then authorize a device again:

  ficus auth login local --api-url http://localhost:3000

  Use your actual instance URL. Clear an explicitly exported stale FICUS_PASSWORD before browser authorization.

• The CLI returns 403: your account may be signed in but lack permission for that action. Reinstalling the server does not grant a user additional permissions.

Do not clear authentication variables or create another instance as a way to recover an existing account.

The app works but agents cannot run

Check worker logs and the selected runtime. If the instance is under maintenance, inspect Settings → System → Maintenance pause or run ficus system pause-status. Release only your administrator hold when its maintenance work is complete.

If the agent reports a provider error, check Settings → AI Providers and model setup. Saving a provider credential requires the instance’s encryption key. If logs say FICUS_ENCRYPTION_KEY not configured, restore the installation’s existing key from configuration or backup; do not generate a replacement for a database that already contains encrypted credentials.

For host-mode browser errors, install a Chromium-family browser or set FICUS_BROWSER_EXECUTABLE_PATH to its executable, then restart. Missing tmux affects host-mode local deployments. Container runtimes need their Docker image/runtime available independently of the web app.

An update failed

Run ficus update status --offline from the local checkout and inspect recent service logs. The local updater refuses uncommitted source changes; review them before trying again. Preserve them rather than using a destructive Git reset as a repair.

Use ficus server update for the local installation when the API is down. An authentication failure against a remote backend is a separate problem; it does not authorize an offline update on your laptop.

If you need help, include the command, error text, OS, runtime, local status and relevant log excerpt. Remove credentials, first-run links, .env contents and private workspace material before sharing.

Find what is using disk space

Open Settings → Storage. This view requires the same system permission as Logs. The sandbox machine breakdown needs Ficus Cloud or a self-hosted instance using VM sandbox machines; the stored-files section and the cleanup settings work on every runtime.

Each machine shows its used and total disk space. Squads are listed largest first. Expand a squad to see its Squad workspace (repositories, worktrees, caches), then its Agents: each agent’s files with its name, type, status, and when it was last active, largest first. Dormant agents are collapsed into one line, such as 3 dormant · 4.2 GiB · removed automatically from 10/21/2026 (or removal pending once that date has passed and the background cleanup is working through them); expand it to see each one. Folder sizes include their contents, so do not add a parent folder’s size to its children.

Files stored by Ficus lists attachments and images kept on the Ficus server itself, per squad, totalled from Ficus’s records rather than a disk scan. Files that belong to no squad, such as attachments in people’s or the system inbox, are shown as Unattributed. A bar compares agent file, inbox and workflow handoff attachments with the shared attachment quota (INBOX_MAX_TOTAL_STORAGE_BYTES, 10 GB by default); images do not count toward it.

You or the User Assistant can also use ficus system storage --json to read the breakdown and scan state, or ficus system storage --refresh --json to request a background scan. Both return immediately; read again after a few seconds while scanning is true. See the CLI reference.

The page reloads the latest saved result about every five minutes while open; viewing it does not start a scan. Refresh requests a new worker scan; manual scans are limited to once a minute. A scan can take several seconds, and existing results stay visible with their previous timestamp until it finishes. Offline or parked machines show as unavailable. Partial scans are marked rather than presented as empty disks.

If a scan reaches its 45-second limit, measured child folders remain visible even when their parent totals were not returned. These sizes are labeled Partial; sandboxes with no measurements show Not measured. The page reports known scan failures and how many sandbox home totals were returned. A missing total does not prove a sandbox is empty or deleted. Large homes can still exceed the scan budget; repeated refreshes do not guarantee a complete result.

Other disk usage includes shared tools, system files, and files outside known squad directories. This is an approximate breakdown of the sandbox machine’s filesystem, not an inventory of separate database or backup services. Shared files and files changing during a scan can affect attribution. Other sandbox runtimes do not yet provide this breakdown.

Hardlinked files count once per scan and may appear under whichever folder was visited first. Removing one link does not necessarily free the file’s storage, so folder totals are not estimates of reclaimable space. Compare filesystem usage before and after an approved cleanup to verify actual recovery.

Scans run at low CPU and idle I/O priority, but traversing a large directory tree can still generate disk activity. Inspection does not delete files or start agents. Worktree cleanup after work completes helps keep usage down; do not manually remove a worktree that is still in use.

Free space from agents

Every cleanup action asks for confirmation and states what happens and how much space it frees. Disk sizes change only after the next scan; use Refresh to scan sooner.

• Make dormant on an agent row stops the agent and releases its compute, the same as ending it elsewhere. It frees no disk space yet: a dormant agent keeps its files and wakes on a new message. Managers, the system manager, and Assistant agents are not offered. This needs agents:terminate for the squad.
• Make idle consultants dormant… on a squad previews the consultants with no message for a number of days (90 by default), or never messaged and created that long ago, with their sizes. Consultants with queued work or a message waiting are not included. Confirming makes those consultants dormant; Ficus re-checks each one and leaves alone any that became active, without interrupting it. This needs agents:terminate for the squad. To do this automatically, turn on Make consultants dormant after they’ve been idle in the squad’s Settings → Workspace.
• Remove now on a dormant agent, or Remove all now on the dormant group, removes it without waiting for the retention period. Removal runs in the background over the next few minutes, and the agent shows Removing… until it finishes. If removal fails five times, the agent shows Removal failed with the reason, and you can try again. Its home is archived and removed from the machine, and the agent can no longer be woken or reused. This needs system:cleanup.
• Remove dormant agents after (days), under Settings at the bottom of the page with the background monitoring options, sets how long dormant agents keep their files before automatic removal (AGENT_DORMANT_RETENTION_DAYS, 7 days by default). This needs settings-write permission.

Ficus host cleanup, for users with system:cleanup, runs the existing cleanups on the server running Ficus: Scan Nix stores finds the Nix stores of orphaned or terminated agents and reports how much can be reclaimed, and Scan empty workspace folders finds empty folders left by deleted squads. Nothing is removed until you confirm. The same actions are available as ficus admin nix-gc and ficus admin workspace-gc.

Scheduled storage checks

VM sandbox storage is measured every 12 hours by the worker, even with all browsers closed. The latest scan is saved across restarts. In Settings → Storage, users with settings-write permission can change the interval to 1–168 hours (including fractional hours), or use 0 to disable scheduled scans. Manual refresh remains available and normally starts within a minute when the worker is running.

Capacity warnings use thresholds of 80%, 90%, and 95% by default. Change the increasing, comma-separated percentages and enable or disable system-inbox alerts in the same settings section. A scan that crosses a higher threshold sends one alert per machine at the highest crossed threshold. Usage must fall three percentage points below an alerted threshold before it rearms, avoiding repeated alerts near the boundary. Missing measurements are not recovery.

The banner and storage page show latest measured usage, not a continuous live reading. Stale warnings keep their timestamp; failed scans retain previous results and retry after 15 minutes while scheduling is enabled. Scans never start agents, wake parked machines, or delete files. Only the latest breakdown is retained, rather than an unbounded scan history.

The same controls are available through the settings API/CLI keys STORAGE_SCAN_INTERVAL_HOURS, STORAGE_ALERT_THRESHOLDS, and STORAGE_ALERTS_ENABLED. Disabling inbox alerts does not hide capacity warnings in the webapp.