Synopsis

homeboy server <COMMAND>

Subcommands

Runner Machine Onboarding

For a normal runner machine, use one ID for the machine and its runner capability:

homeboy server create <runner-id> --host <host> --user <user> --port 22
homeboy runner enable <runner-id> --workspace-root <workspace-root> --concurrency-limit 4 --artifact-policy copy
homeboy runner connect <runner-id>

This records <runner-id> as the SSH server and enables runner settings on the same server record.

create

homeboy server create [--json <spec>] [--skip-existing] <id> --host <host> --user <user> [--port <port>]

- `--port` defaults to `22`.
- When `--json` is provided, CLI mode arguments are not required.
- `id` is the server ID (not a display name); it should match what you’ll reference from projects.

server_id is the <id> you provide (CLI mode) or the id field in the JSON body (JSON mode).

show

homeboy server show <server_id>

set

homeboy server set <server_id> --json <JSON>
homeboy server set <server_id> --base64 <BASE64_JSON>
homeboy server set <server_id> --json '{"auth":{"mode":"key_plus_password_controlmaster","persist":"4h"}}'
homeboy server set --json <JSON>   # server_id may be provided in JSON body

Updates a server by merging a JSON object into servers/<id>.json. Runner-capable servers store their runner settings under the nested runner object; homeboy runner enable <server_id> is the preferred CLI for adding that capability.

Arbitrary server updates must use --json or --base64; positional JSON, positional key=value, and dotted-path compatibility updates are not accepted.

Use null in JSON to clear a field (for example, {"identity_file": null}).

Options:

• --json <JSON>: JSON object to merge into config (supports @file and - for stdin)
• --replace <field>: replace array fields instead of union (repeatable)

delete

homeboy server delete <server_id>

Deletion is safety-checked:

• If any project references this server ID, the command errors and asks you to update/delete those projects first.

list

homeboy server list
homeboy server list --full

Rows are always returned under data.entities, the canonical key for every row-shaped list command; an empty registry returns "entities": [] rather than omitting the key.

The default keeps entities as a bounded summary of id, host, port, user, and kind. Runner PATH, settings, environment, and resources are omitted. output_budget uses the shared collection budget; continue_command is homeboy server list --full.

homeboy server show <id> and homeboy server list --full return the complete redacted server record. Sensitive environment values stay [redacted].

connect

homeboy server connect <server_id>

Opens an operator-authenticated SSH control-master session for servers configured with auth.mode = "key_plus_password_controlmaster". New managed-session policies require an explicit auth.persist OpenSSH ControlPersist value. Homeboy reuses the session for later server-backed commands without storing the password.

status

homeboy server status <server_id>

Checks whether the configured control-master session is live. Its persist value is a local OpenSSH ControlMaster idle lifetime, not a remote server policy.

disconnect

homeboy server disconnect <server_id>

Closes the configured control-master session.

key

homeboy server key <COMMAND>

Key subcommands:

• generate <server_id>
• show <server_id>
• import <server_id> <private_key_path>
• use <server_id> <private_key_path>
• unset <server_id>

JSON output

Note: all command output is wrapped in the global JSON envelope described in the JSON output contract. homeboy server returns a single ServerOutput object as the data payload. Fields are optional based on subcommand.

Note: all command output is wrapped in the global JSON envelope described in the JSON output contract. homeboy server returns a single ServerOutput object as the data payload. Fields are optional based on subcommand.

• command: action identifier (examples: server.create, server.key.generate)
• server_id: present for single-server actions
• server: server configuration (where applicable)
• entities: list rows. The default is the bounded summary; --full returns complete redacted server records
• updated: list of updated field names (values are command-specific)
• deleted: list of deleted IDs
• key: object for key actions
• session: object for managed SSH session actions

Note: all command output is wrapped in the global JSON envelope described in the JSON output contract. homeboy server returns a single ServerOutput object as the data payload. Fields are optional based on subcommand.

• action: generate | show | import | use | unset
• server_id
• public_key (when available)
• identity_file (when set/known)
• imported (original path used for import; ~ is expanded)

Top-level fields:

• action: connect | status | disconnect
• server_id
• control_path
• persist: effective local OpenSSH ControlMaster idle lifetime
• live
• persist_scope: explains that persist is local OpenSSH behavior, not remote policy
• stdout
• stderr

Key payload (key):

Related

• ssh