llms.txt
# Udon
> Udon turns an Apple Silicon Mac into a home server. Run containers, install
> apps, share files, and manage the machine from a browser, with an optional AI
> assistant. macOS 26 or later. Try free for 5 days, then a one-time license per Mac.
## Docs
- **Getting started**
- [Introduction](/docs): Udon is a remote management tool for macOS with a browser dashboard and a phone companion app.
- [Install](/docs/install): Install Udon on macOS 26 or 27, finish setup in the Welcome window, update it, and uninstall while keeping your data.
- [Sign in & accounts](/docs/accounts): Create the first admin account, sign in to the Udon dashboard, turn on two-factor authentication, and add users with admin, operator, or viewer roles.
- [Udon Docs MCP](/docs/docs-mcp): Search Udon docs with your AI assistant.
- **User Guides**
- The dashboard
- [The dashboard](/docs/dashboard): Arrange live dashboard tiles, pin container apps, set a wallpaper and theme, restart the Mac, and search containers, settings, and files with Cmd+K.
- [Custom widgets](/docs/dashboard/widgets): Build a custom dashboard tile in the Widget Editor from one HTML file, fed by a shell command or HTTP request, with its own refresh interval and buttons.
- Containers
- [Containers](/docs/containers): Run, update, and remove containers on your Mac with Apple's container engine or OrbStack, and open each one's logs, shell, and resource stats.
- [Deploy a container](/docs/containers/deploy): Run a container from any image in the Run dialog with its ports, volumes, and environment variables, or build a Docker Compose stack in the Composer.
- [Stacks](/docs/containers/stacks): Group related containers into a stack, a Docker Compose project on OrbStack or an Udon group on Apple Container, and start, stop, or restart it as one.
- [App Store](/docs/app-store): Install self-hosted apps from Udon's catalog, any public Docker Hub image, or a Homebrew package on your Mac, with dependencies listed first.
- [Packages](/docs/packages): Browse, upgrade, and remove the Homebrew formulae and casks installed on your Mac from the browser, with a live terminal for every action.
- [Storage & files](/docs/storage): Browse your Mac's volumes and disks, check SMART disk health, mount network shares, share folders over SMB, and upload or download files from the browser.
- [Network & remote access](/docs/network): Set the Mac's IP address and DNS, connect Tailscale, serve the dashboard with a trusted certificate, and reach your containers remotely by their own IPs.
- [Terminal & remote desktop](/docs/terminal): Open a shell on your Mac from the browser, keep sessions running between visits, and view or control the Mac's screen through macOS Screen Sharing.
- [AI Assistant & MCP](/docs/ai): Connect Claude, GPT, a local model, or a coding CLI to deploy and debug apps by chat, and expose Udon's tools to external AI clients over MCP.
- [Workflows](/docs/workflows): Run synced workflows for Udon's AI assistant, write local ones with instructions, reference files, and scripts, import a SKILL.md, and export a ZIP.
- [Activity](/docs/activity): Watch CPU, memory, disk, network, and energy use on your Mac process by process from the browser, and quit or force quit anything that misbehaves.
- [Monitoring](/docs/monitoring): See live CPU, memory, network, power, and disk use for your Mac on the dashboard, and check that Udon's permissions and container engine are healthy.
- Troubleshooting
- [Verify Full Disk Access](/docs/troubleshooting/full-disk-access): Recover when Udon still reports missing Full Disk Access after you turn on its System Settings switch.
- [Udon won’t start or finish setup](/docs/troubleshooting/startup): Check the daemon, resolve permission prompts, and recover from an installation or update failure.
- [An update failed or Udon did not reconnect](/docs/troubleshooting/updates): Recover from a failed update check, interrupted installation, or rollback without deleting Udon's data.
- [Uninstalling or reinstalling Udon](/docs/troubleshooting/uninstall): Resolve cancelled authorization, partial removal, and ownership errors, then recover your data and license after reinstalling.
- [The dashboard will not open](/docs/troubleshooting/dashboard-unreachable): Check whether Udon is running, recover local access, and trace LAN, Tailscale, or certificate failures.
- [Can't sign in](/docs/troubleshooting/sign-in): Recover from a sign-in lockout, rejected authenticator codes, a lost authenticator, or a forgotten password.
- [A container will not install or start](/docs/troubleshooting/container-wont-start): Recover an unavailable engine, identify image-pull and startup failures, and resolve Compose deployment errors.
- [A container app will not open](/docs/troubleshooting/container-app-unreachable): Check app startup, published ports, HTTP or HTTPS, dependencies, and Tailscale routes when a running container is unreachable.
- [I can't access files or share a folder](/docs/troubleshooting/files-and-sharing): Check disk access, account permissions, uploads, SMB shares, and container data folders.
- [Udon is locked](/docs/troubleshooting/license-locked): Check a license lock, restore verification, or pick up a purchase that has not appeared in Udon.
- [A package install or update appears stuck](/docs/troubleshooting/package-install-stuck): Check Homebrew availability, answer terminal prompts, and verify a package action before retrying it.
- [Terminal or Remote Desktop won't connect](/docs/troubleshooting/terminal-remote-desktop): Recover terminal connections and check Screen Sharing and macOS credentials for Remote Desktop.
- [Assistant or MCP connection fails](/docs/troubleshooting/assistant-connection): Check assistant provider errors, pending approvals, and external MCP connections with missing or rejected tools.
- **Administration**
- [Settings](/docs/settings): Every Udon Settings page, the macOS settings it can change from the browser (energy, updates, sharing, network), and how to grant Admin Privileges.
- [Menu bar app](/docs/menu-bar): Finish setup in the Welcome window, start and stop Udon, keep the Mac awake, check permissions, and uninstall Udon from its macOS menu bar app.
- [Licensing & updates](/docs/licensing): Try Udon free for 5 days, buy a lifetime license for your Mac, check your license, and install updates.
- [Security](/docs/security): How Udon protects your Mac home server with a non-root daemon, HTTPS, strict session cookies, and hashed passwords, and how to report a vulnerability.
- API Reference: Udon HTTP API
- [API reference](/docs/api): How to authenticate against Udon's HTTP API, the roles it checks, and its main HTTP and WebSocket endpoints.
- Activity
- [Sample the process table](/docs/api/activity/listProcesses): One sample of the host's running processes, taken when the request arrives; the daemon runs no background loop. CPU, disk, and wakeup figures are rates measured against the previous call, so the first call after startup reports zeros for them. Processes the daemon may not inspect are omitted. Requires the **operator** role.
- [Stop a process](/docs/api/activity/terminateProcess): Sends SIGTERM, or SIGKILL when `force` is set. Admin only, and recorded in the audit log.
- Ai
- [Answer an assistant question](/docs/api/ai/answerAIQuestion): Replies to an open `ask_user` question in the latest turn, then resumes the run server-side. The answer is capped at 4000 characters. Only the owner of the conversation may answer.
- [Approve or deny a pending tool call](/docs/api/ai/approveAITool): Records an allow or deny decision for a tool call that is waiting on the user, then resumes the run server-side. Only the owner of the conversation may decide.
- [Cancel the running turn](/docs/api/ai/cancelAITurn): Stops the conversation's in-flight turn, if any. Only the owner may cancel.
- [Create a conversation](/docs/api/ai/createAIConversation): Starts a conversation owned by the signed-in user. Only that user can read, continue, or delete it.
- [Generate an MCP access token](/docs/api/ai/createMCPToken): Creates (or replaces) the MCP access token. `role` defaults to `operator`. Admin only. The token is returned once.
- [Delete a conversation](/docs/api/ai/deleteAIConversation): Deletes a conversation the signed-in user owns. One belonging to anyone else returns 404, so its existence is never revealed.
- [Local CLI provider status](/docs/api/ai/getAICLIStatus): Readiness of a local-CLI provider. There is no API key: configured means the CLI is installed on this Mac and signed in. Admin only.
- [Get a conversation](/docs/api/ai/getAIConversation): The rendered message thread, including tool calls and any pending approvals. Only the owner may read it; a conversation belonging to anyone else returns 404, so its existence is never revealed.
- [Get assistant settings](/docs/api/ai/getAISettings): The AI connector settings. Never returns the API key, only whether one is set. Requires the **viewer** role.
- [List conversations](/docs/api/ai/listAIConversations): Conversations started by the signed-in user, newest first. Chats are private, so the list never includes another user's conversations, and a role does not change that.
- [List available models](/docs/api/ai/listAIModels): The configured provider's model ids, for the settings dropdown. Falls back to a static list when the provider can't be reached. Requires the **viewer** role.
- [The tool catalogue and MCP exposure](/docs/api/ai/listAITools): Every tool the assistant can call, with the group and tier the settings page renders, and whether an MCP client may currently reach it. Admin only.
- [Tool approvals for a local CLI](/docs/api/ai/mcpApprovalJSONRPC): A one-tool MCP server (`approve`) that a local CLI provider asks before it runs a tool, so the person in the Udon conversation can allow or deny the call. Udon gives the CLI a run ticket in the `ticket` query parameter; without a live ticket every call is denied. It authenticates like `/api/mcp` and is not meant for external MCP clients.
- [End an MCP session](/docs/api/ai/mcpEndSession): Ends the MCP session named by the `Mcp-Session-Id` header, so a long-lived client can let go of its id instead of waiting for the idle sweep.
- [MCP server-initiated stream (unsupported)](/docs/api/ai/mcpGetStream): The MCP Streamable HTTP transport's GET opens a server-initiated event stream. Udon does not offer one, so this always answers 405 with an `Allow` header, as the MCP specification prescribes.
- [MCP JSON-RPC endpoint](/docs/api/ai/mcpJSONRPC): A Model Context Protocol server over JSON-RPC (Streamable HTTP). Supports `initialize`, `ping`, `tools/list`, and `tools/call`. Authenticate with the MCP bearer token (external clients) or a signed-in session. A client sees only the tools switched on in the MCP tab of the Assistant settings (`mcpTools` on `GET /api/ai/settings`; null means the recommended set), and each call is gated by the token's (or user's) role. `initialize` returns an `Mcp-Session-Id` header to send on later requests. Protocol versions 2024-11-05, 2025-03-26, and 2025-06-18 are accepted. Send `Accept: text/event-stream` to receive the reply as a Server-Sent Event; a `tools/call` that carries a progress token streams progress notifications before its result.
- [Revoke the MCP access token](/docs/api/ai/revokeMCPToken): Deletes the stored MCP access token, so external clients using it stop being authenticated. Admin only.
- [Send a user message](/docs/api/ai/sendAIMessage): Stores a user message and starts the turn server-side, so it runs to completion even if the client navigates away. Open the stream endpoint to follow along.
- [Follow a turn (SSE)](/docs/api/ai/streamAIConversation): Subscribes to the conversation's running turn (started by the send, approve, or answer endpoints) as Server-Sent Events: `status`, `delta`, `message`, `tool_result`, `approval_request`, `approval_resolved`, `awaiting_approval`, `user_question`, `awaiting_input`, `usage`, `done`, `cancelled`, and `error`. Buffered events replay first, then live ones; disconnecting only drops this subscriber, never the run.
- [Test the connection](/docs/api/ai/testAIConnection): Tests the saved connection. A local CLI must be installed and signed in; a hosted or custom provider must answer, and list the chosen model if it lists any. A pass marks the connection verified; a failure clears that and switches the assistant off. Admin only.
- [Update assistant settings](/docs/api/ai/updateAISettings): Updates the connector. Admin only. Pass `apiKey` to set/replace it, or `clearKey` to remove it. Changing the provider, model, base URL, or key clears the verified flag and switches the assistant off until the connection is tested again.
- Auth
- [Begin two-factor setup](/docs/api/auth/beginTwoFactorSetup): Starts TOTP setup for your own account and returns the secret and the `otpauth://` URL for the authenticator app. Two-factor stays off until the first code is confirmed via the enable endpoint. Requires the **viewer** role.
- [Disable two-factor](/docs/api/auth/disableTwoFactor): Turns two-factor off for your own account, confirmed with your password. Requires the **viewer** role.
- [Enable two-factor](/docs/api/auth/enableTwoFactor): Confirms the pending TOTP setup with a code from the authenticator and turns two-factor on, returning one-time recovery codes. Requires the **viewer** role.
- [Current user](/docs/api/auth/getCurrentUser): The signed-in user. Requires the **viewer** role.
- [Your two-factor status](/docs/api/auth/getTwoFactorStatus): Whether your own account has TOTP two-factor enabled. Requires the **viewer** role.
- [Sign in](/docs/api/auth/login): Sign in with a username and password. Public; sets the session cookie.
- [Sign out](/docs/api/auth/logout): End the session. Requires the **viewer** role.
- [Refresh the session](/docs/api/auth/refreshSession): Rotates the session token and extends it to the full 30-day lifetime, so a signed-in client can stay signed in without re-entering credentials. Requires the **viewer** role.
- Catalog
- [App catalog](/docs/api/catalog/getCatalog): The installable apps from the Udon Community catalog. Requires the **viewer** role.
- Containers
- [Check for image updates](/docs/api/containers/checkContainerUpdates): Re-check every container's image against its registry now, instead of waiting for the periodic refresh. Requires the **operator** role.
- [Create a network](/docs/api/containers/createNetwork): Create a container network. Requires the **operator** role.
- [Delete a network](/docs/api/containers/deleteNetwork): Delete a container network. Requires the **operator** role.
- [Delete a volume](/docs/api/containers/deleteVolume): Delete a named container volume. Requires the **operator** role.
- [Container runtime selection](/docs/api/containers/getContainerConfig): The configured container runtime, every runtime Udon can use with its install state, and what the active engine supports. Requires the **viewer** role.
- [Container logs](/docs/api/containers/getContainerLogs): The last 500 lines of a container's logs as plain text. Requires the **viewer** role.
- [Container run spec](/docs/api/containers/getContainerSpec): A container's current configuration, rebuilt into the shape `POST /api/containers` accepts, so a container can be recreated or edited from what it runs today. The daemon parses each engine's own inspect output, so this response is the same shape for every container engine. Requires the **viewer** role.
- [Container stats](/docs/api/containers/getContainerStats): Live resource stats for a container. Requires the **viewer** role.
- [Container stats history](/docs/api/containers/getContainerStatsHistory): The sampled history behind the container charts, oldest sample first. The daemon samples every five seconds while a stats stream is open or a history read came in during the last minute, so a first read can return `collecting` with no samples. Requires the **viewer** role.
- [Container engine status](/docs/api/containers/getEngineStatus): Whether the container engine is reachable, and its version. Requires the **viewer** role.
- [Inspect a container](/docs/api/containers/inspectContainer): Inspect a container, returning the engine's own `inspect` output. Its shape differs between engines; `GET /api/containers/{id}/spec` gives one shape for all of them. Requires the **viewer** role.
- [Kill a container](/docs/api/containers/killContainer): Kill a container, optionally with a signal. Requires the **operator** role.
- [List containers](/docs/api/containers/listContainers): List containers with engine status. Requires the **viewer** role.
- [List networks](/docs/api/containers/listNetworks): List container networks. Requires the **viewer** role.
- [Remove a container](/docs/api/containers/removeContainer): Remove a container, optionally forcing it. Requires the **operator** role.
- [Restart a container](/docs/api/containers/restartContainer): Restart a container. Requires the **operator** role.
- [Run a container](/docs/api/containers/runContainer): Create and start a container from a `RunSpec`. Requires the **operator** role, or the **admin** role when the spec reaches the host through a host path in `volumes`, any `mounts`, `devices`, or `extraArgs`, an escalating capability in `capAdd`, or a shared host namespace such as host networking. Mounting the host root is refused for every role, and so is sharing a host namespace on OrbStack.
- [Set auto-start](/docs/api/containers/setContainerAutoStart): Start (or stop starting) this container automatically when the daemon boots. Keyed by container name, so a recreate keeps the setting. Requires the **operator** role.
- [Select the container runtime](/docs/api/containers/setContainerConfig): Switch the daemon to another container runtime. A real change restarts the daemon to apply it. Requires the **admin** role.
- [Start a container](/docs/api/containers/startContainer): Start a container. Requires the **operator** role.
- [Stop a container](/docs/api/containers/stopContainer): Stop a container, optionally with a timeout. Requires the **operator** role.
- [Container stats stream](/docs/api/containers/streamContainerStats): A live Server-Sent Events feed of the newest sample for every container, every five seconds. Each event's `data` is a JSON object with `state` and `samples`, a map from container id to that container's newest `ContainerSample`. In this stream a sample's `timestamp` is a number of seconds since 2001-01-01 UTC; the history endpoint sends ISO 8601. An open stream keeps the sampler running. Requires the **viewer** role.
- [Update a container's image](/docs/api/containers/updateContainer): Pull the newest build of the container's image tag, then recreate the container from its current configuration (name and volumes kept). A failed pull leaves the old container running. Requires the **operator** role; host-escalating configurations require the **admin** role.
- Dashboard
- [Create a widget](/docs/api/dashboard/createWidget): Create a dashboard widget. Requires the **admin** role.
- [Clear a container icon](/docs/api/dashboard/deleteContainerIcon): Clear a container's custom icon. Requires the **operator** role.
- [Clear the login background](/docs/api/dashboard/deleteLoginBackground): Remove the sign-in background media. Requires the **admin** role.
- [Clear the wallpaper](/docs/api/dashboard/deleteWallpaperImage): Remove the wallpaper media. Requires the **operator** role.
- [Delete a widget](/docs/api/dashboard/deleteWidget): Delete a dashboard widget. Requires the **admin** role.
