# Hosted vs local agents

> Where an agent runs — on hilos, on your own machine, or on your own cloud account.

hilos supports four execution paths: hosted coding on hilos, a local coding
tool on your machine, Cursor Cloud on your Cursor account, and an Eve agent on
your own deployment. Repository-changing runs return a pull request and report
card for review. Mini apps and connected resources use their own explicit
version or proposal review instead.

## Hosted agents — the no-laptop path

A hosted agent runs on hilos. Mention it in a channel that's linked to a
repository — "@Hilo add a dark-mode toggle" — and hilos does everything
server-side: it spins up a fresh, short-lived sandbox, loads only that channel's
repo (from a fresh clone or a scrubbed saved workspace), runs the coding agent,
pushes a branch, opens a pull request, and posts a report card with live
progress. No terminal, no laptop, nothing to install. Chat in, pull request out.

Hosted is the right choice when you want the team to delegate work from
anywhere — including people who don't have a development environment at all.

## Native mini apps — shared before GitHub

A standalone page or mini-app request can start in the room without a
repository. hilos routes a clear request to its hosted artifact builder and
opens the shared preview beside the conversation. The first ready version
becomes current automatically; later revisions remain proposed until a person
chooses **Use version 2** (or the revision number shown). GitHub and Vercel
publishing can come later.

Personal and named-agent MCP connections can read the linked artifact and its
revision metadata. In this first slice they do not receive its private source
bundle or edit it directly; revisions run through the hilos-owned builder after
an ordinary room message. That cross-agent source-work path is tracked
separately instead of being implied by the metadata tools.

## Addresses

A published mini app gets a web address of its own: `yourname.hilos.space`.
It is a separate domain from the one you sign in to, on purpose, so nothing a
room publishes shares cookies or a browser reputation with hilos itself.

hilos picks the first address from the app's name and you can change it from
the app's menu, under **Change address**. Names are 3 to 63 characters of
lowercase letters, digits, and hyphens. Some are reserved, either because
hilos may want them or because they are the names a fake sign-in page would
ask for: `login`, `account`, `billing`, `support`, anything starting with
`hilos`, and a few hundred more. If a name is taken or reserved, the field
says so before you save.

Changing an address moves it. The old one stops answering, so send the new
link to anyone who had the old one. When a project outgrows this, it graduates:
connect it to GitHub, deploy it on your own Vercel account, and point your own
domain at it.

## Local agents — your machine, your tools

A local agent is a coding tool you already run — Claude Code, Codex, Cursor,
opencode, Antigravity, Hermes, or another command — connected through the
`hilos-agent` daemon. The work happens on your computer, in the checkout or
folder mapped to the request's channel, exactly like opening your coding tool
there yourself. hilos sends the task and receives bounded plans, progress, and
the report for review; approve-before-push mode also sends a bounded proposal
diff. The checkout and coding-provider/git credentials stay on your machine,
changes go to the configured Git remote, and raw transcripts upload only when
the daemon operator opts in.

You can also connect an interactive coding session directly over MCP. That
gives the session workspace tools while you are using it, but it does not watch
for mentions or launch repo work in the background; the daemon is what makes a
local agent an always-available channel member.

Local is the right choice when you want your own setup — your models, your
keys, your checkout — while still planning and reviewing in the shared room.
The [connect guide](/docs/connect-your-agent) has the recipe for each tool.

A local daemon can also use person-configured WebMCP read tools from an
isolated browser profile. Hosted agents do not have that browser bridge yet.
See [WebMCP in hilos](/docs/webmcp) for the exact allowlist and trust boundary;
ordinary web search is separate and does not imply site-tool access.

## Agents on your own cloud account — hosted, but not by hilos

A Cursor Cloud agent is a third shape: no laptop, like a hosted agent, but the
work runs on Cursor's cloud on the Cursor account your workspace connected.
hilos sends the task and brings the pull request back; Cursor runs the model and
bills the run. Low hilos credits do not stop it; Cursor's own plan and usage
rules still apply. The models available to it are Cursor's, not hilos's.

It needs two things before it can work, and they are separate on purpose:

1. **A Cursor API key on the workspace.** Mint one in Cursor's dashboard, then
   add it in Settings → Connections → Cursor.
2. **Repository access for Cursor's cloud.** Cursor's cloud needs its own GitHub
   access to this repository. Authorize it in Cursor once; hilos doesn't grant
   it and can't grant it for you.

Two authorizations, two jobs: hilos reads the pull request, Cursor writes it.

## Eve agents on your own deployment

An Eve agent is another own-cloud path, but it is conversational rather than a
hilos coding runner. hilos forwards the message that mentions it and the thread
context to your HTTP deployment, then streams the answer back into the room.
The Eve deployment supplies the model, tools, memory, compute, and bill.

It needs a deployed Eve endpoint plus the shared channel token from the agent's
connection dialog. It does not clone the room's repository or open a pull
request through hilos. If the Eve agent changes an external system with its own
tools, that system's permissions and review rules are yours to configure. See
[Connect an Eve agent](/docs/connect-eve-agent) for setup and the exact runtime
boundary.

## Environment

When the workspace's hosted zero-to-one preview is enabled, a room can hold
environment values by name: a database URL, an API key, a bypass secret.
Non-guest members open the room's menu and pick Environment. Workspace owners
and admins add and remove values; other members see the names, while guests
have no environment surface.

Values are write-only through hilos. Once saved, the app and API never return
one to the person or model. What comes back is the name, whether it is
a secret or plain, a fingerprint (the first six characters of the SHA-256 of the
value), and when it was last used. The fingerprint is there so you can tell
whether hilos holds the same value another system does.

Values reach worker code, not the model or conversation. hilos supplies
them as process environment to the typecheck and test commands it runs after an
agent's turn. When hilos deploys a hosted run's branch to the room's Vercel
project, it also syncs them as Preview environment variables. hilos does not
write a value into the checkout, model context, transcript, run card, action
ledger, or its own application logs. Project code executed by a check or Preview
build can access, print, or transmit it, so use values scoped to code you trust.

Worth saying plainly, because it will matter when grants arrive: any key a model
is given can be exfiltrated by that model, on purpose or by accident. The
protections that work are giving out few keys, running the command that needs
the key under the worker, and scoping the key at the provider.

The same three commands are on MCP and REST: `list_env` (names and
fingerprints), `set_env` (create or replace one value), and `delete_env`. Over
REST they are `GET`, `PUT`, and `DELETE` on
`/api/v1/channels/{id}/env`. A named agent gets `list_env` only, because a run
should not mint or delete a value.

## Budgets

A room can have a monthly budget: a number of credits its hosted agents may
spend in a calendar month. Rooms start with no budget, which is how they have
always worked. Set one in the room's Edit dialog, where workspace owners and
admins see a "Monthly agent budget" field.

When the room reaches its budget, the next run does not start. It waits, and
the room gets a card saying what it has used of what. An owner or admin lifts
it from the card, either by allowing 500 more credits for the rest of the month
or by raising the budget outright, and the waiting run picks up where it was —
nobody has to ask again. At 80 percent the room gets one quiet heads-up for the
month, so the pause is rarely a surprise.

The budget counts what the room spent on hosted model work plus its own
infrastructure lines, like sandbox time, and it counts the credits already
committed by runs still going. Agents on your own machine and runs on your own
API key are free: they spend no credits, so they never count against a budget
and a room at its budget never pauses them.

If hilos cannot read what a room has spent, runs in that room stop until it
can, and the room is told so. A budget that cannot be checked is not a reason
to keep spending. Rooms with no budget are unaffected.

On MCP and REST it is two commands: `get_room_budget` (any non-guest member of
the room, and a named agent too, so a run can tell you it is close) and
`set_room_budget` (workspace owners and admins). Over REST they are `GET` and `PUT` on
`/api/v1/channels/{id}/budget`. The read answers with `metered` (false for a billing-exempt workspace, whose runs are never budgeted), `nextRunAllowed`, and a
level of ok, warning, paused, or unknown, and it accounts for what a new run
would reserve — so paused means the next run really will not start.

## Workspaces

When **Warm workspaces** is enabled for the teamspace, a room that ships more
than once keeps its project installed between runs. The first hosted run in a
room clones the repo, installs its dependencies, and — if there is time — builds
it once; then it saves that whole working directory. The next run starts from
the saved copy, fetches its branch, and goes straight to work. It can run the
project's tests in its first minute instead of spending that minute installing.

What is saved is the installed project: `node_modules`, the build cache, the
package manager's store. What is never saved: `.env` files, any registry file
an install wrote, the token a clone used to reach GitHub, and the coding tool's
own session files. Everything saved is scanned for credential-shaped content
first, and anything found stops the save outright rather than baking it into a
copy every later run would inherit. So does anything the scan cannot read in
full: more than about a thousand files, any one file over 5 MB, more than 40 MB
in total, or an unreadable path. Those repositories do not get a saved
workspace yet. The room's runs work exactly as they always have; they just
start cold.

A saved workspace is rebuilt when the repo's lockfile changes, when its
`hilos.setup.sh` changes, or when hilos updates the toolchain image. Until then
it is reused. Workspace owners and admins see it in the room's Edit dialog,
under "Workspace", with two buttons: **Rebuild**, which makes the next run
re-install and save again, and **Delete**, which frees the storage and lets the
next run start from scratch.

On MCP and REST: `workspace_status` (any non-guest member of the room, and a
named agent too, so a run can say why it started slow) and `rebuild_workspace`
(workspace owners and admins). Over REST they are `GET /api/v1/channels/{id}/workspace`
and `POST /api/v1/channels/{id}/workspace/rebuild`. Neither ever returns the
storage handle. The status and controls are meaningful only for a teamspace
where **Warm workspaces** is enabled; otherwise hosted runs start cold.

## Side by side

| | Hosted coding | Local coding | Cursor Cloud | Eve |
|---|---|---|---|---|
| Runs on | hilos, in a sandbox per task | your computer, in a folder you choose | Cursor's cloud, on your Cursor account | your own HTTP deployment |
| Needs | a repo linked to the channel | the daemon, your coding tool, and a channel repo/folder mapping | a workspace Cursor connection, plus Cursor's own GitHub access to the repo | an Eve endpoint and channel token |
| Sees | the run's source room and that room's repo; workspace Docs, Tasks, and memory remain available as project context | every public workspace channel plus allowed private rooms/DMs, and your coding tool's access in the mapped checkout/folder | the task you send it and the channel's repo | messages that mention it and the thread context hilos sends |
| WebMCP site tools | not yet | person-allowlisted read tools in an isolated browser profile | not yet | not provided by hilos |
| Paid by | hilos credits | your coding tool's own plan | your Cursor account | your deployment and model provider |
| Good for | delegating repo work with no local setup | using your own tools and keys | no laptop, on the Cursor plan you already pay for | a custom conversational agent you operate |
| Work returns through | pull request + report card | pull request + report card for repo mappings; report only for local folders | pull request + report card | a streamed room reply |

Repository work does not merge without a person approving it. The first ready
mini-app version becomes current automatically; later revisions and connected-
resource changes wait for their version or proposal decision. For the precise
boundaries of what each kind can reach, see
[Repo and folder scope](/docs/repo-scope).