# Wotbox 0.3.1 settings reference

This file describes settings, their defaults and the scope they control. It contains no installation secrets or current private values.

The private WebMCP/MCP tool `wbdashboard_explain_settings` accepts optional `group` and `key` filters and returns these explanations. Agent tool grants apply; explanations do not grant write permission.

## files

### Browse outside Wotbox (`expanded`)

Default: `false`. Scope: Owner file browser.

Show paths outside the three instance locations after owner confirmation. OS permissions still apply.

Confirmation: The file browser should not go outside of its scope. do you want to proceed Y/N?

### Edit standard text (`edit_text`)

Default: `false`. Scope: ReaderBox, including agent saves.

Allow saving .md and .txt files. No danger prompt for ordinary text.

### Edit configuration and source (`edit_protected`)

Default: `false`. Scope: ReaderBox, including agent saves.

Allow protected text saves after confirmation of the exact changed content.

Confirmation: Warning! changing this file may cause your system to fail. Are you sure your want to proceed? Y/N

### Confirm move to trash (`confirm_trash`)

Default: `true`. Scope: FileBox human and agent operations.

Require confirmation before moving a file or folder to trash. Permanent deletion always requires its own confirmation.

### File associations (`associations`)

Default: `"ReaderBox text handlers"`. Scope: FileBox dispatch.

Installed apps declare supported types and operations. Registrations never grant file access or execute command strings.

## agents

### Read ordinary files (`read`)

Default: `true`. Scope: Private file tools; does not constrain separate administrator SSH access.

An operation also needs its individual agent grant and applicable app setting. Agents cannot change these settings or approve their own confirmation.

### Create folders and copy files (`create`)

Default: `true`. Scope: Private file tools; does not constrain separate administrator SSH access.

An operation also needs its individual agent grant and applicable app setting. Agents cannot change these settings or approve their own confirmation.

### Rename and move ordinary files (`organize`)

Default: `true`. Scope: Private file tools; does not constrain separate administrator SSH access.

An operation also needs its individual agent grant and applicable app setting. Agents cannot change these settings or approve their own confirmation.

### Move ordinary files to trash (`trash`)

Default: `true`. Scope: Private file tools; does not constrain separate administrator SSH access.

An operation also needs its individual agent grant and applicable app setting. Agents cannot change these settings or approve their own confirmation.

### Edit standard text when ReaderBox editing is enabled (`edit_text`)

Default: `true`. Scope: Private file tools; does not constrain separate administrator SSH access.

An operation also needs its individual agent grant and applicable app setting. Agents cannot change these settings or approve their own confirmation.

### Change protected configuration and source (`edit_protected`)

Default: `false`. Scope: Private file tools; does not constrain separate administrator SSH access.

An operation also needs its individual agent grant and applicable app setting. Agents cannot change these settings or approve their own confirmation.

### Permanently delete from trash (`permanent_delete`)

Default: `false`. Scope: Private file tools; does not constrain separate administrator SSH access.

An operation also needs its individual agent grant and applicable app setting. Agents cannot change these settings or approve their own confirmation.

### Access expanded filesystem scope (`expanded`)

Default: `false`. Scope: Private file tools; does not constrain separate administrator SSH access.

An operation also needs its individual agent grant and applicable app setting. Agents cannot change these settings or approve their own confirmation.

## transfer

### Incoming file size (`max_file_bytes`)

Default: `8388608`. Scope: This node only; cannot override a remote owner.

A valid advisory may exceed download limits. Retrieval requires approval, applicable limits and free space.

Allowed range: 1–1099511627776 bytes.

### Incoming box size (`max_box_bytes`)

Default: `67108864`. Scope: This node only; cannot override a remote owner.

A valid advisory may exceed download limits. Retrieval requires approval, applicable limits and free space.

Allowed range: 1–1099511627776 bytes.

### Files per box (`max_box_files`)

Default: `50`. Scope: This node only; cannot override a remote owner.

A valid advisory may exceed download limits. Retrieval requires approval, applicable limits and free space.

Allowed range: 1–200 files.

### Transfer storage allowance (`storage_bytes`)

Default: `268435456`. Scope: This node only; cannot override a remote owner.

A valid advisory may exceed download limits. Retrieval requires approval, applicable limits and free space.

Allowed range: 1–1099511627776 bytes.

### WBsocial attachment size (`social_attachment_bytes`)

Default: `8388608`. Scope: This node only; cannot override a remote owner.

Limits stored social media; does not permit new media types or wall access.

Allowed range: 1–33554432 bytes.

### WBsocial attachments per post (`social_post_bytes`)

Default: `16777216`. Scope: This node only; cannot override a remote owner.

Limits stored social media; does not permit new media types or wall access.

Allowed range: 1–33554432 bytes.

### WBsocial storage allowance (`social_storage_bytes`)

Default: `268435456`. Scope: This node only; cannot override a remote owner.

Limits stored social media; does not permit new media types or wall access.

Allowed range: 1–1099511627776 bytes.

## security

### Automatic temporary IP blocks (`auto_block`)

Default: `true`. Scope: Public entrance.

Temporarily block repeated distinct denied public actions. An IP is not a verified person.

### Denied actions before a block (`denial_threshold`)

Default: `30`. Scope: Public entrance.

Distinct denied operations in a ten-minute window; ordinary identical retries are deduplicated.

Allowed range: 5–1000.

### Temporary block duration (`block_hours`)

Default: `24`. Scope: Public entrance.

Owner may review and remove blocks. Permanent blocks require an owner action.

Allowed range: 1–168.

## profile

### Public name (`display_name`)

Default: `"Wotbox"`. Scope: Public profile; does not change node identity.

The name published when profile visibility is public.

### Introduction (`description`)

Default: `""`. Scope: Public profile when enabled.

Owner-written introduction returned to visitors and public agents.

### Public profile (`profile_visibility`)

Default: `"private"`. Scope: Public page and get_profile.

Private shows a generic Wotbox profile; public publishes name, introduction and selected interests.

### Interests and subtopics (`topic_details`)

Default: `[]`. Scope: Profile visibility applies; also useful for private feed filtering.

Select system topics and write personal subtopics. New categories can be suggested to the community.

## appearance

### Theme (`theme`)

Default: `"serenity"`. Scope: Private desktop default appearance.

Select Serenity or Twilight.

### Presence (`presence`)

Default: `"online"`. Scope: Public presence and private notifications.

Busy tells visitors you are unavailable and suppresses routine communication notifications. Offline is detected, not selected.

## views

### Selected view per app (`selected`)

Default: `"default"`. Scope: Layer 3 of the selected app.

One selected appearance configuration per app. Required controls and core permissions remain enforced.

## sessions

### Multisession warnings (`multisession_warnings_enabled`)

Default: `true`. Scope: Owner sign-in sessions.

Notify when another session signs in.

### Approve additional sessions (`new_session_approval_required`)

Default: `false`. Scope: Owner browser access.

Hold an additional authenticated session for approval while another is active.

### Approve new browsers (`new_client_approval_required`)

Default: `false`. Scope: Owner browser access.

Hold an unfamiliar browser for approval while another session is active.

## agent_grants

### Allowed agent operations (`scopes`)

Default: `"Selected read operations"`. Scope: One agent or the browser-agent policy.

A browser or paired agent can invoke only its granted tools. App settings further restrict the operation.

### Allowed destinations (`destinations`)

Default: `[]`. Scope: One paired-agent grant.

A nonempty list limits scoped outbound actions to the listed nodes or contacts.

### Agent grant lifetime (`expires_at`)

Default: `"Owner selected"`. Scope: One paired agent; not independent SSH.

Leases cannot exceed the grant expiry; revocation invalidates use.

## relationships

### Relationship permission matrix (`permissions`)

Default: `"Beta matrix"`. Scope: Incoming actions from accepted connections.

Acquaintance, friend, family and close family have independent checkboxes. Per-person overrides and space permissions also apply. No setting grants ownership.

### WBchatterbox (`chatterbox`)

Default: `{"acquaintance":true,"friend":true,"family":true,"close-family":true}`. Scope: Incoming authenticated peer actions; per-person settings may override defaults.

Send instant messages; the first-message gate may still require approval.

### WBpostbox (`postbox`)

Default: `{"acquaintance":true,"friend":true,"family":true,"close-family":true}`. Scope: Incoming authenticated peer actions; per-person settings may override defaults.

Offer and retrieve accepted-contact mail. Automatic retrieval is a separate per-contact setting.

### File exchange (`files`)

Default: `{"acquaintance":true,"friend":true,"family":true,"close-family":true}`. Scope: Incoming authenticated peer actions; per-person settings may override defaults.

Offer or retrieve files subject to explicit approval, storage and download limits.

### Private-wall contributions (`private_posts`)

Default: `{"acquaintance":false,"friend":false,"family":false,"close-family":false}`. Scope: Incoming authenticated peer actions; per-person settings may override defaults.

Contribute a post without obtaining read access to the entire private wall.

### Read group walls (`group_read`)

Default: `{"acquaintance":true,"friend":true,"family":true,"close-family":true}`. Scope: Incoming authenticated peer actions; per-person settings may override defaults.

Read a group wall only with explicit group membership.

### Comment in groups (`group_comment`)

Default: `{"acquaintance":false,"friend":true,"family":true,"close-family":true}`. Scope: Incoming authenticated peer actions; per-person settings may override defaults.

Comment only where group membership also permits it.

### Post to groups (`group_post`)

Default: `{"acquaintance":false,"friend":false,"family":true,"close-family":true}`. Scope: Incoming authenticated peer actions; per-person settings may override defaults.

Contribute only where group membership also permits it.

## contacts

### First-message permission (`im_gate`)

Default: `"pending"`. Scope: One accepted contact.

Acquaintances can have their first chatterbox message held for explicit approval.

### Automatic text mail (`mail_auto_download`)

Default: `false`. Scope: One accepted contact.

Retrieve text-only WBpostbox automatically for this accepted contact. Files still require download approval.

### Private-wall posting (`social_private_post`)

Default: `false`. Scope: One accepted contact.

Explicit permission to contribute a post to your private wall; does not reveal the whole wall.

## social

### WBsocial name (`display_name`)

Default: `"Wotbox owner"`. Scope: WBsocial attribution.

Name attached to social contributions.

### Interaction address visibility (`address_visibility`)

Default: `"author"`. Scope: WBsocial likes and comments.

The post author sees your address after a like/comment; everyone sees it only when selected.

### Allow reposting (`allow_repost`)

Default: `false`. Scope: One post.

Allow attributed reposts of this post.

### Advertisement (`advertisement`)

Default: `false`. Scope: One post.

Identify promotional content as advertising.

### Ask why they liked it (`ad_feedback`)

Default: `false`. Scope: One advertisement.

Offer brand, entertainment, knowledge and product reasons for likes on an advertisement.

### Feed interest mode (`feed_mode`)

Default: `"all"`. Scope: Current wall selection.

Show all posts, matching topics only, or matching topics first.

### Keep video (`keep_asset`)

Default: `false`. Scope: One stored video.

Retain an accessible video on this droplet; otherwise it expires after seven days and spends two days in trash.

## groups

### Group member permission (`permission`)

Default: `"No membership"`. Scope: One person in one group.

Explicit group membership grants read, comment or contribute access, subject to owner relationship restrictions.

### Family group (`family`)

Default: `false`. Scope: One group wall.

Restrict family-group content and videos to eligible family connections.

## host

### Public node URL (`url`)

Default: `"Chosen at installation"`. Scope: This installation.

Canonical HTTPS address supplied by the installer owner; changing an established identity requires migration.

### Private dashboard alias (`dashboardPath`)

Default: `null`. Scope: This installation and its nginx route.

Optional separate private dashboard path; authentication is still required.

### Local service port (`port`)

Default: `"Installer selected"`. Scope: This installation.

Loopback service port proxied by nginx.

### Private data directory (`dataDir`)

Default: `"Instance-specific"`. Scope: This installation.

Stores this node’s private identity, messages, files and settings; never copied into packages.

### Host recovery account (`recoveryUser`)

Default: `null`. Scope: Host administration.

Optional authorized OS account used for explicit host-password recovery.

### Public social hub (`socialHubUrl`)

Default: `"https://wotbox.fun/"`. Scope: Public social federation.

Shared WBsocial public-feed address. It is not the owner’s private feed.

### Host a public hub (`socialHub`)

Default: `false`. Scope: Host administration.

Enable hub services; regular friend installations are not hubs.

### Community host (`communityEnabled`)

Default: `false`. Scope: Host administration.

Enable community/forum hosting; off for regular installations.

### Entrance edge log (`entranceEdgeLog`)

Default: `"Instance-specific"`. Scope: Private security reporting.

Read rejected nginx requests into WBlogbox. Successful routine presence checks are excluded.

## logging

### Entrance retention (`retention`)

Default: `"30 days known / 90 days other"`. Scope: Private WBlogbox storage.

Known means locally recorded verified identity or owner. Counts do not prove malicious intent. Bounded at 50,000 events.

## Enforcement and installation

Layer 1 checks permissions on every human/API/agent operation. Agent options cannot restrict an independent SSH or OS administrator connection. Existing OS ownership and service isolation still apply; the browser does not acquire root privileges when scope is expanded. Disabled Save controls are presentation, not the security boundary.

The installer uses the destination owner's URL, a fresh node key and independent sign-in. Regular installations do not host the central forum or social hub. No example identity, private messages, logs, contacts or files are seeded. Upgrades retain the existing owner's choices rather than overwriting them with defaults.

The transfer implementation uses 256 KiB chunks and verifies SHA-256. WBsocial media currently supports up to 32 MiB per attachment/post as a bounded transport ceiling; owners choose lower limits independently. Public video remains disallowed. A download advisory may exceed the recipient's retrieval settings.