Skip to content

Your own server: remote runhosts in Agentry Desktop

A remote runhost is a Linux server of your own that runs your QuickAgents for you. Agentry Desktop sets it up over SSH and then sends your runs there: they run on your server with your consent and your keys, the way they run on your computer, and their results come back to you. Agentry is not in the path, and no credits pay for the server's work.

A runhost is for runs that need a machine that stays on: a schedule that runs while your laptop is shut, a persistent agent that keeps going, or more room than your computer has. What the server installs, what it holds and who can read it are on the technical page, Remote runhosts. It also has the CLI's commands for the same things.

Setting one up in the first-run wizard

The wizard's first choice is where your runs go: Local (this computer), Remote (a server of your own) or Cloud (In Agentry). Remote's steps:

  1. Your server. Give the runhost a name, the server's address, and an admin account on it: root, or one that can use sudo. Choose that account's private key, or type its password, and its sudo password when it asks for one. Agentry uses this sign-in once and keeps it nowhere.
  2. The server's identity. A server this computer has never seen is shown to you by its host key, in a dialog, before anything is sent to it.
  3. Checks. The app reads the server without changing anything (its system, its disk and memory, the engines and open ports it already has) and shows what it found. A server Agentry cannot run on stops here.
  4. Install. Each step is shown as it runs: an agentry account, Docker Engine if the server has none, gVisor, the signed CLI, the images runs need, and the runhost's service. Then this computer is paired with it. Setup opens no network port on the server.
  5. Model. Sign the runhost in to your Claude, ChatGPT or Copilot plan from your browser here, or give it your Agentry credits. A run's own API key needs nothing here: it travels with each run.
  6. Done. The runhost becomes where your runs go by default.

You can also add one later, from Settings → Runhosts → Add a runhost.

Runs on your runhost

A run's setup asks Where: This computer, each of your runhosts by name, or In Agentry. Choose a runhost and the run goes there with its task, its input files, your answers, its secrets and its model key. The release is checked on this computer and again on the server, and its output comes back sealed for this computer alone and opens in your run history as a local run's does.

The app does not yet send a run that needs a connection (an MCP server you sign in to), a target host, or a file or repository answer to a runhost. It says so before anything is sent and gives the agentry run … --on command that does, in a terminal.

Choose Later or Repeat under When to make it a schedule on the runhost, which then runs with nobody present (desktop v0.7.7 or later). A dialog first names everything the runhost will keep for it, such as a model key or a secret, and the server it keeps them on. Each run is collected here the next time this computer reaches the runhost, at the app's start and every ten minutes.

Settings → Runhosts

Each runhost has a card:

  • Its state: whether this computer reaches it, its CLI version, and the jobs running or waiting there. After the app updates itself it updates each runhost, and the card says how that went. Anything only the server's administrator can change is shown as needing attention. Update it now does it by hand.
  • Run here by default: makes it where runs go unless you choose otherwise.
  • Sign in with your Claude, ChatGPT or Copilot plan, or Sign out, and Agentry credits: Use my credits makes a token on your account that can only pay for model use, kept on the runhost, and Revoke ends it.
  • Unsafe Mode: off unless you turn it on, with the server's admin sign-in. When it is on, every run on the runhost is an Unsafe Mode run, still under gVisor.
  • Schedules: each schedule the runhost runs, its next run and what it keeps there (never a value), with Remove, which takes it off with everything it kept.
  • Persistent agents (desktop v0.7.9 or later): the Assistant, the Coding agent and any persistent agent you installed there, each with Start and Stop. A first start asks you, in a dialog, to agree to what the agent would be given on that server. Talk sends a message and shows its answer. The agent runs on the runhost, on the model the runhost keeps, and goes on running when you close the app. Agentry Helper stays on this computer, because it works the app itself.
  • Unpair takes this computer off the runhost, and Remove takes Agentry off the server with its admin sign-in.

Pair with a runhost set up on another computer adds this computer to a runhost you set up elsewhere, with the server's admin sign-in.

What stays on this computer

Meeting notes record this computer's microphone and screen, so they never run on a runhost. A run's files open here once its output is collected.