Skip to content

Target hosts: a server you name when the run starts

A target host is a machine you name when a run starts, such as a Linux server for a QuickAgent to set up or manage. The QuickAgent says that it takes one, never which one, so one QuickAgent serves every server its users have: you give the address, and how you sign in to it, each time you run it.

The runner on your computer opens the SSH session, not the agent: it does so from a container of its own, the host link, and the agent works the server through the host link's tools. The agent never holds the SSH session or your sign-in.

Target hosts are for runs on your own computer only, with Agentry Desktop or the CLI. Agentry does not run a QuickAgent that declares one in its sandbox (see Local only).

How you spot one

A QuickAgent that takes a target host shows it everywhere its access is listed:

  • on its page, the Declared capabilities badge target hosts: server (the name is the question that asks for it);
  • in the install consent, on the site, in the desktop app and in agentry install, the row target hosts: asks for a server when it runs, and can run any command on it as the account you sign in with;
  • on your Installed list, target hosts: server in the row's summary.

A new version that adds a target host asks for your consent again, as any version that widens its access does. On Search, the capability filter asks for targetHosts finds QuickAgents that declare one.

What you are asked

When the run starts, for each target host:

  • The server, as ssh takes it: [user@]host[:port], for example admin@server.example.com or admin@192.168.1.20:2222. An IPv6 address goes in brackets. The user is your own user name if you leave it out, and the port is 22. A password never goes in the address.
  • How you sign in: a private key file (and its passphrase, if it has one), or a password, or a sign-in you saved before.
  • A sudo password, if you want the agent to run commands with sudo and sudo asks for one. It is optional. The agent can use it but never sees it.

In the desktop app these are fields under the question: the server, with the servers you used recently on that computer, Sign in with (the sign-in saved here, a private key file, or a password), and sudo password. With the CLI they are flags, or a prompt at the terminal:

agentry run you/server-helper --intake server=admin@box.example.com --host-key server=$HOME/.ssh/id_ed25519

--host-key <id>=PATH names a key file, and --host-password <id>=ENV_NAME, --host-passphrase <id>=ENV_NAME and --host-sudo-password <id>=ENV_NAME each name an environment variable that holds the value. A flag never takes the secret itself.

The address is resolved by your computer, so a name on your tailnet or your local network works as it does for your own ssh. The run reaches the first IPv4 address the name gives; a server with no IPv4 address is refused. Private, LAN and tailnet addresses are reached. Your own computer (loopback), link-local addresses (a cloud's metadata address among them) and addresses that are no one machine are refused, and the runner's policy can narrow the rest to the networks you list.

What the agent can do there

Whatever the account you sign in with can do on that machine. There is no approval per command: the account is the limit, so sign in as an account that holds only what the work needs. The agent has:

  • one-shot tools: run a command line and get its output and exit status (host_run, with sudo when you gave a sudo password), read and write a file (host_read, host_write), and copy a file to or from the run's scratch folder (host_put, host_get);
  • an interactive shell (host_shell_open, host_shell_send, host_shell_read, host_shell_close), for what one command line cannot do: an installer that asks questions, a sudo prompt, a program answered as it runs. The agent reads it as text, not as a screen.

What the server prints reaches the agent as it is, so the agent can read its configuration and logs. The one thing masked in everything the agent sees, and in every file the run leaves, is your sign-in for that server: the key, its passphrase, the password and the sudo password. A sign-in shorter than 8 characters is not masked in the run's files (nor, under 6, in what the agent sees), and the receipt says so. The agent is told that what a server prints is data, never instructions.

The server's own network is outside the run. What a command does with it, once it runs there, is up to the account's rights on that machine.

Where your sign-in goes

Your key, passphrase or password goes to the host link alone, as files only it can read, and they are deleted when the run ends. It is not given to the agent, the model, the run's other containers, the run's inputs or the receipt. A run with a target host happens on your computer, so the sign-in is not sent to Agentry.

If you choose to save a sign-in, it is kept in your system keychain (on Windows, the Credential Manager; on macOS, the Keychain; on Linux, the Secret Service), under the account and the server. A key is saved as its file's path, never the key itself. Later runs, schedules and the agentry command read it from there. You can remove it from the desktop's host field, or from the keychain itself.

Host keys

Before it signs in, the runner reads the key the server offers and checks it:

  • A key you already accepted, in your own ~/.ssh/known_hosts or in Agentry's own list, is used. Agentry reads your known_hosts and never writes it.
  • A key on neither list is shown to you, with its type and SHA256 fingerprint, and the run goes on only if you accept it: the desktop asks Accept this host key?, and the CLI asks at the terminal. An accepted key is kept in Agentry's own list. A run with no one to ask (a schedule, a script) refuses an unknown key.
  • A key that has changed since you accepted it refuses the run, every time, and names both fingerprints. If the server was reinstalled, remove its old entry from the file that holds it (your ~/.ssh/known_hosts, or Agentry's own, ~/.agentry/runner/known_hosts) and accept the new key on a run you watch.

Schedules

A schedule on your computer can run a QuickAgent that takes a target host. When you make it, you give the server and the sign-in once, and accept the host key; the schedule keeps the server, a reference to the sign-in saved in your keychain, and the accepted key. Each scheduled run uses those, and refuses if the sign-in is gone or the key has changed. It needs the CLI v0.6.111 or newer.

What the receipt says

Every run's receipt names each target host: the account, the server as you named it and the address your computer resolved it to, the port, the host key's fingerprint and where it was accepted (your known_hosts, Agentry's list, or at this run's start), how you signed in and where that came from (never the value), how many calls the agent made, and that the server's own network was outside the run.

Beside it, receipts/host-<id>.log has one line for each call: the tool, the command or the file, whether it used sudo, the exit status and the size of what went each way. Each shell session leaves a transcript, receipts/host-<id>-shell-<n>.log, with what was typed and what the shell printed. Both pass through the same masking as above, and the sudo password appears only as the name of the key the agent pressed.

Local only

A QuickAgent that declares a target host does not run in Agentry's sandbox. Signed in, its page and its run setup say so in place of Run in Agentry: This release works a server you name over SSH, which only a run on your own computer does, so Agentry does not run it. The site starts no run, schedule or re-run of it in Agentry, and the runner refuses a target host in any run it knows to be hosted. Run it with Agentry Desktop or the CLI, from the computer that can reach the server.

Making one

In the QuickAgent Builder, add a question and set its type to host (a server). The Builder declares a target host for each such question (capabilities.targetHosts in agent.yaml), up to four, and the summary before Submit says what it lets the QuickAgent do. Write the instructions for the work on the server; the address and the sign-in belong to whoever runs it, so never put either in the manifest or the instructions.

By hand, the two halves name each other:

intake:
  - id: server
    prompt: "The server to set up"
    type: host
    required: true
capabilities:
  targetHosts: [server]

A target host is not network egress, and it is not a scan finding by itself: AI Review reads it as declared access to that machine. A support script your QuickAgent ships that runs ssh itself is still the release reaching a host on its own, and the scan reports it as before. An exec declaration that names ssh, scp, sftp or rsync draws a warning that points at targetHosts, and a low finding in the scan. The format's full rules are in the package format, and the runner's side in running them.