Hosted agent sessions

Applies to: Hosted session.

A hosted session is a run that happens at your AI provider, on your own provider key. Ithura runs no machine for you. You do not host anything and you do not install anything. You add a key, create an agent, and delegate a task.

If you would rather run the agent on a machine you host, see Your runner. Both kinds of agent work the same way from the task's point of view: the same questions, the same pull requests, the same stop button and the same budgets.

For a step by step start, follow Your first hosted agent task.

Set the agent provider key

The key is separate from the key for the in-app assistant. You set it in two places.

  • Workspace key. A workspace admin adds it under Settings, AI, in the card "Agent provider key". Every project in the workspace uses it.
  • Project override. A project admin can add a different key for one project, in the project's settings under Repository, in the card "Agent provider key for this project". That project then uses its own key and its own sandbox settings.

A project with neither key cannot start hosted sessions.

The card has these fields:

  • API key. An Anthropic API key. It is checked when you leave the field. You see "Key works" or "The key was refused" with the reason.
  • Model. The list comes from your key. The recommended model is marked.
  • Effort. Low, medium, high, xhigh or max. Medium is the default.
  • Extra allowed hosts. See Network access.

Use Save to store the settings and Test now to check the key again. The key is never shown back to you. To change it, use Replace key. A person who is not an admin sees the settings and is told to ask an admin to change them.

When the key is saved and ready, the card says "Saved. Hosted sessions can start."

Remove or change a key

Remove key asks you to confirm: "Remove the key? Hosted sessions stop until a new key is added." On a project, Remove override sends the project back to the workspace key.

You cannot remove or change a key while a hosted session is running on it. You are told to stop the session or wait for it to end, then try again.

When a key is removed or changed, Ithura tries to clean up the setup it made at your provider with the old key. This is best effort and never blocks the change. If a live hosted session still uses those objects, they are left in place. If anything is left over, you can delete it in your provider's console.

Choose Hosted session or Your runner

Each agent has a Runs on setting. You pick it when you register the agent in Settings, Agents, and you can change it later on the agent.

  • Hosted session (your provider key). The run happens at your provider.
  • Your runner. A machine you host runs ithura-agent. See Your runner.

If no provider key exists, the Agents page tells you: "Hosted sessions need an agent provider key. Add one in AI settings."

What happens when you delegate a task

  1. The session starts. Ithura starts a session at your provider with the task, the repository and the agent's instructions. If no session slot or budget is free, the run shows that it is waiting for a free session, or waiting for budget, and starts when there is room.
  2. The agent works and the steps appear. The run view shows what it looked at, changed and ran, and what it committed. You can send guidance or press Stop. See Stopping and steering a run.
  3. It asks when it is blocked. The task moves to Needs you with the question and a few options. Your answer continues the same session. If the session is gone, a new one starts on the same branch with a summary of the work and your answer.
  4. It runs the checks. Before it reports, the agent runs the project checks from the repo contract. If a check fails, it may fix the work and run the checks again, a limited number of times.
  5. Ithura opens the pull request. The agent only pushes its branch. Ithura opens the pull request, or updates it, as the Ithura GitHub App. The agent has no token to open it itself.
  6. You review. Review and merge are yours.

The agent works only on the task's own branch. It never commits to your base branch and never force-pushes. It follows the rules in your repository, such as CLAUDE.md, AGENTS.md and CONTRIBUTING.md.

If the branch has no commits beyond the base branch, the run finishes as no change and no pull request is opened.

Review before the pull request

Each agent has a checkbox Review before PR. When it is on, an automatic review pass runs before the pull request opens. A separate read-only session looks at the diff. If it finds serious problems, they go back to the same session for one fix round, and then the pull request opens. If the review cannot run, the pull request says so.

What the pull request says

The title is the task reference and the task name. The body has the summary, the decisions the agent made, the checks it ran (each marked passed, failed or skipped, with its command), the review results, a link to the run with its cost, and a link to the task. Without a repo contract, it says there are no checks configured.

Rework

When a reviewer asks for changes, when you reply on the task, or when you answer a question, the run continues on the same session. The agent first merges the base branch into its branch. If that conflicts and it cannot settle it safely, it asks you. Rework always updates the same pull request. Within 24 hours of the last report the same session continues. After that, or after a run that failed, a new session picks up the pull request branch with the earlier summary and your feedback.

Stop

Stop asks the run to end. The agent gets a short time to commit what works as "WIP: stopped by a person" and push it to a branch named after the task branch with -wip on the end. It never pushes that work to the task branch. The run ends as stopped. If the agent does not finish saving in that time, the run still ends as stopped, without a -wip branch.

Cost

The run receipt shows the session's cost at your provider's list price, to the cent. Ithura adds no charge on top. If your account has a discount with the provider, you pay less than the receipt shows. When Review before PR ran, the receipt has a separate "Review pass" row with its cost and tokens, and the run total includes it.

A receipt can gain a row shortly after the run ends. Providers report some costs late, and Ithura adds them to the run they belong to rather than dropping them or putting them on the next run, so a total may rise by a few cents after you first see it. That late cost counts toward the budget period in which it arrives.

A run also has a cost cap per run. You set it per agent, between 0.50 and 50 USD. The default is 10 USD. The run stops when it reaches the cap, and says so. The cap that applies is the smallest of the per-run cap, what is left of the agent's budget and what is left of the workspace budget. Sessions that are running hold the budget they may still spend, so a new run can wait for budget until they finish.

See Agent budgets.

Limits per plan

How many hosted sessions can run at once depends on the plan:

PlanSessions at once
Free1
Starter2
Pro4
Enterprise8

This is also the most that one agent can run in parallel. An active trial counts as Pro. Hosted sessions need a connected GitHub repository, which is available from Starter.

A hosted run may last 30 minutes on Free and 120 on paid plans. A run that reaches the limit ends and says so. The agent's settings show the limits of your plan.

Network access

A hosted session can reach GitHub, your AI provider, the common package registries and the language download sites. It cannot reach anything else.

If your build needs another host, add it under Extra allowed hosts, one host per line. A project with its own key has its own sandbox, so its hosts apply to that project only.

Every extra host widens the ways data can leave the sandbox. Add only hosts you trust.

Where session data lives

Session data lives with your AI provider, in your account there. Ithura keeps the run's summary, steps and receipt on the task.

Protect your base branch

Agents push to their own branch and open a pull request. But anyone with write access can still push straight to your base branch. Turn on branch protection in GitHub.

When the base branch is not protected, the project settings card shows "The base branch is not protected" with a link to your branch settings. It is a warning. It never blocks a run.

When a run does not start

A run that cannot start says why on the run:

MessageWhat to do
No agent provider key is set.Add a key in the workspace settings, then delegate again.
The provider rejected the key.Replace the key in the agent provider settings, then delegate again.
No GitHub repository is connected for this task.Connect one, then delegate again.
Ithura could not get access to the repository.Check the GitHub connection, then delegate again.

When the provider fails during a run

A problem at your provider part way through a run (a usage or rate limit, no credit left, a key that no longer works, or an outage) does not always show its cause in how the run ends:

  • A key the provider rejects ends the run as failed and says the key was rejected.
  • An error the provider reports during the session shows as a step in the run, with the provider's own text.
  • A session the provider closes ends the run as failed with "The session ended at the provider before the agent reported a result."
  • A provider that cannot be reached is retried. A short outage costs a pause and the run carries on. A long one keeps the run waiting until it reaches its time limit, and it ends with the time-limit message.

When a run ends as failed this way, the task comes back to you under Needs you. Nothing retries it on its own. When the provider works again, reply on the task or delegate it again, and a new session picks up the branch.

If the person behind the agent leaves

A hosted agent acts as one person. If that person leaves the workspace, the agent shows "Needs an owner" and new tasks cannot be given to it. A workspace admin can take it over.