# Skiff Skiff is Insula for Linux with no window. It is the same core as the desktop app: agent, [Insula Network](/wiki/10-insula-network), file transfer. You point it at a folder and leave it running. Sign in with the same account as your desktop. The skiff joins your private network as a named peer. Another Insula — usually a desktop window — can send files to that folder and ask the skiff to do work. It is lighter than the desktop app because it has no window. Typical use is a worker on a machine that holds a project. This is not [Open Remote](/wiki/08-remote-servers) (an SSH window onto a host) and not [Dashboard Companion](/wiki/13-companion) (a website seat on a live process). ## Download Get the Linux binary from [insulalabs.io/#/releases/skiff](https://insulalabs.io/#/releases/skiff). That page is the Skiff release channel. It shows one card per platform (Linux amd64 and arm64). Each card is the newest upload for that platform (newest by upload time). The card shows the version, file name, size, a sha256 prefix, and **Download**. Compare that version to `insula-skiff version` (or the version line from `status`) on the machine. If the page is newer, replace the binary and start serve again. The same page offers a JSON copy of that latest-per-platform list (**Show raw JSON**, or the `/api/releases/skiff` link on the page). Useful for a script. Not required if you only need the download. ## Sign in ``` insula-skiff login ``` This prints a portal URL. Open it in any browser. The browser does not have to be on the Linux host. Approve the sign-in, then paste the `insula://` callback URL shown after approval. Use the same account as your desktop. ``` insula-skiff status # version, username, plan insula-skiff logout # end this device session ``` State lives under `~/.insula`. To keep a skiff apart from anything else on the machine, or to run several as different accounts, give it its own home: ``` insula-skiff --home /srv/skiff-a login insula-skiff --home /srv/skiff-a serve --launch /srv/projects/api --callsign api-bot ``` Pass the same `--home` to every command for that skiff. ## Serve ``` insula-skiff serve --launch /srv/projects/api --callsign buildbox ``` This opens the folder, joins the network as `buildbox`, and stays up until interrupt (SIGINT or SIGTERM). The callsign is how the peer appears on your desktop Hub and Network strip. Callsign rules: 2–32 characters, lowercase letters, digits, or hyphens. It must start with a letter and must not end with a hyphen. `hub`, `transfer`, `mesh`, and `insula` are reserved. The callsign must be unique on your network. Serve exits if it is taken. A chat model must already be available (synced from your account, or set up on that machine). Without one, inbound asks fail. For a lasting service: ``` [Service] ExecStart=/usr/local/bin/insula-skiff serve --launch /srv/projects/api --callsign api-bot Restart=on-failure ``` ## Allow commands Skiff has no approval cards. A command that is not on the allowlist waits two minutes, then is denied. Seed the list before you serve. Prefix match on a word boundary (`git` matches `git status`, not `gitx`): ``` insula-skiff settings allow add git insula-skiff settings allow add npm insula-skiff settings allow add go insula-skiff settings allow add python3 ``` Allow by pattern: ``` insula-skiff settings allow add --regex '^git (status|diff|log)' ``` Allow everything (only on a machine you fully trust the agent with): ``` insula-skiff settings allow add --regex '.*' ``` Inspect and remove: ``` insula-skiff settings show insula-skiff settings allow rm git ``` This is the same allowlist the desktop **Always allow** button writes (`~/.insula/settings.json`). ## Send files While serving, incoming Network transfers are always accepted. There is no toggle. Files land in the `--launch` folder root with collision-safe names. Desktop windows still prompt; only skiff auto-accepts. The network only connects processes signed in as the same account. You can always drop files to your own skiffs. 1. Run `insula-skiff serve --launch --callsign ` on the host. 2. On your desktop, sign in as the same user with Network up. Do not be attached to an [Open Remote](/wiki/08-remote-servers) session — that hides Network send. 3. Drag files from the file tree onto the skiff’s row in the Network strip, or open Hub, select the peer, and send files. 4. The skiff log shows `transfer offer: auto-accepting`, then `transfer complete`. The files are in the folder root. 5. Ask your desktop agent to have the skiff use them — same ask as any other peer, by callsign. Transfers always land in the root of the launched folder. There is no way to target a subfolder or a different folder from the sender. ## Ask the skiff There is no chat tab. Asking a skiff is the same [Insula Network](/wiki/10-insula-network) ask as any other peer. On the desktop, with Network up, tell that window’s agent to ask the skiff by callsign: run the tests, summarize failures, and so on. The skiff answers against its launched folder. It handles one inbound ask at a time. Do not phrase work so the skiff has to ask a question back. Those questions have no answer path and sit until the turn times out. ## If it fails - `not logged in` — run `insula-skiff login` first, with the same `--home` you serve with. - `callsign taken` — another peer on your network already uses that name. Pick another. - `project is locked by another Insula process` — the desktop app or another skiff has that folder open. - Desktop cannot see the skiff — both must be signed in as the same account. Check `insula-skiff status` and the serve log’s `skiff serving` line. - Sending from desktop does nothing — you are in an Open Remote session, or the peer is stale; wait for reconnect. - Agent will not run commands — check `settings show` and add allowlist entries. The serve log warns `approval pending` with the exact command. - No answer to asks — no chat model resolved. The serve log prints `no chat provider resolved` at start if so. ## Commands ``` insula-skiff [--home ] login sign in (prints portal URL, paste the insula:// callback) logout sign out and end this device session version print the Insula version status print auth status serve --launch --callsign run headless on a folder, joined to the network as (incoming Network file transfers are auto-accepted into the folder) settings show print agent settings settings allow add [--regex] add a terminal allowlist entry settings allow rm remove terminal allowlist entries matching ``` ## Related topics - [Insula Network](/wiki/10-insula-network) - [Agents](/wiki/05-agents) - [Subscriptions](/wiki/09-subscriptions) - [Remote servers](/wiki/08-remote-servers) - [Dashboard Companion](/wiki/13-companion)