Hunter B
84 lines
2.4 KiB
Markdown
84 lines
2.4 KiB
Markdown
# Agent Fleet
|
|
|
|
Agent Fleet is the local-first control plane for durable multi-worker runs. The
|
|
initial CLI surface is:
|
|
|
|
```sh
|
|
codewhale fleet init
|
|
codewhale fleet run tasks.json --max-workers 4
|
|
codewhale fleet status
|
|
codewhale fleet inspect <worker-id>
|
|
codewhale fleet interrupt <worker-id>
|
|
codewhale fleet restart <worker-id>
|
|
codewhale fleet stop --all
|
|
```
|
|
|
|
Fleet state is stored under the workspace in `.codewhale/fleet.jsonl`. Worker
|
|
logs and adapter logs are stored under `.codewhale/fleet/` and
|
|
`.codewhale/fleet-host/`.
|
|
|
|
## Task Spec
|
|
|
|
`codewhale fleet run` accepts JSON or TOML. A minimal JSON spec:
|
|
|
|
```json
|
|
{
|
|
"name": "local smoke",
|
|
"tasks": [
|
|
{
|
|
"id": "lint",
|
|
"name": "Lint",
|
|
"instructions": "Run the lint check and report failures.",
|
|
"expected_artifacts": ["log"]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Workers are optional. If omitted, CodeWhale creates local worker slots up to
|
|
`--max-workers`.
|
|
|
|
## Host Adapters
|
|
|
|
The host adapter boundary supports local child processes and explicit SSH
|
|
workers. Adapters expose the same operations: start, read status, read bounded
|
|
logs, interrupt, restart, stop, and cleanup.
|
|
|
|
Local workers run as child processes with stdin closed and stdout/stderr written
|
|
to bounded fleet host logs. They inherit only a small safe base environment
|
|
such as `PATH` and explicitly allowlisted variables.
|
|
|
|
SSH workers run through the system `ssh` client with `BatchMode=yes` and a
|
|
bounded connect timeout. Remote environment variables are sent with OpenSSH
|
|
`SendEnv`; values are not embedded in the local ssh argv or fleet logs.
|
|
|
|
Example SSH worker spec:
|
|
|
|
```json
|
|
{
|
|
"id": "builder-1",
|
|
"name": "Builder 1",
|
|
"host": {
|
|
"kind": "ssh",
|
|
"host": "builder.example.com",
|
|
"user": "codewhale",
|
|
"port": 22,
|
|
"identity": "~/.ssh/codewhale_fleet",
|
|
"working_directory": "/srv/codewhale/work",
|
|
"env_allowlist": ["CODEWHALE_PROFILE"],
|
|
"codewhale_binary": "/usr/local/bin/codewhale"
|
|
},
|
|
"capabilities": ["local", "linux", "tests"],
|
|
"max_concurrent_tasks": 1
|
|
}
|
|
```
|
|
|
|
Defaults are intentionally conservative:
|
|
|
|
- no hosted control plane or cloud provisioning is enabled;
|
|
- SSH requires an explicit host, working directory, and CodeWhale binary path;
|
|
- secret-like environment names such as `TOKEN`, `SECRET`, `PASSWORD`,
|
|
`API_KEY`, and `PRIVATE_KEY` are rejected from adapter allowlists;
|
|
- secrets should remain in CodeWhale config providers or remote host config,
|
|
not in task instructions, argv, or fleet logs.
|