Host settings

These operations require a device paired with --manage-host. Ordinary pairing already permits workspace work. Host management adds authority over this machine's configuration and connected devices.

Prefer Workspace settings in Fluso for interactive setup. Use this API when your client needs to manage the same settings.

Read, save, then apply

Saving settings does not apply them to the running sandbox.

Read GET /daemon/v1/settings and GET /daemon/v1/sandbox.
Keep each response's revision.
Save the change with that resource's expectedRevision.
Keep the new revisions returned by the saves.
Apply both revisions with POST /daemon/v1/apply.
Read discovery and runtime status to check the outcome.

For example, change the model while keeping the existing provider and key:

{
  "expectedRevision": "SETTINGS_REVISION_FROM_READ",
  "settings": {
    "FLUSO_MODEL": "MODEL_ID_SUPPORTED_BY_YOUR_PROVIDER"
  }
}

Send that body to PATCH /daemon/v1/settings. Omitted fields remain unchanged. null clears a field. Returned secrets are presence flags, not key values.

Apply the saved revisions with:

{
  "settingsRevision": "SETTINGS_REVISION_FROM_SAVE",
  "sandboxRevision": "SANDBOX_REVISION_FROM_READ",
  "interrupt": false
}

A 409 INTERRUPTION_REQUIRED means active work would be interrupted. Ask the owner before repeating with interrupt: true.

Change the provider or sandbox

For an OpenAI-compatible endpoint, set FLUSO_PROVIDER: "custom", OPENAI_BASE_URL, FLUSO_MODEL, and OPENAI_API_KEY. Include /v1 in the base URL when the provider requires it. Other provider choices are openrouter, openai, and pcci.

A saved key stays tied to its endpoint. Enter a key again when changing that destination. Audio has separate provider and key settings. The daemon's schema lists every supported setting.

Sandbox changes use PUT /daemon/v1/sandbox with expectedRevision and the complete config. Preserve all intended hostFiles grants. An empty list removes shared-folder access.

Host paths refer to the daemon's machine, even when you connect remotely. Grant only the required folders. Writable grants permit changing or deleting the original host files. Workspace /v1/files paths do not grant access to arbitrary host paths.

Management endpoints and recovery

Method and path	Use
`GET /daemon/v1/settings`	Read saved provider settings and their revision.
`PATCH /daemon/v1/settings`	Save changed fields. `preview: true` validates without saving.
`GET /daemon/v1/sandbox`	Read configuration, revision, host RAM, and disk budgets.
`PUT /daemon/v1/sandbox`	Replace the sandbox configuration with revision protection.
`POST /daemon/v1/apply`	Apply the saved settings and sandbox revisions.

Sandbox config contains runtimeProfile, hostFiles, memoryGiB, and diskGiB. RAM is the VM allocation. Disk is the combined saved-work and temporary-work budget. It excludes images, backups, and shared host folders. Existing workspace data must fit a smaller budget before you apply it.

On 409 CONFIGURATION_CONFLICT, reload both resources and review the newer changes. Do not substitute a fresh revision without reviewing them.

During an update or apply, workspace routes can return 503 with Retry-After. Discovery shows applying or configuration_error where applicable. Resolve a configuration error before resubmitting work. A 423 locked credential store requires recovery on the host.

Discovery exposes saved and applied revisions and restartRequired to host-authorized clients. After a lost apply response, read those values before another apply.

Binary updates, backups, and credential-store recovery use the daemon CLI. The settings API does not replace those operations.

Host settings

Read, save, then apply

Change the provider or sandbox

On this page