| name | offload |
| description | Use when the user wants to run a long or resource-heavy task on another computer so their local machine stays free, the work continues if they close their laptop or lose connection, and the result returns as a reviewable branch in their project. Use this skill also when no offload target exists yet and the user needs help setting one up. |
| argument-hint | <plain description of the work to hand off> |
Offload
Help the user offload work to another computer, or set up and configure the target computer. A
correct offload preserves the local project's behavior: it rebuilds the same environment from the
project's Nix flake, runs the requested work there, and returns the result as a branch in the user's
project.
You do NOT do the requested work yourself when this skill is invoked. You must start it on the
remote target.
$ARGUMENTS
Infer what you can from the project and request. Ask only when the choice matters: spending money,
using an online account, choosing between valid targets, or changing project configuration.
How To Speak To The User
Keep the narration and explanation clear and direct. When describing setup, focus on what the user
needs to do and what will happen, without introducing internal names, implementation details, or
technical jargon such as Fly Machines, Nix, foolfad, Nixie, or transport adapters. Use those terms
only if the user requests more detail, demonstrates familiarity, when providing exact command lines,
or when relaying an error that includes them.
Do not expose setup probes in user-facing narration. For example, do not say "FOOLFAD_TRANSPORT is
unset" or "the flake has no x-offload marker" unless the user asks for implementation details.
Say that no saved remote computer is configured for this project yet.
When setup is needed, keep the user oriented around the visible phases:
- Create the remote computer.
- Add the required secrets before starting it.
- Save the local connection details.
- Connect the remote computer to GitHub so it can fetch and push branches.
- Run a tiny end-to-end check, then run the requested work.
Do not describe a raw connection check as "the transport works" to the user. Say the remote computer
is reachable, then immediately explain the next visible requirement.
When no target is set up yet, say something like:
I can help you set up a remote computer on Fly.io. It will require logging in with your Fly.io
account, and Fly may charge for the remote computer while it exists.
When explaining access to web pages or dev servers, say that the remote computer gets a public web
address and Nestail auth protects the shareable links. Avoid implying that the user needs to
understand Fly internals or configure networking by hand.
Supporting Skills
Use supporting skills for specialized work: foolfad for the hand-off and foolfad-config for remote
GitHub and assistant setup. Provision and manage the target with the official Fly.io CLI (fly).
If a skill is missing, try npx skills --help and npx skills add <repo> --list; foolfad and
foolfad-config are in ToxicPine/tissloolly.
Tools
Three custom commands are involved. Run foolfad locally for the actual hand-off; it starts the
other commands on the remote target.
- foolfad runs locally, inside the user's git project. It pushes the project's current state to
the remote target as branch
foolfad/<run-id>, then starts the remote work. It does not pull
results back by itself. For a fixed command, that command must push its own changes. For an
open-ended task, boondoggle commits and pushes the result.
- boondoggle runs on the remote target, inside the copied project. It gives a coding assistant,
such as Codex or Claude Code, a goal, lets it run until done, then commits changes and pushes them
back on the run branch. Use it through
foolfad when the task is open-ended, such as "make this
feature work", rather than one exact command. Configure the assistant through foolfad-config; see
references/assistants-on-the-machine.md.
- vusperize runs on the remote target and wraps the work so it can send live progress pings,
for example to Telegram. Use it for long jobs or when the user asks for progress updates. If the
user wants Telegram pings and they are not set up yet, see
references/setup-telegram.md.
foolfad reaches the target through a transport (see "Find the target") and starts boondoggle or
vusperize there. The Fly target keeps its files between restarts, rebuilds project dependencies
fresh each run, and has the remote-side tools installed. If no target exists, set one up with
references/provision-remote-machine.md. Otherwise assume one exists.
Running the hand-off
Use Nixie directly for local offload dependencies. Resolve <skill-dir> as the directory
containing this SKILL.md. The Nixie-generated wrapper is <skill-dir>/scripts/nix. It behaves like
the nix command: when system Nix is installed it delegates to system Nix, and when Nix is missing
it downloads and runs Nixie's static Nix in the user's cache. It is not a custom package launcher.
The offload dependency environment is a small flake at <skill-dir>/scripts/deps. Use this command
shape for local setup tools:
<skill-dir>/scripts/nix develop <skill-dir>/scripts/deps -c <command> ...
For brevity, the rest of this skill writes that prefix as <offload-nix>. It provides local
dependencies such as fly, openssl, git, jq, and the original foolfad-transports package
(foolfad-fly, foolfad-ssh, foolfad-tailscale, etc). Run tissloolly commands such as
foolfad and foolfad-configure through <skill-dir>/scripts/nix run or
<skill-dir>/scripts/nix shell against github:ToxicPine/tissloolly.
Examples:
<offload-nix> fly auth whoami
<offload-nix> fly status -a <app>
<skill-dir>/scripts/nix run github:ToxicPine/tissloolly#foolfad -- -- <command>
Offloading still works cleanly only when the target can rebuild the project environment from
flake.nix. That keeps dependencies and behavior consistent after the work moves. On the target,
prefer Nix-run invocations when commands are not already installed:
nix run github:ToxicPine/tissloolly#boondoggle or
nix run github:ToxicPine/tissloolly#vusperize -- ....
Fly CLI auth must be ready before provisioning a new target. Use
<offload-nix> fly auth whoami to check,
<offload-nix> fly auth login to log in, and
<offload-nix> fly --help or the Fly docs when a command option needs
confirmation.
Fly targets must have Nestail auth enabled. Before using a Fly target, ensure its app has
NESTAIL_AUTH_SECRET set. Check with <offload-nix> fly secrets list -a <app>.
If it is missing, generate a fresh secret with
<offload-nix> openssl rand -hex 32 and set it with
<offload-nix> fly secrets set -a <app> NESTAIL_AUTH_SECRET="$secret". Treat this
as machine-level secret state; do not commit it, print it, or reuse a placeholder.
Authenticated Nestail links must be generated on the target. The nestail token ...
command needs the target's NESTAIL_AUTH_SECRET, so do not run it locally unless the local computer
is the target. Use the saved FOOLFAD_TRANSPORT to run it remotely, or ask the Telegram
conversational agent on the target to generate the link. For example:
printf '%s\n' 'nestail token 3000 /dashboard' | bash -c "$FOOLFAD_TRANSPORT"
If the remote does not have nestail on PATH, run the target-side equivalent that the machine
provides, but keep the generation on the remote so the secret never leaves the machine.
Check the flake offload marker before doing anything with the flake. Use nix flake show (or
nix flake show --json) to look for top-level x-offload. Treat it as a hint, not a guarantee:
"configured" means an offload worked at some point. Try it; if it breaks because setup drifted,
move it back to "untested" while you re-check the setup, then restore "configured" after a
successful offload."untested" means setup was attempted and nothing obvious blocks it, but no successful offload is
known yet."none" means there is a hard reason not to offload, or the user does not want offloading for this
project. Optionally add x-offload-none-reason with a few dense words.
When you become confident the flake will work for offloading, set x-offload = "untested";. After a
successful offload, set x-offload = "configured";. If you find a real blocker, or the user
declines offloading, set x-offload = "none";.
Keep it in outputs beside the existing outputs:
outputs = { self, nixpkgs, ... }: {
x-offload = "configured";
# existing outputs...
};
Check that the project rebuilds on the target. Review flake.nix and any .envrc: will the
rebuilt project have the dependencies and settings this task needs? This is a sanity check, not an
audit. If setup is incomplete or there is no flake.nix, tell the user and offer to fix it first,
usually by adding or extending a devShell and .envrc. foolfad copies the whole project, so any
secret the devShell cannot provide must not travel as plaintext. Offer to encrypt it with age or
sops-nix. Ask before changing anything.
Find the target. foolfad reaches it through FOOLFAD_TRANSPORT, usually Fly:
<skill-dir>/scripts/nix develop <skill-dir>/scripts/deps -c foolfad-fly --app <app> --machine <machine-id>.
Plain SSH and Tailscale transports are still valid for user-managed boxes, but Fly is the default
when this skill provisions the machine.
Hand it off.
- One exact command:
<skill-dir>/scripts/nix run github:ToxicPine/tissloolly#foolfad -- -- <command>. This runs on the
remote branch. To return changes, the command must commit and push them itself.
- Open-ended task:
<skill-dir>/scripts/nix run github:ToxicPine/tissloolly#foolfad -- -- bash -lc 'printf "%s" "<task>" | nix run github:ToxicPine/tissloolly#boondoggle'.
The configured assistant works until done, then pushes the result back as a branch. This requires
an assistant, such as Codex or Claude Code, configured through foolfad-config
(references/assistants-on-the-machine.md).
The work starts inside the project directory on the remote target, so the environment (devShell,
.envrc) loads on its own. Do not wrap the command in cd or nix develop. For long jobs or
progress pings, wrap the command with vusperize, which runs alongside it on the remote target.
Report back. Tell the user which branch receives the work, which target ran it, and how to check
progress later. foolfad-target and boondoggle-runs are target-side skills. They are useful when
the user talks to an agent on the remote target, for example over Telegram. If the user is local
only, use FOOLFAD_TRANSPORT to run a target-side command that asks the remote agent or Codex to
inspect the run and print the answer back locally.
When reporting a dev-server URL for a Fly target with Nestail auth enabled, generate the shareable
URL on the remote target with nestail token <port> <path> through FOOLFAD_TRANSPORT, or have the
Telegram agent on the target do it. Do not construct a grant URL locally and do not ask the user to
copy NESTAIL_AUTH_SECRET back to their local shell.
Follow-up questions
For how to view a dev server through the public Fly URL, why an address won't load, or who else can
see it, read references/frequently-asked-questions.md before answering.
