Start with one Bot
The app is your control surface. A gateway is the machine that runs the agents and keeps their work. A provider supplies the AI model. A Bot keeps its identity and configuration across conversations.
1 · Connect a gateway
Open Gateway and pair a self-hosted machine, or use möbius Cloud to provision a managed private gateway. Select the machine you want to work on; its providers, Bots, workspaces, and history become available.
2 · Configure a provider
Open Providers, add a setup, and complete its sign-in or API-key configuration. Save it before choosing a model. A Cloud gateway and a model-provider account are separate parts of setup.
3 · Set Bot defaults
Choose a model and reasoning effort, write a short system prompt, and review capabilities. Start with Ask for approval. Save Bot defaults, then create a Bot from Bots.
4 · Start a conversation
Choose the Bot and a workspace on the gateway. Give a concrete task and the expected output, for example: ‘Read this repository and explain how to run its tests. Ask before changing files.’ Review the transcript and any approval requests.
5 · Add automation when ready
Try a routine manually before enabling repetition. Create a Swarm when you need several persistent specialists to collaborate. Subagents are also available for delegated work inside one conversation.
Gateway · where work runs
Gateway lists the machines paired with this device. Chats run on the selected gateway, using that host’s files and credentials. Keep the gateway running and reachable for remote work and routines.
Pair and select
Use the + button and enter the gateway address and pairing code supplied by its operator. Use the address exactly as provided, including the transport and port when present. Pairing grants this device access; use a gateway you control or trust. The selected machine is marked in the list.
Connection details
Open a paired gateway to inspect Status, Endpoint, Transport, Name, and Wire protocol. WebSocket TLS and TLS are encrypted remote transports; Loopback TCP is local to the host. Reconnect retries the selected connection. Rename changes the device’s display name for that gateway.
Pair another device
On the active gateway, choose Create one-time code. Enter or share that short-lived code with the same gateway address on the other device. Check the displayed expiry and generate another code if it expires. Treat the code as an access credential.
GitHub credentials
Open Host credentials → GitHub. If none is available, enter a GitHub username and personal access token, then Save. The credential is sent once to the host’s configured Git helper; möbius does not read it back. This enables Git HTTPS access on that host, separately from model-provider sign-in.
SSH identities
Open Host credentials → SSH to inspect public identities, algorithms, and fingerprints. Generate creates an Ed25519 key pair on the gateway. Copy or share the public key and add it to the remote service. The private key stays on the host; generating a key alone does not grant repository access.
Cloud and forgetting a gateway
The möbius Cloud offer provisions a managed private gateway. Subscription and service status are managed through the Cloud account. Forget gateway removes this device’s pairing and requires pairing again; it is not a command to delete the remote gateway or cancel a subscription.
Cloud plans and credit
Choose Cloud or Cloud Plus before subscribing. Both plans include the same gateway and features, with different included AI credit. Settings → Profile shows the current plan, billing date, remaining credit, and any scheduled change. Manage subscription opens Apple’s controls: an upgrade starts immediately, while a downgrade starts at renewal. Credit renews once per verified paid billing period and does not roll over. Turning off renewal keeps paid access until its end; Restore purchases does not grant extra credit.
Self-hosted administration
Install and run mobius-gateway on the host, initialize its state, configure reachability, and obtain a pairing code. The terminal reference at /manual documents the gateway commands and flags. Host setup, backups, uptime, and network reachability remain the operator’s responsibility.
Providers · accounts, endpoints, and models
A provider setup represents one account or endpoint on the selected gateway. You can create separate Work and Personal setups for the same service. Configure the connection here, then assign a route to a Bot.
Add a setup
Use + and choose an available subscription or API provider. Subscription providers use their supported sign-in flow; API providers normally require a key. The gateway advertises which providers and options are available. A setup’s service is fixed after creation.
Name and colour
Name identifies the setup in model pickers and usage, so use meaningful names such as Work. Colour distinguishes it visually. Neither changes the selected AI service.
Model ID(s)
For configurable providers, enter exact model IDs separated by commas. Whitespace, empty entries, and duplicates are ignored. Fixed catalogs show their models read-only. Listing a model does not grant access to it: the endpoint and account must support it.
Reasoning effort(s)
For configurable catalogs, enter the exact efforts supported by the listed models, separated by commas; leave empty for the provider default. Fixed catalogs show supported efforts read-only. Choose the desired model and effort in the Bot’s model picker. Higher effort can increase latency and usage.
Base URL
Change the endpoint only where the provider exposes this field. Otherwise it is provider managed. Use the API base URL required by that service, not its website or sign-in page. Keys and prompts go to the configured endpoint, so verify its address before saving.
Tool discovery
This read-only value describes how the route makes optional tools available. Native discovery preserves the cached context; Rebuild supports the same tools but starts a new cache prefix when the tool set changes. It is not a tool permission switch.
Hosted web search
Off disables provider-hosted search. Cached allows the provider’s cached search; Live allows its live search. Choose among the modes advertised by this provider. The description under the picker explains the selected behavior; a single available mode cannot be changed. Hosted search is separate from the network permission for shell commands in Sandbox.
Credentials and sign-in
Enter an API key in Credential or follow the provider’s sign-in instructions. A device-code flow displays a verification page and a code; finish the provider’s confirmation and return to the app. Configured status and a masked key hint do not expose the full saved key. Save the setup and check the status before starting work.
Usage and removal
Provider usage shows the data that provider supplies; missing limits or cost data should not be read as unlimited access or zero cost. Removing a setup deletes it from the gateway. Reassign Bots that use it to an available route before running them again.
Bot defaults · the starting configuration
These are the prompt, model, and capabilities copied into newly created Bots. Saving defaults does not rewrite existing Bots. Edit an existing Bot’s own settings when you want to change its behavior.
System prompt
Write the durable brief: role, boundaries, working style, and expected results. Keep individual tasks in conversations or routines. For example: ‘Review code for correctness. Explain findings with file references. Ask before applying changes.’ Avoid storing credentials in prompts.
Model and reasoning
Choose a route from the configured provider setups. The route identifies the account, model, and supported reasoning effort. If the picker is empty, connect to the gateway and configure a provider first.
Voice
A Voice picker appears when the selected configuration supports realtime voices. Choose the voice used for supported realtime conversations. A text-only route does not acquire voice support by selecting another Bot setting.
Maximum model steps
Limits primary model rounds in one run, not tokens, seconds, or total provider spend. The app permits 1–42,000 and steps by 100. A high ceiling allows long work but can increase usage; delegated agents and scheduled runs need their own attention. Reaching the ceiling stops that run.
Capabilities and saving
Toggle optional capabilities and open rows with details to configure them. Required capabilities cannot be disabled. Done closes a capability editor; use Save Bot defaults to persist the whole draft. The status control shows unsaved changes, validation, and save results.
Conflicts and busy state
Changed elsewhere means another client saved a newer revision. Reload the saved configuration and reapply your intended changes. Busy means the gateway cannot apply the change yet; let active work finish or stop it, then retry. A rejected configuration must be corrected before it takes effect.
Bots · durable agents
A Bot is a persistent identity with its own prompt, model, capabilities, conversations, and routines. Create specialists with clear responsibilities, then reuse them across tasks and workspaces.
Create and identify
In Bots, use + to create a Bot. Enter a name and operational description. möbius assigns its @handle, colour, and the current Bot defaults. The name is for people; use the exact @handle shown in the roster when addressing a Bot in a Swarm.
Edit a Bot
Open the Bot and its settings to change its name, description, accent, system prompt, model, voice when supported, maximum model steps, and capabilities. Save Bot persists the durable configuration. A name or colour change is presentation; prompts, routes, and capabilities affect its work.
Conversations and background work
Open a Bot’s conversation to give it a task in a workspace. Its detail screen also shows routines, run history, Swarm membership, and background conversations when present. Open the relevant conversation or run to see results, failures, or pending approvals.
Defaults versus a Bot versus a chat
Bot defaults seed future Bots. Bot settings define that Bot’s durable behavior. Conversation controls, such as a route or approval selection where offered, concern the selected conversation. Check which scope you are editing before saving.
Delete deliberately
Delete Bot and All Data removes the Bot and its owned data, including conversations and routines. It is not an archive operation. Read the confirmation and preserve any results you need before deleting.
Capabilities · what an agent can do
The built-in catalog below describes the shipped defaults. Your gateway’s saved Bot defaults may differ. A capability’s switch and its settings are separate: configuring a disabled optional capability does not enable it.
Sandbox · required
Owns approval policy and command isolation. Ask is the initial policy. The next section explains all four modes and their effect on unattended work.
Tools · required
Provides workspace file reads and edits and command execution. Available tools are discovered as needed. Tools still pass through their validation and approval boundaries; having the capability does not bypass Sandbox.
Attachments · initially on
Lets the chat inspect files you attach. What the model can understand depends on the route’s supported input types. Attach only the files needed for the task.
Artifacts · initially on
Lets the agent publish workspace files into the current chat as deliverables. Open the published result to inspect or share it. A file changed on the host is not automatically a published artifact.
Workspace instructions · initially off
Loads optional root AGENTS.md guidance from the workspace. Enable it for repository-specific working instructions. This is additional workspace guidance, not a replacement for your Bot’s system prompt.
Extensions · initially off
Enables selected installed skills and plugins. Install packages in Extensions first, then activate the desired packages in this capability and save. Package hook trust is a separate decision.
Tasks · initially off
Lets the agent keep a durable to-do list for multi-step work. Use it when you want visible task progress. It does not schedule runs; use routines for that.
Subagents · initially on
Allows delegation to durable child agents inside the current chat’s task tree. Default model can inherit the parent or use another configured route. Maximum depth defaults to 4 (range 1–16). Maximum concurrency defaults to 8 (range 2–64) and includes the root agent. Maximum agents defaults to 101 (range 2–256), counts retained agents including the root, and must be at least the concurrency limit. Children share the workspace; more parallelism can increase usage and concurrent file edits.
Messages · required
Active message delivery defaults to Steer: messages sent while work is running enter at the next model boundary. Queue starts a new turn after the active turn finishes. Neither promises an immediate interruption of an executing tool. Maximum pending messages defaults to 64, with a range of 1–1,024.
Context offloading · initially on
Masks older successful tool output from the model’s active context. Stale after tokens defaults to a trailing window of 50,000 tokens, must be positive, and changes in steps of 10,000. A smaller window retains less tool output in active context; it does not erase the durable transcript. Handoff compaction disables this capability.
Compaction · initially on
Automatic uses native provider compaction where supported, otherwise a summary. Handoff asks the agent to save a working checkpoint and continue in a fresh context in the same chat and task; it disables Context offloading. Compact after tokens defaults to 250,000, must be positive, and changes in steps of 10,000. The model’s actual context capacity can force earlier management; raising the setting does not enlarge the model’s context window.
Scratchpad · initially on
Keeps explicitly approved shared Swarm and global knowledge. Use durable notes for facts and working conventions worth carrying between tasks; review their scope before saving. It is not an automatic promise that every chat detail will be remembered.
Sessions · required
Supports resuming, forking, and recovering Bot-owned durable history. Session history and the model’s currently visible context are different: compaction can shorten active context while durable history remains available.
Bots · required
Collaboration defaults to Off; choose Swarm to make a Bot eligible to join one and exchange messages. Routine creation defaults to Off; On lets the Bot request creation of a routine through an approval-required tool. This switch governs the agent’s tool, not your ability to create a routine in the app. A Swarm leader can target a current member when creating a routine.
Approval policy · choose the authority you intend
Approval policy is configured under Sandbox and may also appear in conversation controls. It controls approval-required actions; it is not a substitute for describing the task clearly.
Ask
Pauses approval-required actions for your decision. Read the proposed action, arguments, and workspace before approving or rejecting it. An unattended routine can wait here until you respond. Approval permits that action; another Bot’s message cannot grant your authority.
Allow · no network
Runs approval-required actions without asking, while commands have no network access. Use it for work that can complete with local files and tools. It does not mean the whole app is offline: model requests still need the configured provider.
Allow · network
Runs approval-required actions without asking and permits network access within the sandbox. Tasks can make network requests; choose this only when that authority fits the intended work.
Full access
Runs shell commands without approval with host filesystem and network access. This can affect files outside the workspace and resources accessible to the host. Select it only for work and extensions you trust with that reach.
Workspace boundaries
Workspace paths refer to the gateway’s filesystem, not your phone’s storage. Attached files and folders make additional task material available through the app’s supported controls. If access is denied, inspect the requested path and current policy rather than repeatedly approving an unrelated action.
Routines · scheduled Bot work
Open a Bot and add a routine. Each run uses a workspace and task, with results in run history. The gateway performs the scheduling, so your phone does not need to remain open; the gateway must remain operational.
Workspace and task
Choose an available workspace and write self-contained instructions: what to inspect, what to produce, and when to ask you. For example: ‘Review changes since the previous report, write a concise summary, and do not edit source files.’ A routine should make sense without an open chat supplying missing context.
Once
Choose a future date and time in Run at. A one-time routine runs at that scheduled instant and then finishes. Repeating end controls do not apply.
Every
Choose seconds, minutes, or hours and an interval. The minimum is 60 seconds. The app’s value control runs up to 365 units; seconds start at 60, minutes and hours at 1. Intervals express elapsed time, unlike a calendar schedule tied to a local clock.
Daily and Weekly
Daily selects a time; Weekly selects a day and time. Choose the named time zone that should govern the schedule. The time picker uses that zone. Local-time schedules follow its clock and daylight-saving rules, so do not assume the same UTC time throughout the year.
Advanced cron
Enter five fields: minute, hour, day of month, month, day of week, and select a time zone. ‘0 9 * * 1-5’ means 09:00 Monday to Friday in that zone. Use this for schedules the simple pickers cannot express. The gateway validates the expression when you save; inspect the next-run display after saving.
End and Enabled
Repeating routines can end Never, After duration, or At date. Duration accepts 1–365 minutes, hours, or days and is converted to an end timestamp when saved. At date must be in the future. Editing exposes Enabled; the row also has Pause and Resume actions.
Run, inspect, and troubleshoot
The Run action starts a manual run. An already running routine cannot overlap itself. Open run history for the transcript and status: running, succeeded, failed, or skipped. An approval indicator means you must open that run and respond. Pause prevents future scheduling; inspect active work separately.
Deletion
Delete routine removes the routine and its run history. Deleting an individual completed run removes its history entry and conversation transcript. Running entries cannot be deleted through the run-row action.
Swarms · persistent specialists working together
A Swarm groups existing Bots with a leader, coworkers, a shared Swarm Chat, and a collective scratchpad. Each Bot can belong to one Swarm. These are durable peers; subagents belong to a particular conversation’s delegation tree.
Prepare the Bots
Create at least two Bots with distinct roles. In each Bot’s capabilities, set Bots → Collaboration to Swarm and save. A Bot already in another Swarm is not available for a new one. If the selection is empty, check collaboration and existing membership.
Create a Swarm
From Bots, create a Swarm, enter its name, choose a leader, and select at least one coworker. The leader cannot also be selected as a coworker. For example, use a planner as leader, a researcher to gather evidence, and a reviewer to check conclusions.
Address work explicitly
Use the roster’s exact @handles in Swarm Chat, for example ‘@reviewer Check the proposed patch.’ Your message without a mention goes to the leader. A Bot-authored post without a mention stays on the shared board without waking another Bot. Bots can read recent shared messages and use @user when a human decision is required.
Leader and permissions
The leader coordinates the team and, when Routine creation is on, may schedule a current member through the routine tool. Each Bot still uses its own model, capability settings, and approval policy. Messages from peers are advice; they do not authorize actions for you.
Monitor and maintain
Open the Swarm to inspect its roster, activity and statistics, shared chat, and collective scratchpad. Add eligible Bots or remove coworkers through the Swarm controls. Give shared notes enough context to be useful to all members; keep private credentials out of them.
Rename or disband
Rename changes the Swarm’s title. Disband permanently deletes the shared Swarm Chat and collective scratchpad and ends the grouping. Preserve needed shared results first. It is separate from deleting an individual Bot and its owned data.
Extensions · install, activate, and trust
Extensions add skills and portable plugins to the selected gateway. Installation, activation for a Bot, and trust for executable hooks are separate steps.
Available and installed
With a Cloud account, Available shows the extension catalog. Select a package to install it. Installed lists packages on this gateway. Open a package to inspect its description, kind, version, source, reference, subdirectory, resolved revision, digest, skills, and any executable hooks.
Install from Git
Use + and paste an HTTPS Git URL, or a GitHub tree URL for a branch and subdirectory. The gateway clones the source, pins an immutable snapshot, and reads its package manifest. The URL must point to a valid supported package; an arbitrary repository is not automatically an extension.
Activate for a Bot
Open Bot settings → Capabilities → Extensions, enable the capability, select the installed packages to activate, and Save Bot. Use Bot defaults instead if future Bots should inherit the selection. Installation alone does not select a package for every Bot.
Executable hooks
Hooks are shell commands that run on the gateway at matching events. Inspect the listed commands and use Trust hooks only when you intend to run them. They stay disabled until trusted. Trust is tied to the displayed digest; updating to a different snapshot disables them until you review and trust it again. Untrust hooks withdraws that trust.
Update and uninstall
Update fetches a new snapshot from the configured source. Review changed hooks afterward. Uninstall removes the package without rewriting saved chat selections; chats referencing it continue with the extension disabled. Per-workspace .mobius/extensions data is retained.
Discovered skills
Discovered lists skills found in gateway and workspace skill directories. These are not installed packages managed by this screen, so uninstall controls do not remove them. Their availability is discovered from those directories; manage their source files on the host and use the relevant capability in the Bot.
Conversations, context, and results
Use conversations for interactive work, routines for scheduled work, and Swarm Chat for shared coordination. Always inspect the workspace and Bot before asking for file changes.
Send and steer
Describe the result you want, relevant files, and constraints. While work is active, delivery follows Messages → Steer or Queue. Stop interrupts active work through the conversation controls; an additional message is not itself a guaranteed immediate stop.
Files and outputs
Attach relevant files or folders using the available composer controls. Published artifacts appear with the conversation. Inspect important output before sharing or using it, especially when the agent has changed files or run commands.
Long-running work
Watch model steps, usage, pending approvals, and delegated work. Compaction or a fresh context continues the same task using retained context and history; it does not reset the workspace. Put lasting decisions in an appropriate durable note rather than assuming unlimited active context.
Voice
Use voice controls when the chosen route supports them and grant microphone access when prompted. The selected realtime voice comes from the supported model configuration. If voice is unavailable, check route support and device permissions.
When something needs attention
Start with the status control on the affected screen and the transcript of the affected run. The same app can be connected to different gateways with different data and configuration.
A page is empty or actions are disabled
Confirm the intended gateway is selected and connected. Providers must be configured before model choices are usable. Some configuration changes wait for active work to finish. Use Retry or Reconnect after addressing the underlying connection issue.
A model request fails
Check provider sign-in, account access, exact model ID, supported reasoning effort, base URL, and any reported usage limit. A saved catalog entry is not proof that the remote provider accepts that model or credential.
A routine does not finish
Check whether it is enabled, has reached its end, is already running, or is waiting for approval. Inspect the workspace, time zone, next run, and failure message. The gateway needs uptime and provider access; closing the phone app is not the same as stopping the gateway.
A Bot does not reply in Swarm Chat
Check membership, Collaboration = Swarm, the exact @handle, and pending approvals or failures in its work. A user message without a mention goes to the leader; mention a coworker explicitly to address that Bot.
An extension appears inactive
Check installation on the selected gateway, activation in the Bot’s Extensions capability, saved configuration, and hook trust for the current digest. An update can require a fresh trust decision.
Ask for help
Include the app and gateway versions, affected screen, expected behavior, and the visible error. Share only the relevant transcript excerpt; remove credentials, pairing codes, and private file contents. Use /manual for command-line reference and the support link below for product help.