Skip to main content

Doctor checks

istota doctor runs every check below against the loaded config and reports each as ok, warn, fail or skip, with a remedy on everything that is not ok. It exits 1 on any fail. The same checks run at daemon start-up (silent unless something is wrong), every hour from the scheduler ([scheduler] doctor_check_interval), from the self-check heartbeat, and in Admin > Health, which shows the runs the daemon records. An hourly run that moves a check into fail alerts each admin's alerts channel.

Select checks by name prefix with --only (istota doctor --only security. or --only nextcloud.rclone_rc). --scope image runs only the checks a bare docker run of the image can answer (marked image below); --scope deployment runs the rest. Two checks are opt-in: sandbox.masks runs with --deep, and runtime.model_execution runs only when named, since it calls a model.

A skip is not a pass. The forge checks skip when no forge token is configured, and most connection checks skip when their service is off, so a run with no fail says nothing about a feature whose checks skipped. Run inside a task, checks that need the daemon's environment skip rather than fail.

Runtime​

CheckWhat it answers
runtime.platformThe operating system and architecture. image
runtime.bwrapbubblewrap is installed and can run. image
runtime.model_cliThe claude CLI the claude_code brain runs is installed. image
runtime.gitleaksgitleaks with its git subcommand is installed wherever developer tasks commit. image
runtime.gwsThe gws binary is installed when Google Workspace is enabled. image
runtime.pdf_toolspdftotext and pdftoppm are installed for the health module. image
runtime.native_brainThe native brain names a provider, and that provider has a key
runtime.framework_dbThe framework database opens, passes quick_check and has a schema
runtime.task_failure_rateWhether most of the last hour's tasks failed
runtime.writable_dirsThe directories the daemon writes to exist and are writable
runtime.mount_livenessA configured workspace mount is mounted, and a host folder carries its .istota-workspace marker
runtime.workspace_xattrExtended-attribute calls on a workspace file fail cleanly rather than with EIO
runtime.workspace_modeThe configured storage mode agrees with the mount the workspace is on
runtime.egress_holdWhether istota-stack hold keeps the stack's containers off the network; warns while it does
runtime.workspace_diskThe local workspace's disk has room left: warns under 10% or 2 GiB free, fails under 2%
runtime.data_diskThe disk holding the databases (on a VM, also Docker's images and volumes) has room left. The remedy names istota-stack reclaim
runtime.session_log_dirWhere native-brain transcripts are written, and that no task can read them
runtime.task_control_dirThe daemon-owned directory holding each task's prompt and attachments sits where no task can write above it
runtime.bare_metal_importWhether this install was imported from a bare-metal one; warns on every run for a rehearsal copy
runtime.subscription_usageThe Claude Code plan's usage against its limits, with reset times
runtime.model_executionA real model call answers through the tool harness. Costs a call; runs only when named

Models​

CheckWhat it answers
models.cli_authHow the claude CLI authenticates, and whether that credential is present and used as configured
models.catalogueEvery configured model resolves on the brain that runs it, each provider's model list is fresh, and the model-listing key file is private

Storage and backups​

CheckWhat it answers
backups.off_volumeThe database snapshots are not on the same disk as the databases they protect
nextcloud.connectionThe bot signs in to Nextcloud as the configured account, and Talk is installed when it is used. An outage warns; a wrong password or account fails
nextcloud.rclone_rcIn full Nextcloud integration, the mount's control socket answers with its password and refuses a caller without one

Security​

CheckWhat it answers
security.skill_proxyThe istota-skill entry point the proxy runs resolves on the daemon's PATH, and, as security.skill_proxy.forge_posture, where the forge token sits while the proxy is off
security.sandbox_effectiveThe sandbox the config asks for is in force
security.task_cgroupsEach task gets a cgroup of its own with its memory, process and CPU limits written
security.linked_resource_bindsThis bubblewrap can bind from a file descriptor, which linked folders need
security.sandbox_credentialsWhat skill_proxy_enabled = false exposes while the sandbox is on
security.proxy_peer_checkThe skill proxy can tell its own task's processes from others
security.credential_brokerThe credential broker is ready, without generating a CA or reading a secret
security.skill_model_credentialA skill CLI that calls a model of its own (the code review) can authenticate
security.secret_keyThe encrypted secrets store has a master key of sufficient length
security.adminsFails when two or more users are configured and nobody is an admin
security.key_separationKey files are not stored beside the databases or backups they protect
security.credential_libraryThe KeePass import and export libraries are installed. image
security.credential_isolationCredential vaults for several users are kept apart by the sandbox
security.credential_backupScheduled credential backups to registered recipients are not failing or overdue
security.walletThe wallet's payment cards are ready, without showing card details
security.egress_open_jobsHow many scheduled jobs still run on full access
security.room_scope_confinementA guest's turn in a shared room is kept out of the host's files on disk, which needs the sandbox
security.signup_tagsNo signup address stays open after its credential was removed
security.inline_credentialsNo installation credential is written inline in config.toml rather than in its secret file
security.devbox_netfilterA devbox cannot reach what the VM's egress rules drop
sandbox.masksA real sandbox namespace hides the databases. Runs with --deep

Browser​

CheckWhat it answers
browser.api_tokenThe browser API accepts the token this process holds
browser.chrome_versionWhich Chrome the browser runs, and whether it has trailed a stable release for more than seven days. The remedy is istota-stack update

Developer​

These skip when the developer skill has no forge token configured.

CheckWhat it answers
developer.forge_binariesThe gh and glab binaries the wrapper runs exist and are executable. image
developer.forge_config_driftThe configured forge binary path is the one that resolves
developer.forge_wrapper_shadowingNothing resolves gh or glab by name to an unexpected binary. image
developer.forge_policyEvery forge_cli_permit entry matches a rule
developer.gitlab_reviewer[developer] gitlab_reviewer is a username glab can resolve
developer.forge_transportNo forge token travels over plain HTTP or sits in a URL
developer.repos_layoutClones are in the per-user layout the daemon reads
developer.containerThe development container's backend, transport, identity and the rest of what fails silently, as separate results

Messaging​

CheckWhat it answers
talk.signaling_reachableThe Talk high-performance backend answers
talk.signaling_chat_relayThe signaling server relays chat messages, not only refresh hints
talk.signaling_authTalk is in external signaling mode and has a token key
talk.signaling_watchersEvery live room has a connected watcher and none has fallen behind
sms.commonSMS is configured locally, without contacting a provider
sms.twilio, sms.telnyxThe provider's settings are complete
whatsapp.commonWhatsApp is configured locally, without contacting Meta
whatsapp.billingWhether the Cloud API's spending stop is open, and what this month has spent
whatsapp.media_stagingThe inbound image staging directory is private and empty
whatsapp.gif_decoderA GIF sent over Baileys can be shown to the model
whatsapp.baileys_bridgeThe Baileys sidecar is connected and its session is alive
whatsapp.baileys_sessionEvery paired-session credential on the host is private
whatsapp.pairing_relayThe pairing relay file is private, and whether a pairing is in progress
email.confirmation_answersA user whose alerts reach only email can answer a held task by mail
email.sender_matchWhether mail from a user's own address is trusted on its From: header alone
email.sender_flagsWhether suspected-injection flags can be recorded against a sender on this deployment
mail.connect_verifiedThe TLS context every IMAP and SMTP connection uses verifies the server. image
mail.account_isolationOne user's task is kept away from another user's mail account passwords
push.credentialsThe APNs signing key's metadata, without opening the key or sending. Skipped under relay delivery
push.signing_keyWith [push] content = "private": the private push signing key is a regular file, mode 0600, owned by the service user, parses as Ed25519, and matches its .pub file. Reports the key ID. Skipped when push is disabled or content is legacy
push.relayWith [push] delivery = "relay": the relay URL is a normalized https:// base URL, and the relay answers GET <relay_url>/healthz with 200. An unreachable relay or a 5xx is a warning, a redirect or a 4xx a failure. Fails when the push credentials directory is not a directory, has a mode looser than 0700, or holds a .cap file readable by others; warns when it cannot be written or created. Warns when devices are waiting to enroll again (their route expired or was revoked, or its credential file is missing), when route revocations have been queued for more than a day, and when APNs settings are set, since relay delivery ignores them. Skipped when push is disabled or delivery is direct

Web​

CheckWhat it answers
web.authLogin prerequisites: methods, hostname, mail, identities, admins, proxy IP checks and the session secret, as seven results
web.staticThe web UI's build exists. image
web.tlsIn direct ingress, nginx serves a certificate a client accepts
web.build_currentThe served web bundle is current for this checkout. Skips on the stack
web.basemapThe map pages have a background that will render. Opens no connection
web.avatar_importHow the last import of Nextcloud profile pictures went
web.config_applierThe host is taking the web config editor's requests

Connections and sharing​

CheckWhat it answers
servarr.connectionEach configured arr app answers with its key, one result per app
sharing.ics_feedsHow the calendar feeds users shared with Istota are doing, as counts
sharing.ocmA remote server can reach the Open Cloud Mesh receiver at [site] hostname

Users and configuration​

CheckWhat it answers
config.skill_overlaysEvery per-skill user overlay loads, or is named with the reason it does not
config.operator_personaWhich persona is in force, and whether a shipped update is waiting to be merged
users.email_address_uniquenessNo email address is held by more than one user

Checks report names and counts, never credential values. The detail for each check, and the reasoning behind its severities, is in the source, src/istota/doctor.py.