fabro/docs/plans/2026-04-06-cli-config-socket-storage-separation-plan.md

CLI Config, Socket, And Storage Separation

Summary

Separate machine config, server target, and server storage so the CLI no longer conflates:

• config path: ~/.fabro/settings.toml
• default socket target: ~/.fabro/fabro.sock
• default storage dir: ~/.fabro/storage

Normal user-facing commands should always talk to a server target. A Unix socket target may auto-start the daemon. An HTTP target may not. Serverless/direct-storage command behavior should be removed from normal commands in this pass.

Scope Boundaries

In scope:

• add FABRO_CONFIG support for machine settings loading
• default the server target to ~/.fabro/fabro.sock
• default server storage to ~/.fabro/storage
• decouple socket-path resolution from storage-dir resolution
• keep daemon auto-start only for Unix socket targets
• remove normal-command fallback to direct storage-based targeting
• keep fabro server *, hidden fabro __runner, and fabro install as storage-owning commands
• keep user-facing --server on server-targeted commands
• remove user-facing --storage-dir from server-targeted commands

Out of scope:

• fabro exec
• fabro system df
• fabro system prune
• fabro store dump
• new remote maintenance endpoints for deferred commands

Problem Frame

The current CLI still mixes together two different ideas:

• a local daemon reached over a Unix socket
• serverless behavior where the CLI uses storage_dir as the command target

That has produced the wrong defaults and the wrong abstractions:

• the socket path is currently derived from storage_dir
• many commands still model targeting as "server or storage dir"
• normal commands can still fall back to a storage-driven local connection shape
• autostart is keyed off the local/storage connection path instead of the actual server target type

The intended model is simpler:

• normal commands always resolve a server target
• the default server target is a Unix socket in ~/.fabro
• Unix socket targets may auto-start a daemon
• HTTP targets may not auto-start a daemon
• storage is server-owned runtime state, not the primary targeting mechanism for normal commands

Key Decisions

• FABRO_CONFIG selects the active machine settings file.
  • For server lifecycle commands and daemon auto-start, precedence is: explicit --config where supported, then FABRO_CONFIG, then ~/.fabro/settings.toml.
  • Normal user-facing commands do not gain a new --config flag in this pass; they resolve settings from FABRO_CONFIG or the default path.
• FABRO_SERVER selects the effective server target for normal commands.
  • It accepts either an absolute Unix socket path or an http(s) URL.
  • If unset, use settings.server.target.
  • If that is unset, default to ~/.fabro/fabro.sock.
• Server-targeted commands keep --server as the standard one-off override.
  • FABRO_SERVER remains the env-var equivalent.
• FABRO_STORAGE_DIR is no longer a normal command-targeting mechanism.
  • It remains an override for storage-owning commands only.
  • Precedence for storage-owning commands: explicit --storage-dir where still supported, then FABRO_STORAGE_DIR, then settings.storage_dir, then ~/.fabro/storage.
• settings.server.target remains the durable place to configure the machine's server target.
• settings.storage_dir remains the durable place to configure where the local server stores data.
• fabro server start keeps --config and --bind.
  • Its default bind is ~/.fabro/fabro.sock, not <storage_dir>/fabro.sock.
• fabro server stop and fabro server status remain storage-owning commands and continue to resolve the local server instance from storage-owned records.
• fabro settings is a local config-inspection command, not a server-targeted command.
  • It keeps its current local settings-resolution behavior in this pass.
• fabro exec is unchanged in this pass.

Command Classification

Storage-owning commands

These commands continue to resolve and use local storage directly:

• fabro server start
• fabro server stop
• fabro server status
• hidden fabro server __serve
• hidden fabro run __runner
• fabro install

Local config-inspection commands

These commands stay outside the server-targeting cleanup in this pass:

• fabro settings

Server-targeted commands

These commands should resolve a ServerTarget only and should not use storage-dir fallback semantics:

• fabro run
• fabro create
• fabro preflight
• fabro validate
• fabro graph
• fabro model list
• fabro model test
• fabro doctor
• fabro repo init
• fabro provider login
• fabro secret list
• fabro secret rm
• fabro secret set
• fabro ps
• fabro rm
• fabro inspect
• fabro run start
• fabro run attach
• fabro run logs
• fabro run resume
• fabro run rewind
• fabro run fork
• fabro run wait
• hidden fabro run diff
• fabro artifact list
• fabro artifact cp
• fabro sandbox cp
• fabro sandbox preview
• fabro sandbox ssh
• fabro pr create
• fabro pr list
• fabro pr view
• fabro pr merge
• fabro pr close

Deferred local-maintenance commands

These remain unchanged in this pass:

• fabro system df
• fabro system prune
• fabro store dump

These deferred commands continue to use StorageDirArgs and the existing hybrid ServerRunLookup::connect(storage_dir) path in this pass, and should keep working against the new default storage dir without being reclassified as server-targeted commands yet.

Implementation Changes

1. Shared settings and path resolution

• Add a shared helper for the active settings path used by CLI and server code.
  • This helper must honor FABRO_CONFIG.
• Add a shared helper for the default socket path: ~/.fabro/fabro.sock.
• Change the default storage dir helper to return ~/.fabro/storage.
• Stop deriving the socket path from storage_dir.

2. Target resolution model

• Refactor CLI target resolution so normal commands resolve a ServerTarget, not a "local vs target" union.
• Remove ServerConnection::Local as a normal command-routing concept.
• Split helpers into two categories:
  • server-target resolution for normal commands
  • storage-dir resolution for storage-owning commands
• Keep TLS handling attached to HttpUrl targets exactly as today.

3. Connection and auto-start behavior

• Update the server client helpers so they accept or derive a ServerTarget.
• If the resolved target is UnixSocket(path):
  • attempt to connect to that socket
  • if unavailable, auto-start the daemon
  • auto-start the daemon bound to that exact socket path
• If the resolved target is HttpUrl(url):
  • attempt to connect once
  • if unavailable, fail with a clean reachability error
  • do not auto-start anything
• Auto-start must pass the active config path through to the spawned server with --config.
• The auto-start helper should take the resolved active config path, resolved Unix socket path, and resolved local storage dir as explicit inputs.
  • It should not rediscover config via environment variables or reload settings internally during daemon launch.
• Auto-start may also pass the resolved storage dir for the local server process, but only as runtime/server lifecycle plumbing, not as the command target abstraction.
• Any active-server record lookup used by server stop, server status, install, or daemon auto-start should temporarily fall back to the legacy implicit storage root ~/.fabro when no explicit storage location is provided and no record exists under the new default ~/.fabro/storage.
  • This is only to find already-running daemons started before the default-storage change.

4. CLI arg surface cleanup

• Keep user-facing --server on all server-targeted commands listed above.
• Remove user-facing --storage-dir from all server-targeted commands listed above.
• Remove the storage_dir_explicit conflict plumbing for those commands.
• Remove the custom --server / --storage-dir conflict detection in main.rs once no supported command still accepts both flags together.
• Keep --storage-dir only on storage-owning commands in this pass.
• Keep --config only where already appropriate for server lifecycle.
• Update help text and parser tests so normal commands still advertise --server but no longer imply that storage-dir is a general targeting control.

5. Run/create local run-dir handling

• run / create currently thread a synthesized local run dir through the result object to print asset paths after completion.
• Preserve that behavior only when the effective target is the machine's local Unix socket and the effective local storage dir is known.
• For HTTP targets, do not synthesize a local run dir.
• This should be derived from "effective target is local socket" plus resolved storage dir, not from a ServerConnection::Local enum variant.

6. Docs and user-visible messaging

• Rewrite docs and examples so:
  • normal commands use config-driven target resolution by default
  • temporary overrides use FABRO_SERVER=... fabro ...
  • config-file overrides use FABRO_CONFIG=... fabro ...
• Update language to avoid "local mode" as a user-facing concept.
  • Use "Unix socket target" or "HTTP target".
  • Use "serverless" only for the behavior being removed.
• Make doctor and settings print:
  • active config path
  • effective server target
  • effective storage dir
  • any active env-var overrides

Test Plan

• Unit tests for path and precedence helpers:
  • active config path honors FABRO_CONFIG
  • default socket path is ~/.fabro/fabro.sock
  • default storage dir is ~/.fabro/storage
  • FABRO_SERVER overrides settings.server.target
  • FABRO_STORAGE_DIR overrides settings.storage_dir for storage-owning commands only
  • FABRO_CONFIG=/custom/path/settings.toml loads that file's contents and the resolved server.target / storage_dir from that file actually take effect
• Unit tests for target resolution:
  • normal commands default to a Unix socket target when nothing is configured
  • normal commands no longer resolve a storage-dir fallback connection
  • HTTP targets never route into autostart code
• Integration tests for daemon behavior:
  • fabro server start defaults to binding ~/.fabro/fabro.sock
  • auto-start for socket-targeted commands binds the requested socket, not <storage_dir>/fabro.sock
  • auto-start passes the active config path through to the daemon
  • HTTP-targeted commands fail cleanly when unreachable
  • server stop / server status still find an already-running daemon whose record lives under the legacy implicit storage root
• Parser/help tests:
  • server-targeted commands still accept --server
  • server-targeted commands no longer accept --storage-dir
  • storage-owning commands still accept --storage-dir where intended
  • fabro settings keeps its existing local settings override surface in this pass
• Workflow behavior tests:
  • run, create, model, doctor, ps, and secret work via the default socket target
  • local Unix socket runs still print local asset/run-dir info when appropriate
  • HTTP-targeted runs do not print synthesized local run-dir paths

Assumptions

• This is a hard cut for CLI targeting semantics. No deprecation period for removed normal-command flags.
• FABRO_SERVER is the single override for user-facing command targeting; no separate FABRO_SOCKET env var is added.
• server.target remains the canonical durable target field in settings.toml.
• Deferred commands will be handled in a later pass rather than forced into this refactor.