Installed integrations
Most agents take Fleet's hooks at launch: a flag or a variable names them,
and Fleet writes nothing in the agent's config directory
(harness profiles). Some agents read
hooks only from their own config files. For such an agent,
fleet integration writes Fleet's hooks into its config directory, and
removes them again.
An installed integration exists only for an agent with no launch-time way.
For every other agent, fleet integration answers not needed: launch-time hooks.
Commands #
fleet integration status [<agent>|--all] [--json]
fleet integration install <agent>
fleet integration uninstall <agent>|--all
statusreports one state for each agent. With no agent, it reports every harness Fleet has a profile for.installwrites the agent's hooks. It replaces an older version that Fleet wrote.uninstallremoves what Fleet wrote for the agent.--allremoves every integration in the ledger. The ledger drivesuninstall, so it also works for an agent that has no profile now.fleet version --jsonlists each outdated integration underoutdatedIntegrations.fleet doctorchecks each integration (its checks).
The commands work on this machine only. Fleet does not install an
integration on a remote host. To use an installed agent on a remote host,
run fleet integration install <agent> on that host.
The agents #
| Agent | Harness | Config directory | What Fleet writes |
|---|---|---|---|
| Kimi Code | kimi |
$KIMI_CODE_HOME, else ~/.kimi-code |
a block at the end of config.toml; not on Windows yet |
Kimi Code reads hooks from its config.toml only. KIMI_CODE_HOME moves
its whole home, its sign-in included, so Fleet cannot name another
directory at launch.
What Fleet writes #
Fleet writes only what the profile's [install] table lists
(profile format). Each item is one of
these:
-
An own file. Fleet owns the whole file. The agent must merge it with the user's files, for example one file in a hooks directory.
-
A block. Fleet appends the block to a file that the user also edits. A first and a last comment line name Fleet:
toml# >>> fleet integration kimi, version 1: `fleet integration uninstall kimi` removes this block [[hooks]] event = "Stop" command = '[ -z "$FLEET_SIGNAL_FILE" ] || fleet signal idle --harness kimi 2>/dev/null || true' timeout = 10 # <<< fleet integration kimi
Each hook command obeys these rules:
- It exits at once when
FLEET_SIGNAL_FILEis not set. Outside a Fleet session, the hook does nothing. - It ends in
|| true. A missingfleetnever fails the agent's turn.
The rules #
- Fleet never creates the agent's config directory. When the directory is
not there,
installstops. Start the agent once, then install. - Fleet reads the config directory from the agent's own variable, for
example
KIMI_CODE_HOME. Without the variable, it uses the agent's default directory under the home directory. - Fleet does not take over a file that it did not write. When an own file
is already there,
installstops and writes nothing. installchecks the new version before it removes the old one. When the new version cannot be written, the old one stays.- One
installoruninstallruns at a time. Each holds the operating system's advisory lock onintegrations.lock, in the data directory, while it reads and writes the ledger. A second command waits a few seconds, then stops and names the file. The lock goes with its holder: a killed command does not block the next one. - On Windows, Fleet installs an integration only when its profile sets
install.windows = true. Kimi Code's hooks are POSIX shell commands, and no Windows run has checked them, so on Windowsfleet integration install kimistops with "not supported on Windows yet".statusreportsunsupported-platform. - Each write replaces the whole file:
- Fleet refuses a file with more than one hard link.
- Fleet follows a symbolic link to its real file. It refuses a file that is not a regular file.
- Fleet writes a temporary file in the same directory. Only its owner can read it while Fleet writes it. Then it gets the permissions of the file it replaces. A new file stays readable by its owner only.
- Fleet renames the temporary file over the file.
- On Windows, a rename can lose the file's access control list. So Fleet
writes an existing file in place, and keeps a backup until the write is
done:
- Fleet stops when
<file>.fleet-backupor<file>.fleet-backup.pendingis there. An earlier write was interrupted, and that backup can be the only good copy. - Fleet copies the file to
<file>.fleet-backup.pending, then renames the copy to<file>.fleet-backup. - Fleet writes the file.
- Fleet removes the backup.
- Fleet stops when
The ledger #
Fleet records each integration in integrations.json, in its data
directory. For each agent, the ledger holds:
- the version written, and the config directory;
- each own file, with a hash of its bytes;
- each block, with a hash of its bytes and the separator Fleet put before it;
- each directory that Fleet created.
Fleet writes the ledger entry before it writes the files. An interrupted
install is thus in the ledger, and uninstall removes it.
uninstall removes exactly what the ledger lists:
- It removes each own file.
- It removes each block, and the separator before it. The user's bytes stay as they were.
- It removes a file that Fleet created for a block, when the file is empty without the block.
- It removes each directory that Fleet created, when the directory is empty.
The states #
| State | Meaning | To do |
|---|---|---|
not-needed |
The agent takes its hooks at launch. | Nothing. |
unsupported |
Fleet knows no hooks for the agent. | Nothing. |
unsupported-platform |
The integration is not checked on this platform (Windows, for Kimi Code). | Nothing. |
agent-missing |
The agent's config directory is not there. | Start the agent once. |
not-installed |
The ledger lists no integration for the agent. | fleet integration install <agent> |
current |
The ledger version is the profile's, and each item is as Fleet wrote it. | Nothing. |
outdated |
The profile has a newer version, an item is missing, or the agent now reads another config directory. | fleet integration install <agent> |
modified |
A file or a block that Fleet wrote holds other bytes now. | fleet integration uninstall <agent>, then install again. |
install refuses a modified integration: it does not overwrite a
person's edit. uninstall removes the modified file or block.
A block that lost its first or its last comment line is modified too.
Fleet cannot tell where it ends, so neither install nor uninstall
changes the file. Remove the block by hand, then run uninstall again.