Install Skulk
The packaged Skulk apps are the recommended way to install and operate Skulk. They give the runtime a stable application identity, include the matching dashboard and native components, and let you start, stop, inspect, and open a node without managing a source checkout or Python environment.
Choose the path that matches the machine:
| Machine | Recommended install |
|---|---|
| Apple Silicon Mac running macOS 15 or newer | Signed and notarized Skulk menu-bar app through a DMG or Homebrew |
Ubuntu or Debian desktop, amd64 or arm64 | Skulk app and runtime through the Foxlight APT repository |
Headless Ubuntu or Debian, amd64 or arm64 | Runtime-only APT package |
| Contributor workstation, development branch, or another Linux distribution | Source installer |
macOS
Download the pinned Skulk 2.0.2 signed and notarized app directly:
Download Skulk 2.0.2 for Apple Silicon (.dmg)
Open the DMG, drag Skulk to Applications, eject the DMG, and open Skulk from Applications. macOS verifies the Developer ID signature and stapled notarization ticket before launch.
Homebrew is an equally supported install and update channel:
brew install --cask Foxlight-Foundation/skulk/skulk
Skulk is a menu-bar app: it does not keep a window or Dock icon open. After
launch, click the Skulk fox in the macOS menu bar. The menu shows the node state
and provides Start Skulk, Stop Skulk, Open Dashboard, and
Reveal Runtime Log. The app includes the exact Skulk runtime and dashboard
built for its release, so you do not need to install or approve uv, Python,
Node.js, or a source tree.
First run on macOS
- Open Skulk from Applications. The menu initially reports Stopped; that is expected because Skulk waits for you to choose to start.
- Click the Skulk menu-bar fox and choose Start Skulk.
- Approve macOS Local Network access. Skulk needs it to discover and communicate with nodes on your LAN. Skulk does not require Screen & System Audio Recording; deny that permission and report the app version if macOS ever presents it.
- Wait for the menu to report Ready, then choose Open Dashboard.
- Confirm that your Mac appears in the topology. A single Mac is a complete one-node cluster, so you can launch a model and chat before adding more machines.
Update or remove the Mac app
Choose Check for Updates… from the Skulk menu. When a newer version is available, Download version… opens its signed DMG. Install it through the same Applications-folder flow. Skulk also checks at app startup and never silently replaces itself.
If you use Homebrew, update with brew upgrade --cask Foxlight-Foundation/skulk/skulk. To remove a DMG installation, quit Skulk and
move Skulk from Applications to the Trash. Homebrew users can instead run
brew uninstall --cask skulk, which also removes the plugin service. If you
removed a DMG installation that had plugins set up, turn off Skulk's plugin
service under System Settings → General → Login Items & Extensions → Allow in
the Background.
Ubuntu and Debian
Install the Foxlight repository keyring, refresh APT, and install Skulk:
curl -fLO https://apt.foxlight.ai/foxlight-archive-keyring.deb
sudo apt install ./foxlight-archive-keyring.deb
sudo apt update
sudo apt install skulk
When sudo asks for your Linux login password, type it and press Enter. The
terminal deliberately shows no dots or other characters while you type.
The public keyring package contains only the repository's public signing key and APT source definition. The repository's private signing key is never distributed.
The skulk package installs both the desktop controller and the matching
runtime. Open Skulk from the application menu and select Start Skulk.
The app enables and starts the packaged skulk.service user unit, then gives
you controls for the dashboard, logs, node lifecycle, and cluster namespace.
Installing the package alone does not start the service without your action.
First run on Linux desktop
- Open Skulk from the application menu.
- Choose Start Skulk and wait for the status to report Ready.
- Choose Open Dashboard.
- Confirm that the local machine appears. One machine is a valid one-node cluster; add more machines only after this first node works.
The runtime package contains the exact reviewed Skulk source, locked Python environment, built dashboard, native bindings, launcher, and user service unit for that release. Linux inference engines are selected from the hardware Skulk detects; see the NVIDIA and AMD guides for hardware-specific preparation.
To update later:
sudo apt update
sudo apt install skulk
To uninstall the app and runtime:
sudo apt remove skulk skulk-desktop skulk-runtime
If you set up plugins, also remove the plugin service. It runs under your own account rather than as part of the packages, so removing them leaves it running until you log out:
systemctl --user disable --now foundation.foxlight.skulk.plugins.service
rm -f ~/.config/systemd/user/foundation.foxlight.skulk.plugins.service
systemctl --user daemon-reload
Its runtime and installed plugins stay in ~/.local/state/skulk/plugin-service;
delete that folder to remove them too.
Headless Ubuntu or Debian
On a machine with no graphical session, install only the runtime after adding the repository above:
sudo apt install skulk-runtime
systemctl --user daemon-reload
systemctl --user enable --now skulk
A systemd user service normally runs only while that user has a session. For an unattended node that must survive logout, an administrator can enable lingering for the service account:
sudo loginctl enable-linger "$USER"
Form a cluster
- Get one node to Ready and confirm it in the dashboard.
- Install the same Skulk version on every additional machine.
- Start Skulk on each machine from the app or service manager.
- Open the dashboard from any running node and confirm the machines appear in the topology.
- Pick and launch a model. Skulk places it on compatible hardware and begins serving when the placement is ready.
Nodes on the same network use Skulk's shared default namespace and discover one another automatically. You do not need to invent an identifier for an ordinary cluster. If multiple independent Skulk clusters share a network, set a custom namespace in the app on every node that should belong together. Nodes with different namespaces cannot form one cluster.
What success looks like
The dashboard first shows every connected node and its available memory. Start with one node, then add machines one at a time so a discovery or permission problem is easy to isolate.
These captures show the actual dashboard connected to a live cluster.
After a model reports ready, open Chat and send a short prompt. The response is generated by your own Skulk node or cluster.
Configure Skulk from the dashboard
Choose Open Dashboard from the desktop app, then open Settings. Expand the section you need and select Save changes when finished. You do not need to edit a configuration file for ordinary setup. The Settings guide covers model storage, downloads, inference, Hugging Face access, logging, Intelligent Fabric, telemetry, and pairing.
Add a Hugging Face token
Public repositories normally need no token. Gated or private repositories require an account with access; accept any model terms using that same account first.
- Create a token with model-read access in your Hugging Face account.
- Open dashboard Settings → HuggingFace on any node.
- Paste it into API Token and select Save changes.
- Reopen the section to confirm Token is configured, then retry the download.
The token synchronizes across the cluster, including the model-store host and nodes that join later. A dashboard-supplied token takes effect without restarting Skulk. Leaving the token field blank retains the saved value; it does not erase another node's token.
Advanced: headless token setup and launch overrides
An explicit HF_TOKEN supplied when a node starts overrides the dashboard's
token on that node. If your administrator configured such an override, changing
the dashboard token will not replace it. The administrator must change or remove
the launch override and restart that node.
Headless operators can use hf auth login to populate the Hugging Face token
file when no environment or configured token takes precedence. That file is read
at download time. Run skulk doctor on the downloading node to inspect the token
source without printing the secret. The runtime guide
covers launch environments and service configuration.
Add capabilities (optional)
Capabilities such as Skulk Video Studio are separately installed plugins. They install from the dashboard on every kind of install: the Mac app, Homebrew, the Linux packages, and the source installer. Open the dashboard on the host that will run the plugin and choose Plugins:
- The first time, Skulk sets up that host's plugin service for your user and shows its progress. It needs no terminal and no administrator password, and takes a few minutes. On Linux it needs systemd.
- Browse lists the Foxlight capability store at skulkapps.foxlight.ai. Skulk verifies the store's signatures by itself, and each card says whether a release fits this host.
- Choose Review and install, check what the plugin may do (its permissions, its screens, and whether any action can spend money), and install it with one consent.
Capabilities and Plugins covers setup inside a plugin, private catalogs, updates, and removal. Plugins need Skulk 2.0.1 or later.
First-run troubleshooting
| What you see | What to do |
|---|---|
| Skulk opened but no window appeared on macOS | Click the Skulk fox in the menu bar. A persistent Dock window is intentionally not shown. |
| The menu remains at Stopped on first launch | Choose Start Skulk. The initial startup is deliberately user-triggered. |
| The runtime does not reach Ready | Choose Reveal Runtime Log on macOS or Open Runtime Log in the Linux app. Headless operators can inspect journalctl --user -u skulk. |
| A second local node never appears | Confirm every node uses the same version and namespace. On macOS, enable System Settings → Privacy & Security → Local Network → Skulk, then stop and start Skulk. |
| macOS asks for Screen & System Audio Recording | Deny it. That permission is not part of the Skulk desktop contract. Include the app version when reporting the prompt. |
| The dashboard opens but shows only one node | That is a working one-node cluster. Start the other nodes, then troubleshoot discovery only if they do not join. |
| A gated model fails to download | Open Settings → HuggingFace, enter a token, and choose Save changes. Accept the model terms on the token's account, then retry the download. If it still fails, ask the administrator to check for a launch-time token override. |
sudo looks frozen while asking for a password | Type the Linux account password and press Enter; no typing feedback is shown. |
The macOS app does not start Skulk automatically at login. On Linux desktop, choosing Start Skulk enables the user service, so it normally starts again at later logins. Linux headless operators can explicitly enable the user service as described above.
Source and development installs
Use the source installer when you are contributing to Skulk, testing the development branch, installing on a Linux distribution that the packages do not cover, or need direct control over the source environment:
curl -fsSL https://raw.githubusercontent.com/Foxlight-Foundation/Skulk/main/install.sh | bash
The stable installer targets main. To install the development branch that
matches the /next/ documentation:
curl -fsSL https://raw.githubusercontent.com/Foxlight-Foundation/Skulk/main/install.sh | bash -s -- --ref dev
See Source builds and runtime paths for deterministic commit pins, manual setup, and the exact work performed by the installer.