简体中文 · Website · README · Security
This guide describes the Floe Agent 1.4.50 source target (build 81). Labels may vary slightly with the system language and configured provider. Distribution status must still be verified in TestFlight; a source tag is not an Apple processing receipt.
This guide includes the current development-branch workflow upgrade. See scope, screenshots and outstanding validation; release availability is verified separately.
Use TestFlight when a testing invitation is available. If you use the community unsigned IPA, verify its SHA-256 and provenance, inspect the source, and sign it with your own certificate. Never import a certificate, API key, SSH key, or provisioning profile supplied by an unknown distributor.
Floe Agent requires iOS or iPadOS 26 or newer. iPad is recommended for file review, browser takeover, terminal work, and multi-column inspection.
- Open Settings from the bottom of the sidebar.
- Open Model Providers and add a compatible endpoint.
- Enter the endpoint, wire protocol, model identifier, and API credential required by that provider.
- Test the configuration before making it the default Agent model.
- Return to New Task. The model chip in the composer should show the selected model instead of Not configured.
Credentials should be stored in Keychain. Diagnostics and exported reports redact credential values; do not paste an unredacted provider response into a public issue.
Each provider and each model has its own routing switch. Turning one off keeps its endpoint, credential and model metadata editable in Settings while removing it from the New Task model picker. The picker groups Apple/downloaded local models separately and groups cloud models by provider, so duplicate model names remain distinguishable.
An enabled model also has a separate Hide from primary model picker switch, off by default. Use it for a model that should stay available as an auxiliary/internal model without cluttering the Home/New Task LLM menu. Existing tasks that explicitly reference the model remain resolvable.
Open Settings → Auxiliary Models. The roles are independent:
- Vision model reads user images and browser screenshots. Select only a model whose provider genuinely supports image input.
- Image generation model creates a new image from a prompt.
- Image editing model edits an attached or selected image.
A provider appearing in the Agent picker does not imply it supports vision or image operations. Floe disables incompatible role combinations instead of sending an invalid request.
For a dedicated image provider, choose OpenAI or Google Gemini, enter its API key, and review the editable Base URL before saving. OpenAI defaults to gpt-image-2. Google defaults to Nano Banana Pro (gemini-3-pro-image) through the native Gemini generateContent API. Keep generation, editing and vision capabilities enabled only when the selected endpoint implements them. A proxy URL may include its own path prefix; Floe preserves that prefix when constructing requests.
Open Settings → Local Models. The Apple Foundation Model row is system-managed and therefore has no Floe download button, API-key field or model selector. On iOS/iPadOS 27 it reports one of the system's real states: available, unsupported device, Apple Intelligence disabled, model not ready/downloading, or another system availability failure. Resolve that reason in iOS settings and leave Floe open long enough to refresh; do not repeatedly retry while the system model is downloading.
Qwen and Gemma entries are user-downloaded MLX snapshots. Download, load and benchmark are separate actions. Floe keeps one downloaded model resident at a time and checks current device headroom before mapping it. Closing background apps may increase available memory, but iPadOS can still terminate an app under pressure. If loading is rejected, retry after freeing memory or select a smaller model; if the process terminates, export the new Xcode/device or uploaded diagnostic log rather than assuming a prior crash has the same cause.
An installed model can be disabled without deleting its weights. Re-enabling it makes it available to the task picker again; disabling a resident MLX model also unloads it.
Local models receive a smaller, intent-ranked catalog of real Floe tools and a local-only dynamic context/compression budget. Cloud-provider context limits, compression and tool schemas are not reduced to accommodate a local model. On-device inference is text-only and never maps a vision projector. Floe transcribes attached images with Apple Vision OCR, saves the bounded handoff under the task workspace's OCR folder, and supplies that text to the conversation. PDF text inspection, page rendering and OCR remain available; semantic image.inspect and visual browser tools are not exposed to local models. If OCR finds no readable text, Floe states the limit instead of guessing what the image contains. If a local model cannot produce a valid tool call, Floe reports the parsing or capability reason instead of claiming the tool ran.
Greetings, ordinary conversation, questions and brainstorming do not require an explicit task command. Apple Foundation Model should answer them naturally and asks for clarification only when missing information materially changes a consequential action. Downloaded MLX models prefill prompts in device-budgeted chunks and release transient Metal/KV caches after each generation while retaining model weights only for tool continuation within the active task.
Normal app launch opens New Task. Before sending, use the chips around the composer to choose:
- an Agent model;
- no project or a project workspace;
- local or an authorized remote execution target;
- enabled Skills;
- the initial task permission profile.
Attach files or images, write the request, and send. The draft becomes a persistent task in place; it does not jump into a second chat system.
- No project selected: Floe creates an internal private workspace owned by this task and lists the task under Chats.
- Project selected: the task belongs to that project and appears under its folder in the sidebar.
- A task has exactly one workspace owner. Moving it later is an explicit action because the available file scope changes.
- Deleting a project task never deletes the external project files. Deleting a private task may remove its app-managed workspace and browser data.
Open the workspace Files inspector and select Source Control. A non-repository workspace can be initialized in place. For a repository you can inspect status, per-file diffs and recent commits; stage all changes; commit; create or switch branches; fetch; fast-forward pull; and push. Floe intentionally omits destructive reset/clean, force-push and history rewriting.
Open Settings → GitHub & Source Control to sign in through GitHub's official device authorization page. Floe shows a one-time code and polls only at GitHub's returned interval. Fine-grained token entry remains available as a fallback. The resulting credential is validated against GitHub, stored only in the device Keychain, and never added to a remote URL, repository file, log or model prompt. After connection you can list accessible repositories, clone one into a subfolder of the current workspace, or create a public/private repository. Grant only the repository access needed for the intended operations.
Open Settings → Hosts & Remote Sessions to save a remote device. One device can contain SSH, direct VNC, VNC through an SSH tunnel, Telnet, raw TCP and BLE GATT serial connections at the same time. Device type is optional descriptive metadata; configured protocols and live connection probing are the capability authority.
Only an SSH device with Use as remote execution environment enabled receives automatic Floe guardian checks, installation and updates before guardian-backed work. With the switch off, it remains a management or debugging target and Floe does not force-install the guardian. The model may read and edit non-secret device and connection metadata; passwords and keys still enter through the secure UI and remain in Keychain.
For a paired SSH host, the Agent can run bounded read-only network.ping, network.traceroute, network.dnsLookup, and network.tcpProbe tools. The selected host performs the real probe and returns an exit code plus bounded output, separating host, DNS, route, and service-port failures. Targets, counts, hops, ports, timeouts, and output sizes are structurally constrained.
When the user explicitly supplies an address, port or BLE GATT identifiers in the conversation, the model can open a task-only temporary Telnet, TCP or BLE serial session without saving a device. Temporary connections are not synced and automatically close after 30 minutes. Telnet and raw TCP are unencrypted and should be used only on a trusted network or inside an existing secure tunnel. iOS does not expose arbitrary classic Bluetooth SPP to normal apps, so Floe supports BLE GATT serial characteristics; MFi accessories still depend on their published vendor protocol.
Stateful tools discover identifiers before acting: saved hosts and connections come from the host list, a running SSH command returns the taskID consumed by status checks, remote hosting list returns the shareID consumed by stop, and cloudWorkspace.catalog returns the workspaceID used by remote file and Git tools. The Harness writes trusted provenance and bounded resourceBindings for these IDs and cursors before output can be truncated; tool or model text cannot forge those fields. If an identifier is missing, the Agent calls the named read-only discovery step once rather than guessing an ID or repeating a side effect. Malformed structured calls get one correction attempt and do not create a fake call/result pair.
Every later message creates a new Run inside the same task. Floe reconstructs context from prior messages, attachments, tool results, decisions, the active plan and goal, scoped memory, workspace instructions, and task permissions. Older history can be compressed into sourced summaries; evidence is referenced rather than silently re-executed.
If a task reports that it was interrupted, use Resume or send a continuation message. Side effects whose outcome is uncertain require confirmation before retrying.
Opening an existing conversation positions it at the latest content. Live output follows while you are at the bottom; reading older history keeps your position. Long-press a task in the sidebar, workbench, or conversation list and choose Select Multiple to filter, select all, archive, or delete. Archived tasks can be restored in batches. Archiving running tasks explains the stop action; individual failures remain visible.
- Agent mode can use the tools allowed by the task policy and normal approval gates.
- Plan mode is read-only: it may inspect and analyze, but cannot write files, run side-effecting commands, or submit browser actions until the plan is accepted.
- Goal mode tracks steps, budget, evidence, child runs, and completion criteria. Completion should be proposed only when the evidence gate is satisfied.
Memory is scoped globally, to a workspace, or to one task. A memory candidate must be reviewed before it becomes active, and memory never grants permissions.
The task timeline shows assistant output, reasoning previews, tool requests, tool results, file activity, errors, questions, approvals, and checkpoints. The inspector is collapsed by default; open it when you need:
- Changes for per-file diffs and line statistics;
- Files for the current workspace tree;
- Browser for the task's visible web session;
- Terminal/Host for an authorized execution target;
- Progress for phases, checkpoints, and budget;
- Child Agents for independent child-run status and cancellation.
Switching tasks clears task-specific inspector references so one task cannot accidentally display another task's browser or files.
The browser is a real, user-visible WKWebView. The Agent can navigate, observe a bounded semantic DOM, wait for page changes, take screenshots, click stable element references, type, scroll, and manage tabs within the task policy.
Choose Take Over when a page requires login, QR scanning, CAPTCHA, 2FA, password entry, payment, camera/microphone access, a trusted file chooser, canvas interaction, or content Floe cannot safely address. Finish the interaction directly in the browser, then choose Return to Agent. Floe observes the page again before the Agent continues.
An element reference is bound to a document ID. After navigation or a major DOM change, a stale reference fails and the Agent must observe again; it must not guess and continue clicking.
Effective authority is the intersection of the global ceiling, workspace defaults, task overrides, available device/host capabilities, and any time-bounded grant. The provider receives only allowed tool schemas, and the executor checks authority again.
Change the current task's permission only from the permission control below the chat composer. A selection saves automatically; there is no second Save action. It can also be changed while a task is running: the new mode immediately re-evaluates a waiting tool and applies to subsequent calls. The upper-right menu and inspector no longer duplicate this control. Settings → Agent & Permissions manages defaults for new tasks and existing temporary grants.
Routine bounded reads, workspace inspection, image generation/inspection, OCR, read-only PDF operations and local-network discovery bypass approval-model latency. Once the user explicitly requests installation, deployment, environment repair, a Floe guardian update, or preparation on a selected SSH host, ordinary system packages, package-source changes, dependency repair, and Floe's verified atomic guardian update inherit that task authority instead of interrupting for every command. Deleting data, entering credentials, uploading files, browser login/payment, ambiguous broad remote mutation and catastrophic commands still require explicit review. Git force-push, destructive reset/clean and history rewriting are not exposed.
Approval is based on the user's stated goal and the concrete tool target, not on a brittle keyword match. A broad request such as “test all tools” permits safe diagnostics and bounded non-destructive checks, but does not authorize deletion, credential access, arbitrary remote commands, model-policy changes or persisted personal-data writes. Approval results and reasons appear inside the corresponding expanded tool call rather than as a detached chat message.
Leaving a task screen does not cancel its Run. Floe records checkpoints at model phases, tool boundaries, approvals, user-input waits, child runs, and partial responses. When the app returns, it reconnects to a provider job when supported or creates a recovery Run in the same task.
iOS scheduling and background execution are best effort. A notification or Live Activity opens its target task; ordinary cold launch still opens New Task. Do not assume an SSH, VNC, browser, or model stream stayed connected while iOS suspended the app. If you manually close Picture in Picture, Floe persists that decision for the whole active task batch, including concurrent or cold-restored runs, while background execution may continue. Foreground retraction, mode changes, task completion, and a system interruption are tracked separately. A genuinely new batch may offer Picture in Picture again; stale preparation callbacks cannot recreate a player for an older batch.
Open Settings → Apple Capabilities to decide which compiled integrations Floe may advertise to the Agent. Calendar, Reminders, Home, Maps, Web, Watch status, vision, mail composition, documents/PDF, camera, location, Shortcuts and automatic tasks are independently switchable. These device-local switches do not grant OS permission; iOS still asks on first real use, and denial must not block the rest of a task.
Floe publishes Run Floe Task and Schedule Floe Task App Intents. Add Run Floe Task to a Shortcuts personal automation for a system time, Focus, arrival or other exact Shortcuts trigger. Floe's own schedule is durable but uses best-effort iOS background refresh, so its wake time is not guaranteed. The immediate intent starts a normal durable task with the default Agent model without opening Floe.
Signed builds include bounded CPython 3.13. The model can request a familiar declarative command such as pip install marko==2.2.0; Floe parses its package specs and asks the package-review model whether they are necessary for the user's existing task before any download. The managed installer resolves dependencies in Application Support quarantine and activates only pure-Python py3-none-any wheels after hash verification and static inspection. Flags, URLs, paths, shell syntax, native extensions, Mach-O/ELF payloads, dynamic libraries, subprocess execution and sandbox escape remain unavailable.
Supported builds bundle native NumPy, Pillow, and pandas. The runtime probe is authoritative for the current build; use available native libraries directly. Missing binary packages such as SciPy or Matplotlib can use the explicitly identified browser Pyodide route or a configured trusted SSH host. Report the actual execution environment and results.
exec.localNumerical provides a bounded, dependency-free R, Stata and MATLAB/Octave compatibility surface for descriptive statistics, quantiles, covariance/correlation and one-predictor OLS. Stata-compatible commands include generate, display, summarize, correlate and regress. It is not GNU R or Stata. PyStata still requires a separately installed, licensed Stata runtime, while pyreadstat depends on native extensions; neither can masquerade as an installable pure-Python iOS package. Route full R/Stata to a configured trusted SSH host.
An installed skill may include bounded UTF-8 .py scripts and exact-version pure-Python package requirements. The creation/install review validates paths and source, downloads and inspects only universal wheels, and records script/package fingerprints. A later task can execute the identical audited script without asking again for ordinary sandboxed computation; task inputs travel separately in inputJSON. Any source or dependency change, important-file mutation, credential use, privilege request, destructive behavior, or external side effect returns to the current task's normal approval policy.
Open Python, JavaScript, MJS or CJS files from the workspace to use the structured editor with line numbers, syntax highlighting, search/replace, symbols, undo/redo and bounded local execution where supported.
The Agent can create native DOCX, XLSX and PPTX files with document.createWord, document.createWorkbook and presentation.createDeck. It can inspect semantic fields with document.office.inspect and apply bounded text, cell, formula and slide-note changes with document.office.updateText. These operations are local and do not wait for an approval model when they remain inside the current workspace.
For manual revision, open the file from the workspace. Floe shows the normal document preview first. Choose Edit Office document to open the basic editor, make changes, and save. DOCX exposes text fields; XLSX exposes worksheet cells and formulas; PPTX exposes slide text and speaker notes. Saving is atomic and preserves untouched OOXML package parts. Use Microsoft Office, LibreOffice or another full editor for advanced layout, charts, macros, tracked changes, animation and pixel-perfect compatibility.
PDF is separate from Office: open it directly from the file list, read it in the wide-screen inspector, then expand to fullscreen. The shared reading session retains page and zoom state; changed local files reload. Remote previews are downloaded read-only snapshots. Office saves check the file version and retain your draft when saving fails or conflicts.
Open a workspace's Files inspector and choose Canvas. Each workspace owns at most one native canvas project, and that project can contain multiple canvases. The current native surface supports movable text notes, freehand drawing, panning, zooming, renaming and deleting individual canvases, and atomic local persistence. Canvas content stays with the workspace and is not silently published to a global asset library.
The canvas is deliberately a focused editing surface, not a second unrestricted browser. Drag empty space with one finger to pan, drag a node to move it, use two fingers to pan and zoom at any time, and use Apple Pencil to draw. Double-tap empty space to create a node; drag a connection port to another node or release on empty space to create the next node. Import artifacts from Files, Photos, or Materials rather than creating meaningless empty media nodes.
The small AI field below a selected node edits that node in place. It sends only the node's current value, saved settings, explicit references, and the new instruction; it does not open Canvas Assistant, create a task conversation, call tools, or start generation. For a generation task it can refine the prompt and provider-compatible options. Save the configuration first, then press Start Generation on the task card. The task and artifact cards show queued, generating, downloading, failed, and ready states. Retry reuses the existing task and artifact nodes.
Only explicit source connections contribute generation context. Ordinary connections, direction-only arrows, generated-artifact relationships, unconnected notes, and older output do not. Starting or retrying an existing task reuses its saved snapshot and never inserts a new prompt node. Execution stays inline on the task and artifact cards; configuration and import are the only generation flows that open sheets.
Choose Canvas Assistant for cross-node research and orchestration with only the tools allowed on the canvas surface. A text-only primary model routes visual understanding through the configured Canvas Vision model; when none is available, Floe reports the missing capability once instead of retrying. A research result remains read-only until you choose Add to canvas. Public web images are downloaded, validated, deduplicated, and stored before being used as references; raw web URLs are never sent as reference-image inputs. Standard MCP remains disabled for canvas by default. Open … → Canvas Guide to replay the canvas onboarding.
To connect a standard remote tool server, open Plugins → Manage Connectors → Standard MCP and add a Streamable HTTP endpoint. Floe supports no-auth, Bearer token, and custom-header authentication; secret values are stored in Keychain rather than server metadata. Each server and discovered tool can be enabled independently. Remote tools use a server-specific namespace, remain subject to the current task's local permission and approval policy, and treat server descriptions and outputs as untrusted data. Enabling Allow canvas use adds only that server's currently enabled tools to future Canvas Agent runs; the setting is off by default, does not grant ordinary task authority, and never bypasses approval.
You can also create a private canvas from Creative Mode → New Canvas without first binding a workspace or configuring an image-generation model. Creation menus show generation tasks first. iPhone uses a compact action menu and scrollable bottom tools; new nodes use the actual viewport. SVG, HTML, and Markdown node refinement checks revisions to avoid overwriting concurrent edits.
- Skill Creator builds a local declarative instruction package.
- Skill Finder downloads an HTTPS candidate, uses a selected model to normalize it for iOS, then runs deterministic validation and compatibility checks.
Skill tool calls remain subject to the current task authorization and runtime validation. Supported UTF-8 Python scripts and pinned pure-Python dependencies are reviewed at installation; execution reuses only the approved fingerprints. Code or permission changes are checked again. This does not permit native dynamic plugins or installation hooks.
The plugin entry separates Discover and Installed. Official entries show purpose, version, and install/update actions; source and technical details are folded away. Uninstalled official plugins stay removed across launches and can be installed again from Discover. Updates that expand permissions still show the change.
- Model not configured: add a provider and select a default Agent model.
- Apple Foundation Model unavailable: read the exact reason under Settings → Local Models. It requires an eligible device, iOS/iPadOS 27, Apple Intelligence enabled, and the system model ready.
- Downloaded local model will not load or terminates the app: free device memory, unload another model and retry once. Export the newest device/Xcode or uploaded diagnostic log; do not diagnose it from an older unrelated crash.
- Vision unavailable: select a provider/model that advertises and implements image input.
- Local model does not call a tool: confirm the tool is allowed for the task and that the request names the intended action. Floe displays a capability or structured-call parsing reason when the model cannot use it.
- Task interrupted after backgrounding: reopen the task and use the offered safe recovery action.
- A resumed task repeats completed tools: stop the run and export diagnostics. A recovered run should restore its execution ledger and must not replay successful tool/argument pairs.
- Browser says
stale: observe the page again before interacting. - Remote tool unavailable: confirm the host, SSH authorization, task permission, and network path.
- LAN scan finds nothing: allow Local Network access in iOS Settings, stay on the same LAN, and retry. Discovery is limited to the Bonjour service types declared by the app and is not a general port scanner.
- Workspace preview says it is not open: reopen the Files inspector and confirm the task has either its private workspace or the intended project binding before opening the file.
- Picture in Picture is black or does not start: Floe prepares a live inline progress source while the task runs and lets AVKit promote it when you leave the app. Returning to Floe ends the active system PiP session. If you close PiP yourself, Floe will not recreate it for the same task batch after another foreground/background cycle; a new Run resets that choice. Include the PiP status and latest diagnostics when reporting a persistent black frame.
- A Python package will not activate: confirm it is a pure-Python universal wheel. Packages containing native extensions remain download-and-inspect only; use a trusted SSH host for native dependencies.
- Voice fails or exits: check microphone and speech-recognition permissions, audio route, and whether another app owns the input session.
Export a redacted diagnostics report from Settings → Privacy & Security when filing a reproducible bug. See Support for the report checklist and Security for private vulnerability reporting.
Open Settings → Data Management to inspect Floe's total footprint, installed app size, user data, safely reclaimable space, and categories for local models, private workspaces, fonts, attachments, generated content, browser artifacts, checkpoints, database and other data. Safe Cleanup removes only rebuildable caches and temporary items left for at least one hour. It does not remove workspaces, documents, models, fonts, attachments, the database, or credentials.
Data Management → Archived Tasks supports swipe-to-restore, confirmed single deletion, selected restore/delete and clear-all. The normal task list still supports swipe-to-archive.
Data Management → Font Resources keeps one content-addressed Floe-global copy of each imported font. Import from Files or use a direct public HTTPS URL for a TTF, OTF, TTC or OTC file up to 32 MB. Floe registers the managed library again at launch, so Word/PDF work in every workspace can reuse it without downloading per workspace. In Automatic mode, font.list and bounded font.install bypass approval-model latency; font.remove remains reviewed because it affects all workspaces. Apple public APIs do not permit an arbitrary web font to be silently installed for unrelated apps, so downloaded fonts are global within Floe rather than system-wide outside Floe. If iOS does not expose a requested system font, the Agent explains that boundary and installs a permitted font into Floe's managed library instead.
Task history is device-local. Configuration sync includes provider/model profiles and non-secret host profiles, while provider API keys use iCloud Keychain. Sync saved credentials is off by default and requires device authentication. When enabled, only credentials explicitly promoted to the vault can sync; task/workspace temporary credentials never do. A descriptor may arrive before its Keychain item, in which case the UI shows Waiting for secret instead of claiming synchronization completed.
Settings → Files → Browse and Manage Files provides quick access to project workspaces and private workspaces from active or archived conversations. Browsing does not switch the current conversation workspace. Reuse directory search, preview, edit, move, export, and batch deletion. Deleting a private task cleans up its own files while shared projects remain; pending local cleanup can be retried in the manager.
Expanded long reasoning uses its own scrolling reading area with beginning/latest navigation and fullscreen reading. Copy retains the complete transcript. Partial tool-argument generation counts as activity; execution still waits for complete, validated arguments.
Ask to convert a workspace Markdown, DOCX, HTML, RTF or text file to another supported format, or to PDF, while keeping the source. Floe passes file paths to its bundled offline converter rather than asking the model to rewrite the body. Results are saved as new files; only compact status and warnings return to the model. Local images are embedded. Searchable PDF input exports text in page order; scans need OCR first. Complex page geometry, floating objects and formatting that Markdown cannot represent are not guaranteed to survive. Open the output to inspect it.