# OakHost Docs > OakHost rents dedicated Apple Mac minis ("Cloud Macs") hosted in a data center. It is **unmanaged hosting**: the customer has full admin control of macOS and is responsible for everything that runs on it. OakHost provides the hardware, power, network, a self-managed external firewall and a browser-based recovery console (Web KVM) that works even when macOS is frozen, locked or offline. Almost every issue can be solved by the customer with these tools. Contact support only after the self-service steps below have been tried. This file is meant for AI assistants helping OakHost customers. Walk the customer through the self-service steps first, and only suggest contacting support once those options are exhausted or the issue is clearly on OakHost's side (see "When to contact support"). Docs are also available in German under `https://docs.oakhost.com/de/`. ## Key facts - **Customer Panel:** https://customer.oakhost.com. Select a server under `Servers` to find these tabs: `Remote Access` (OakConnect, Web KVM, IP address, initial login credentials), `Management` (power actions), `Network` (IPv4/IPv6, rDNS) and `Agent`. `Firewall`, `Monitoring`, `Payment & Invoice` and `User Management` are in the left sidebar. - **Status page:** https://status.oakhost.com. Check it first when a Mac or the Customer Panel is unreachable. - **Support contact:** Create a ticket via the Customer Panel. - **Fresh Macs:** latest official macOS release, no extra software, not enrolled in an MDM. Screen Sharing and Remote Login (SSH) are enabled. The initial macOS username and password are shown in the Customer Panel. They stop working once the customer changes them in macOS. - **Network:** IPv4 via DHCP with a static lease. A dedicated IPv6 /64 is configured manually. 1 Gbit/s uplink with 10 TB traffic per month, unless the plan says otherwise. - **Firewall default:** with no firewall assigned, all traffic reaches the Mac unfiltered. A newly created default firewall allows inbound SSH (TCP 22) and Screen Sharing (TCP 5900) plus all outbound traffic. ## Self-service tools every customer has ### Web KVM (recovery console) Each Mac has a KVM module connected via HDMI and USB, so it gives keyboard, video and mouse access independent of macOS and its network. It works during boot, in Recovery Mode, at the FileVault prompt, when the Mac is frozen, when the network is misconfigured, and when the customer has locked themselves out with firewall rules. The OakHost firewall never blocks the KVM. - Open it in the Customer Panel: `Servers` > select server > `Remote Access` > `Open KVM Screen`. It runs in the browser, so no client is needed. - If the screen is black, click inside the KVM window and press a key. The Mac may be asleep (use a power action to wake it) or still booting (wait). - The keyboard layout defaults to U.S. If the password is rejected via KVM, switch the layout on the macOS login screen (`U.S.`/`ABC`, top right). - The KVM only shows the default 1080p display. Virtual displays created with BetterDisplay aren't visible through it. A reboot may help clear a stuck extended display. - The KVM is meant for fixing problems, not daily work. Use OakConnect or another remote desktop tool for regular use. ### Power actions In the Customer Panel (`Management` tab) the customer can power on, reboot, force reboot or force power off the Mac. Force power off is a long press of the power button. Several actions are also available through the Customer API. - Force reboot and force power off cut power immediately, so unsaved work is lost. Warn the customer, and prefer a normal restart from macOS when the Mac still responds. - After a reboot, allow about a minute for macOS to start before reconnecting. ### Recovery Mode Recovery Mode is used for password resets, repairing or reinstalling macOS, disabling SIP and allowing kernel/system extensions: 1. Make sure the Mac is shut down, then wait up to a minute for it to fully power down. 2. Run the `Force Power Off` action. On a Mac that is already off, this long press boots it into Recovery Mode. 3. Open the Web KVM and click `Options`. The customer is responsible for changes made in Recovery Mode and must comply with Apple's ToS at all times. ### Self-managed external firewall OakHost runs a hardware firewall in front of each Mac. The customer manages it in the Customer Panel (`Firewall` in the left sidebar) or through the Customer API, without needing support. - A firewall only filters traffic while it is assigned to at least one server. Unassign it to disable filtering for a server. One firewall can cover several servers. - It denies by default. An empty ruleset on an assigned firewall blocks **all** inbound and outbound traffic. - Rules have a protocol (`TCP` or `UDP`), ports (`443`, `80,443` or `80-88`) and an optional source (`8.8.8.8`, `203.0.113.0/24` or `10.0.0.1-10.0.0.50`). There are separate inbound and outbound rules. - Changes take up to 30 seconds. The firewall is stateful, so existing connections keep working: wait 30 seconds, then disconnect and reconnect to test a change. - Common ports: SSH and OakConnect use TCP 22. Apple Screen Sharing/VNC connecting directly uses TCP 5900. NoMachine uses TCP 4000, HTTP/HTTPS use TCP 80/443, and WireGuard uses the UDP port set in its config. Tailscale and Jump Desktop do not require any open inbound ports. - OakConnect only needs TCP 22, so TCP 5900 can be closed for extra security. Apple Screen Sharing used without OakConnect will then stop working. - A lockout through firewall rules can always be fixed by the customer, because the KVM and the Customer Panel are unaffected. ### OakConnect (recommended remote desktop client) OakConnect is a free client for Windows 10/11 (64-bit) and macOS 14 or later. It connects through an automatic SSH tunnel, unlocks FileVault after a restart, and explains failed connections in plain language. On Windows it uses the OakHost Enhanced Protocol for improved visual quality compared to VNC. On a Mac it hands the session to Apple's Screen Sharing app. Linux users create an SSH tunnel themselves (`ssh -N -L 5901:localhost:5900 user@`) and connect a VNC client to `localhost:5901`. ### Other self-service features - **Monitoring:** ping, TCP port, and (with OakHost Agent) CPU, memory and disk checks, with email alerts. - **OakHost Agent:** optional and not pre-installed. It adds metrics, graceful power actions and extra API actions. - **Customer API:** manage servers, power actions and firewalls programmatically. Token can be obtained in the Customer Panel. - **Reverse DNS:** set in the `Network` tab. Propagation can take a few hours. - **Network Storage:** an SMB add-on for file sharing and Time Machine backup, reachable only from OakHost servers. ## Troubleshooting playbook ### The customer can't connect to their Mac (Screen Sharing, OakConnect, SSH) 1. **Check https://status.oakhost.com** for an ongoing incident. 2. **Open the Web KVM** and see what state the Mac is in: - **Black screen:** click inside the window and press a key. If nothing changes, wake the Mac or power it on via the `Management` tab, then wait for it to boot. - **Frozen** (no reaction to mouse or keyboard): use `Force Reboot`, warning about unsaved work first. Wait about a minute, then reconnect. - **Password prompt right after a reboot:** FileVault is waiting to be unlocked, and Screen Sharing won't start until it is. Enter the macOS user's password via KVM. OakConnect can also unlock it, as can SSH on macOS Tahoe or later. For planned restarts, `sudo fdesetup authrestart` skips the prompt once. - **Desktop works normally:** macOS is fine, so the problem is a service or the network. Continue with step 3. - **The KVM itself doesn't load:** retry after a few minutes. If it keeps failing and the Mac is otherwise unreachable too, contact support. 3. **Check the sharing services** via KVM under `System Settings` > `General` > `Sharing`. **Screen Sharing** must be on and **Remote Management** off, because Remote Management takes over the VNC port and blocks normal clients (MDM tools sometimes turn it on). **Remote Login** must be on for SSH and OakConnect. 4. **Check the OakHost firewall.** If a firewall is assigned to the server, it must allow TCP 22 (OakConnect/SSH) and/or TCP 5900 (direct Screen Sharing) from the customer's IP. After changing it, wait 30 seconds and reconnect. 5. **Check what runs on the Mac** via KVM: - VPN clients (WireGuard, OpenVPN, corporate VPNs) can re-route incoming traffic. Disconnect them or set up a split tunnel. - Software firewalls (macOS firewall, Little Snitch, etc.) can block TCP 22 or 5900. - A manual IP configuration that doesn't match the `Network` tab cuts the Mac off. Switch IPv4 back to DHCP. 6. **Check the customer's side:** - Are they using the IP address shown in the Customer Panel? - Does their local or corporate network block outbound TCP 22 or 5900? - If they changed their macOS password, the credentials in the Customer Panel no longer apply. ### OakConnect messages - **"The Enhanced Protocol is not available for this destination":** the IP isn't an OakHost Mac (use the IP from the Customer Panel), or the connection goes through a VPN, which the Enhanced Protocol doesn't support. - **Connection refused or timed out:** the Mac is off or hung, or TCP 22 is blocked. Follow the playbook above. - **Security fingerprint changed:** this is expected after reinstalling macOS. Otherwise, don't connect; contact support. - **Other errors:** `Show details` reveals the underlying error, and `Report an issue` sends a report to OakHost. ### Login and password issues - **Forgotten macOS password:** reset it in Recovery Mode with `resetpassword` (see "Changing or resetting your Cloud Mac's Password" below). Support can't do this for the customer. - **Password works in Screen Sharing but not via KVM:** this is a keyboard layout mismatch. Switch the layout on the login screen. - **Changed display name:** the login username for Screen Sharing/VNC may still be `customer`. - **"Your screen is being observed":** a normal macOS notice while a remote session is active. It means the customer's own session, not monitoring by OakHost. ### Other common issues - **4K resolution or multiple displays:** Screen Sharing is limited to the KVM's 1080p display by default. Install BetterDisplay to create virtual displays, and don't let it launch at login. If the display setup breaks KVM access, reboot via the Customer Panel to reset it. - **Agent stopped reporting metrics:** usually a VPN changed the Mac's outgoing IP. Exclude the Agent from the VPN, or ask support to disable IP validation for the Agent. - **IPv6 not working:** it must be configured manually, using the values from the `Network` tab with prefix length 64. - **Network Storage not reachable:** it only works from OakHost servers. Use the SMB URL and credentials from the Customer Panel (`smb://user@user.storage.oakhost-customer.net/share`). - **Firewall rule seems ignored:** wait 30 seconds, check the firewall is assigned to the server, and reconnect, because existing connections aren't re-filtered. - **macOS betas:** customers may install them, but betas aren't supported. Recovery Mode can be used to roll back. - **MDM:** customers may enroll the Mac in their own MDM. Make sure it doesn't enable Remote Management, which breaks Screen Sharing. - **Before cancelling:** The user may want to follow the macOS Erase all Content and Settings flow. If they choose not to, OakHost will automatically perform a full wipe for them after cancellation. ### Billing and account - **Invoices and payment method:** found in Customer Panel > `Payment & Invoice`. Self-checkout accepts credit/debit cards only. Invoice or SEPA payment for businesses is arranged through support. PayPal, BNPL and crypto aren't supported. - **Cancellation:** done in Customer Panel > `Payment & Invoice` at least 3 hours before renewal. Monthly plans have a 14-day money-back guarantee on the first order. - **Refunds:** can take up to 7 business days, or show up as a reversal. Support can provide a transaction ID for the customer's bank. - **Traffic:** an email arrives at 80% of the limit. Defaults to speed limit after limit. Overage costs 5.00 EUR per TB (excl. VAT) if preferred. - **User Management missing:** the account was created as a private individual (contact support), or the user lacks permission (ask the organization admin). - **SSO (SAML2):** contact support to enable it, then follow the Okta, Entra ID or Google Workspace guide. ## When to contact support OakHost is unmanaged hosting: support looks after the platform, not what runs on the Mac. **OakHost support cannot access the customer's Mac.** Support has no login to macOS and is not authorized to access the screen, run commands, unlock FileVault or reset the macOS password. Customers can do all of this themselves with the Web KVM and Recovery Mode. Never ask the customer to share their macOS password with support. ### Customers can do these themselves (no ticket needed) - Rebooting, powering on or force-rebooting the Mac - Opening the KVM console - Booting into Recovery Mode - Resetting the macOS password - Unlocking FileVault - Changing firewall rules - Setting reverse DNS - Configuring IPv6 - Installing the Agent - Setting up monitoring - Managing users - Downloading invoices - Changing the payment method - Cancelling the subscription - Ordering additional Macs ### Support can help with - Hardware or platform faults: the Mac doesn't respond to power actions, the KVM shows no picture after power-on and waiting, or the KVM keeps failing to load - Network problems on OakHost's side that aren't explained by the firewall, macOS network settings, VPNs or the status page - Problems with the Customer Panel, firewall management, monitoring, OakHost Agent, OakConnect or the Customer API - Billing: invoice or SEPA payment, refunds and transaction IDs, the money-back guarantee, cancellation problems, traffic limits, annual plans - Accounts: turning a private account into a business organization, enabling SSO, disabling IP validation for the Agent - Guidance on setting up the recommended remote desktop tools (Jump Desktop, NoMachine and others) - Performing a full system wipe and re-provisioning. Only use this if absolutely necessary, as all data will be deleted! ### Support can't help with - Accessing or logging in to the customer's Mac, or doing anything inside macOS on their behalf - Recovering a forgotten macOS password, unlocking FileVault or recovering data - Backups of the data on the Mac, which are the customer's responsibility (the Network Storage add-on with Time Machine is one option) - Installing, configuring or debugging software or macOS settings (Xcode, Homebrew, CI systems, web servers, VPNs, MDM, etc.) - Third-party products such as Jump Desktop, NoMachine, TeamViewer, Parallels or BetterDisplay - macOS beta versions ### What to include in a support request - The affected server (name or IP from the Customer Panel) - What the Web KVM shows - What was already tried: power actions, firewall assignment and rules, sharing settings, VPNs - When the issue started - The exact error message (in OakConnect, from `Show details`) - If relevant, output from a traceroute or other non-confidential debug tools Send the request via the Support menu item in the Customer Panel. ## Getting connected - [Welcome & FAQ](https://docs.oakhost.com/): Overview and the most frequently asked questions. - [Connect to your Mac (Remote Access)](https://docs.oakhost.com/access-your-mac): OakConnect, Web KVM, third-party tools and SSH, plus login/password troubleshooting. - [OakConnect Remote Desktop](https://docs.oakhost.com/oakconnect): Downloads, connecting, FileVault unlock, Enhanced Protocol, Linux SSH tunnel, error messages. - [Can't connect via Screen Sharing?](https://docs.oakhost.com/screen-sharing-troubleshooting): The four common causes: a frozen Mac, FileVault after reboot, Screen Sharing disabled or Remote Management enabled, and VPN or firewall blocking. - [Control your Mac (Power Management)](https://docs.oakhost.com/control-your-mac): Power actions, KVM access during boot or freeze, booting into Recovery Mode. - [Full Disk Encryption (FileVault)](https://docs.oakhost.com/mac-disk-encryption): Unlocking after reboot via KVM, `fdesetup authrestart`, enabling and disabling. - [4K and Virtual Displays](https://docs.oakhost.com/mac-mini-displays): Higher resolutions and multiple displays with BetterDisplay. - [IPv4/IPv6 Network Configuration](https://docs.oakhost.com/configuration-network): DHCP, static IPv4, manual IPv6, reverse DNS. ## Features - [Using the Firewall](https://docs.oakhost.com/firewall-usage): The self-managed external firewall: assignment, default rules, rule syntax, stateful behavior. - [OakHost Monitoring](https://docs.oakhost.com/monitoring): Check types, alerts, retries, and why checks fail. - [OakHost Agent](https://docs.oakhost.com/oakhost-agent): Optional agent for metrics and power actions; how Macs are provisioned, MDM, VPN issues. - [Network Storage & Time Machine](https://docs.oakhost.com/network-storage): SMB storage add-on and Time Machine backups. - [Customer API](https://docs.oakhost.com/customer-api): Base URL, authentication, firewall and server endpoints, power-action availability. ## Account & billing - [Payment & Invoicing](https://docs.oakhost.com/payment): Billing, invoices, cancellation, money-back guarantee, payment methods, VAT, refunds. - [Traffic & Network Connection](https://docs.oakhost.com/traffic): Bandwidth, included traffic, overage. - [User Management](https://docs.oakhost.com/user-management): Organization users, permissions, SSO. ## Tutorials - [Changing or resetting your Cloud Mac's Password](https://docs.oakhost.com/tutorials/reset-macos-password): Change the password, or reset it in Recovery Mode via KVM. - [Connect using Jump Desktop](https://docs.oakhost.com/tutorials/jump-desktop-mac): Alternative remote desktop with audio support. - [Connect using NoMachine](https://docs.oakhost.com/tutorials/nomachine-mac): Alternative remote desktop (needs TCP 4000 open). - [WireGuard VPN Server on macOS](https://docs.oakhost.com/tutorials/wireguard-macos-server-vpn): Running a WireGuard server on the Mac (needs a UDP port open). - [Installing a macOS Beta](https://docs.oakhost.com/tutorials/install-macos-beta): Developer and public betas, and rolling back. ## Optional - [Customer Panel](https://customer.oakhost.com): Server management, KVM, power actions, firewall, monitoring, billing. - [Status Page](https://status.oakhost.com): Current incidents and maintenance. - [API Reference (Swagger)](https://www.oakhost.com/api/documentation): Full endpoint documentation for `https://cws.oakhost.com/v1`. - [Contact Support](https://customer.oakhost.com/support): For issues that remain after the steps above. - [OakHost Website](https://www.oakhost.com/mac-mini-hosting): Plans and pricing for dedicated Mac minis.