# Local FX service **Status: ratified and implemented, 2026-10-08; released in 0.2.0; verified offline.** The local FX service gives one project a stable loopback address, an index of recorded runs and saved plans, and the embedded browser client. Workflow execution remains owned by its invoking process. Both the service and independent observers read the existing [observation contract](observation.md). ## 1. Command vocabulary The installed command is `grida-fx` (or `python -m grida.fx`). `fx` in product discussion is shorthand, not a newly installed executable alias. | Command | Responsibility | |---|---| | `init [DIRECTORY] [--template NAME] [--json]` | Start a new project from the built-in starter or a named template, or validate an existing `fx.yaml`. | | `init --list-templates [--json]` | List the templates `init` can start from and identify the starters accepted by `add`. | | `add NAME [DESTINATION] [--json]` | Install an editable copy of a named starter project in a new directory. | | `start [--project DIRECTORY] [--port N] [--background] [--open] [--json]` | Start the local FX service; foreground by default. | | `status [--project DIRECTORY] [--json]` | Inspect the selected project's service using an identity/compatibility handshake. | | `stop [--project DIRECTORY] [--json]` | Stop only the selected service; preserve runs, plans, cache and configuration. | | `logs [--project DIRECTORY] [--lines N]` | Print a bounded tail of the service's local log. | | `run TARGET [--open] [--standalone]` | Execute; announce a usable run URL when inspection is available. | | `plan TARGET [--open] [--standalone]` | Plan without run-phase execution; optionally inspect the materialized graph. | | `inspect RUN [--open] [--standalone]` | Inspect an existing record, optionally in the browser. | `view` remains a hidden compatibility command for independent foreground viewing of source targets, saved plans and saved runs. New onboarding uses the commands above. No service command executes workflow source or loads provider credentials. Browser opening is explicit through `--open`; browser failures never change the result of workflow execution. JSON inspection/planning output conflicts with browser flags that would mix a URL into machine-readable stdout. ## 2. Projects and standalone operation Existing project discovery is authoritative: the nearest `fx.yaml`, or the resolved starting directory with documented defaults if there is no project file. The planning project owns the run catalog, not an imported workflow's home. `init` is recommended onboarding, not a prerequisite for execution or serving. Service commands can select their discovery directory with `--project`. The owning project's optional `viewer.display` settings define canvas defaults for its plans and runs ([viewer.md](viewer.md#project-display-settings)). They are read for viewing, not captured into executable plans. An existing recording therefore adopts current display settings when opened or refreshed, without a new run. Imported workflow homes do not override the service project's display choices. In a directory that is missing, or empty but for `.git` and `.DS_Store`, `init` starts a project. Without `--template` it writes the **starter** embedded in the engine, in this order: `fx.yaml`, `README.md`, `AGENTS.md`, `.gitignore`, `.env.example` and `workflows/icon.yaml`, then every agent skill of the repository's `skills/` (each folder there holding a `SKILL.md`) under `.agents/skills//`, as `npx skills add gridaco/fx` installs them. The engine embeds the skills of the commit it was built from. `AGENTS.md` points agents at the skills and the published `llms.txt`, and asks them to give the user the live viewer's URL while the service runs. The starter sets no route: its one paid step plans as refused until the user picks a provider, and its README says how to install the CLI and connect one. A directory that already holds `fx.yaml` is validated and left as it is: nothing is written, whatever starter files it lacks, and `--template` is refused there (exit 2). Any other non-empty directory is refused (exit 2) and left untouched; a user adds FX to an existing folder by writing `fx.yaml` themselves. `init` never overwrites a file, installs dependencies, loads credentials, starts a server or executes a workflow. Repeating it on an existing valid project configuration is safe. Invalid existing configuration is reported rather than repaired or overwritten. `init` asks nothing unless it would start a project, neither `--template` nor `--json` is given, standard input and output are both terminals, and `CI` is unset. Then it lists the templates and reads a choice; an empty answer is the starter. Agents and scripts never see the question. ### 2.1 Templates A **template** is an example of the FX repository offered as a starting point. The engine embeds the index `examples/templates.json` of the commit it was built from: each entry has a `name` (`[a-z0-9-]+`, unique, not `starter`), a one-line `description`, the `provider` its AI steps use (`none`, `codex`, `gg`, or `any` when the user picks) and its `path`, a folder under `examples/`. `init --list-templates` lists `starter` first, then the index in order; with `--json` it prints [an `fx-project-templates-v1` document](schemas/fx-project-templates-v1.schema.json). Listing reads nothing but the engine. An unknown `--template` is refused before anything is read or sent, naming the templates. `--template starter` is the built-in starter. Any other template's files come from the FX release the engine belongs to: `https://codeload.github.com/gridaco/fx/tar.gz/v`, the tag's gzip-compressed tar archive, whose entries lie under one top-level folder. The download and the bounded read-only model lookups in [model-selection.md](model-selection.md) §3 are the engine's network exchanges outside a live run's provider calls. The template download goes through the providers' default transport on its download lane ([adapters.md](adapters.md) §2): no credential, no cookie, the environment's proxies, no redirect followed and no retry. Anything but HTTP 200 is refused, naming the status, as is a body over 64 MiB. With `GRIDA_FX_NETWORK=off` it is refused before anything is sent. For development and tests, the hidden option `--template-source SOURCE` replaces the release archive: a directory (a checkout of the repository, whose `` is read directly), a `.tar.gz` file, or an `http(s)` URL of one (plain `http` only to a loopback host). A directory source skips `.git`, `.fx`, `runs`, `.venv`, `node_modules`, `__pycache__`, `.showcase-inputs` and `.env` wherever they occur, so that it yields what the archive would. Only entries under `//` are read; the rest of the archive is skipped unread. Within the template, the installer refuses: - a path that is absolute or holds `..`, or an entry that is a symbolic or hard link, a device or a FIFO; - more than 1000 files, or more than 32 MiB unpacked; - entries under more than one top-level folder; - a template folder that is missing from the archive, or holds no `fx.yaml`. The template is unpacked into a hidden temporary folder. The starter's `AGENTS.md`, `.env.example` and `README.md`, and each skill file under `.agents/skills/`, are added where the template has none. A template's own `.gitignore` keeps its lines and gains each line of the starter's it lacks; without one, it gets the starter's. `init` stages inside its target before moving the files into place. Nothing from a template is executed. **Installing with `add`.** An index entry with a `starter` declaration is available to `add`. It names a YAML `workflow_entry`, optionally a bundled `inputs_file`, any `required_inputs` paths checked for presence, and human-readable `prerequisites` for using the starter. Paths are relative to the new project. `init --list-templates --json` exposes `workflow_entry`, `inputs_file` when declared, and `prerequisites` on eligible entries. The built-in starter remains available through `init`. `add` defaults to `./NAME`. A supplied destination is the exact new project directory, relative to the working directory or absolute. Its parent must already be a directory. An existing directory, file, or link at the destination is an error (exit 2). The parent may contain an FX project. The installed copy owns its own `fx.yaml` and project settings. `add` never merges into the parent. `add` shares the release source, network rules, extraction limits, agent files, and hidden test source with `init`. It stages the source beside the destination, validates the staged `fx.yaml` and the declared YAML workflow entry, and verifies the bundled preset file when one is declared. Missing declared user-supplied inputs are reported on success. Prerequisites are declarations. The installer does not probe them, launch code, install dependencies, load credentials, or consult providers. It publishes the finished directory with one exclusive rename. If two installs target the same path, at most one publishes and the other fails. Template inputs in the source tree are copied as files. Canonical runs and downloads of separately hosted input or output files are outside this operation. With an explicit project, ordinary `run` registers the initialized record and uses a compatible running service if present. It does not implicitly start a background process. If the service is absent, execution still proceeds; `--open` reports how to start the service. `plan --open` and `inspect --open` also require the selected project's service and do not start it implicitly. `--standalone` explicitly selects the independent foreground inspection model, including inside a project. It changes serving lifetime, not workflow resolution, routes, budgets, cache identity or cache reuse. A projectless `run` retains this independent model by default. A projectless `plan --open` or `inspect --open` serves its selected data independently. Ordinary planning/inspection without browser or standalone flags does not host a server. For standalone execution, the server uses an available port and ends with the invocation. Standalone saved-run/plan viewing remains foreground until interrupted. The compatibility `--no-view` flag skips run viewer integration and conflicts with `--open`; SDK run methods continue to use it. It does not suppress records. ## 3. Service lifetime and readiness The foreground process owns the service. `start --background` launches the same native executable independently, directs its output to a private log, and returns only after a bounded readiness handshake. A matching already-running background start is idempotent. Parallel starts are serialized by a lifetime-held OS file lock; a PID file alone is not proof of ownership or liveness. Readiness means the server is bound, its local identity and protocol are checked, and the reported URL is usable. Output describes the actual project, service instance and address. Failure to bind, incompatible existing service or readiness timeout is an explicit startup failure. An explicit occupied port is never silently replaced with a random one, and another project's service is never reused. A failure to bind names the port and the next step: an occupied port reads `port N is in use; choose another with --port N`, and a port the user may not bind reads `port N is not permitted for this user; choose another with --port N`. A background start whose service exits before readiness reports that service's cause in one line, `FX service could not start: CAUSE`. Each attempt chooses a tag, 16 random lowercase hex characters, and passes it in the service's environment (`GRIDA_FX_SERVICE_ATTEMPT`); a service started with a tag writes its error line as `: attempt : CAUSE`. The cause is the last error line carrying this attempt's tag that the service wrote to the private log after the attempt began; lines an earlier attempt left, and a concurrent attempt's, are never reported as this attempt's cause. The tag names nothing private. A service that exits without such a line, or a readiness timeout, says so and points to `logs`. With `--json`, a failed background start still prints a `stopped` status document whose `cause` member carries the same cause, and the command exits 2. Whether another project's FX service holds the port is not reported: no machine-wide registry names it. The default port is 8787 on `127.0.0.1`. `--port` selects an exact nonzero port; its successful selection is retained in private local service state across stops. The OS does not reserve a stopped service's port. A second project may choose a different port explicitly. Only one instance may own a given project's service. `stop` uses authenticated local control, not an unchecked PID signal. It is idempotent for a stopped service and waits at most ten seconds for shutdown. The server allows two seconds for active HTTP responses to drain, then closes remaining connections; local runtime cleanup is also bounded. Stopping the service never cancels workflow processes. The service neither schedules nor resumes a workflow after a crash. Clients may reconnect and replay recorded events. The [run-control contract](control.md) defines the separate, runner-owned cancellation interface. Its private discovery works without this service; neither service shutdown nor a browser read is a cancellation request. Background means detached from the invoking command and terminal. Automatic crash restart, login/boot activation, system-level installation, cross-user access and machine-wide project aggregation are not part of this first contract. Native OS supervision can later wrap the same foreground server without changing run events. ## 4. Local catalog and URLs Private service state lives under the selected project at `.fx/service/`, outside portable run records. It includes service ownership/readiness information, saved port preferences, a catalog, saved materialized plans and diagnostic logs. Log reads are bounded to 1 MiB; retained lifecycle logs over that size are reset on the next background start. Directories and files use private user permissions on Unix. Symlink escapes from this directory are refused. Absolute source paths and the control credential are local implementation data; they never enter portable run/plan/event documents, browser catalog responses, URLs or public logs. Each catalog entry has an opaque local ID and one of these routes: ```text / project index /p/PROJECT_ID/runs/RUN_ID/ recorded run /p/PROJECT_ID/plans/PLAN_ID/ materialized plan ``` Project identity distinguishes canonical local project roots. Moving a project changes its local identity; this is not a portable project identity scheme. A run entry binds a canonical run folder and its initial recorded identity, so resuming the same record preserves its URL while replacing it is not mistaken for the earlier run. An invocation ID alone or plan digest alone is not a run ID. The same plan may have several runs. Saved plans are immutable materializations; the service never imports workflow code to refresh them. The catalog supports default project runs and explicitly registered `--run` locations. Discovery is bounded to the configured run storage, not a scan of a project's source tree or the machine. Registration is through local CLI filesystem operations; web requests cannot register arbitrary paths. Missing or changed records are surfaced without silently pointing an old URL at different data. `grida-fx runs remove` ([store.md](store.md) §9) is the one local operation that deletes run entries: once it has removed a run folder it deletes the entries binding that folder and its recorded identity, and their URLs are then not found. A folder removed any other way stays listed as unavailable. Other tools read the catalog's run entries without opening it, so reading never creates or registers anything. The catalog persists independently of server uptime. Registered runs remain discoverable if they finish while the service is stopped. A restarted service rebuilds presentation from retained records; it does not store another execution state machine. Recorded `running` state is not evidence of process liveness. ## 5. HTTP boundary The existing loopback host, Origin and fetch-site checks apply to all routes. `GET /api/view` and `GET /api/catalog` at the service root return a `fx-service-index-v1` document with `project_id`, `title`, and `entries`. Each entry contains `id`, `kind` (`run` or `plan`), `title`, a relative `url`, and display state. Neither filesystem locations nor the service's control credential are exposed. New entries also expose `workflow: {id, source}`, `created_at` (UTC RFC3339), and an optional run `name`. `source` is the exact portable `workflow.file` recorded in the graph, including a builder selector when present; it is not a private absolute path. Unsafe or missing source metadata is omitted, not guessed from a title. Run creation time/name come from the first `run_started`; legacy run times use the unchanged plan file's modification time. A saved plan's creation time is its first catalog registration; registering it again or restarting preserves that time. Unavailable records retain recorded presentation metadata where available. These fields affect neither execution/cache identities nor scoped run URLs. Readers accept older entries lacking this optional metadata. The index groups by project identity plus recorded workflow ID and source. It does not group by title or plan digest: changed inputs/definitions at one source stay in one workflow, while different sources with the same ID remain distinguishable. Entries without sufficient workflow metadata remain separate. The main workflow row opens the newest-created run, including failures, or a saved plan when no run exists. Expandable history includes names, creation times and states, with saved plans in the same group. Older recorded running/unfinished runs remain visible without opening history; recorded state still does not prove process liveness. Resuming never promotes an old run as a new one. Under a selected entry route, `/api/view`, `/api/snapshot`, `/api/events`, and `/api/artifacts/DIGEST` retain their existing contracts and validation. Plans have no run observation or artifact bytes. Artifact URLs are confined to the selected entry. A wrong project or entry ID returns an error, never the current project's unrelated run. Browser readers use explicit scoped API bases and reject URLs outside that scope. The standalone root API remains supported. `GET /api/viewer_config` under the selected entry returns the owning project's current resolved display settings ([viewer.md](viewer.md#project-display-settings)), with `Cache-Control: no-store`. It contains no paths, credentials or other project fields. Standalone inspection serves the same response for its explicitly selected project context. `GET /api/files` under the selected entry returns the portable recorded file inventory defined by [files.md](files.md), with `Cache-Control: no-store`. Standalone inspection serves the same inventory. It contains scoped artifact URLs and safe source references, never source-code bytes or absolute local paths; filesystem resolution is a separate native-caller operation. A scoped `GET /api/layout` returns the selected run's or plan's canvas layout report ([layout.md](layout.md) §6.11) with `Cache-Control: no-store` and no `ETag`, since the report changes as a run records more while the layout file stays the same. The standalone root serves the same report at `/api/layout`, and a run's `/api/snapshot` carries the report of its prefix as `layout`. The report carries automatic cells only. With the layout file ([layout.md](layout.md) §6, not implemented), the service derives the file's location from the recorded `takes_file` alone; a request never names a path. A `takes_file` that is not a plain relative path inside the project, or a location reached through a symbolic link that leaves it, is not read: the report says so with a diagnostic and carries automatic cells. Reading the report executes nothing and changes no record. The service identity endpoint, `GET /api/service`, and shutdown endpoint, `POST /api/service/stop`, require the private local Bearer control credential. Successful identity responses name `fx-service-status-v1`, `protocol_version: 1`, `state: running`, `project_id`, `instance_id`, `pid`, and the actual `url`. CLI discovery verifies the expected instance, project and protocol before reuse. Tokens are not passed on command lines or shown to browsers. This control boundary does not authorize execution, credential access or arbitrary filesystem reads. The wire and CLI result schemas are [catalog](schemas/fx-service-index-v1.schema.json), [status](schemas/fx-service-status-v1.schema.json), [initialization](schemas/fx-project-init-v1.schema.json), [templates](schemas/fx-project-templates-v1.schema.json), and [shutdown acknowledgment](schemas/fx-service-stop-v1.schema.json). `status --json` always returns a status document for an accessible project: `running` exits 0; `stopped`, `unavailable`, and `incompatible` exit 1. Invalid configuration or unreadable local state remains a command error (exit 2). A stopped status has null `instance_id`, `pid`, and `url`. Failed handshakes also leave those fields null instead of presenting unverified service data. Only a failed `start --background --json` adds `cause`, a one-line sentence (§3); readers ignore members they do not know. `init --json` lists every file it wrote in `files_created`, relative and `/`-separated, and names the template it started from (`template`: its `name` and `source`, `built_in`, `release` or `local`), or `null` when it started nothing. It includes the local absolute `project_root`; this is local command output rather than a portable workflow record. `add --json` uses the same result kind on success, with `created: true`, the installed `template`, and the extra members `workflow_entry`, `inputs_file` when declared, `missing_inputs` and `prerequisites`. File paths other than `project_root` are project-relative and `/`-separated. `missing_inputs` and `prerequisites` are arrays and may be empty. `stop --json` returns the final status document, whereas its private HTTP endpoint acknowledges `stopping` before shutdown completes. ## 6. Verification and delivery The acceptance harness uses only synthetic images and bounded local waits. [`service.rs`](../crates/grida-fx/tests/service.rs), [`service_run.rs`](../crates/grida-fx/tests/service_run.rs), and [backend tests](../crates/grida-fx-viewer/src/service/tests.rs) exercise init preservation; foreground/background readiness; parallel/idempotent startup; port conflicts; authenticated and project-scoped status/stop; multiple runs and a plan; scoped artifact bytes; completion after CLI exit; service restart with stable URLs; execution while the service is absent/stopped; standalone execution; and SDK capture compatibility. No paid provider, Docker, remote worker or real browser opener is required in automated tests. An actual browser check must additionally demonstrate multiple run navigation, live step changes and completed-run inspection after the producing command exits.