Hosted vs local agents

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 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 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 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

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.