# Use the hosted runtime

> Choose the agent that answers, name the signed-in user, point the runtime at another Super Assist origin or at a route of your own, keep the open thread in the URL, and handle a refused connection.

`useAssistedRuntime` connects the panel to a Super Assist project with its publishable key. The [tutorial](https://superassist.app/tutorials/add-an-assistant.md) sets up a project and mounts the panel. This page covers the hook's other options. The [reference](https://superassist.app/reference/react.md#useassistedruntime) lists them all.

```tsx
const runtime = useAssistedRuntime({ key: process.env.NEXT_PUBLIC_SUPER_ASSIST_KEY! });
```

## Answer with another agent

The project's default agent answers unless you pass `agent`, the id of another agent of your organization. The id is on the agent's page in the dashboard, behind the copy button beside its name:

```tsx
const runtime = useAssistedRuntime({
  key: process.env.NEXT_PUBLIC_SUPER_ASSIST_KEY!,
  agent: process.env.NEXT_PUBLIC_SUPER_ASSIST_AGENT,
});
```

Each agent keeps its own threads for each end user, so another agent starts with another thread list.

## Name the signed-in user

Pass the signed-in user, and their threads follow them across browsers. Super Assist takes the id as you give it and records it as unverified, so use an id that is stable and not guessable by other users:

```tsx
const runtime = useAssistedRuntime({
  key: process.env.NEXT_PUBLIC_SUPER_ASSIST_KEY!,
  user: session ? { id: session.user.id, name: session.user.name } : undefined,
});
```

Without a user, the browser is a visitor. The hook keeps a random id in `localStorage`, one per publishable key, and the visitor's threads stay with that browser until its storage is cleared. A visitor's threads are never merged into a user's when they sign in.

## Point at another Super Assist origin

`host` is the Super Assist origin, `https://superassist.app` by default. Set it when your app talks to another one, such as Super Assist's own development server on `http://localhost:4310`. An unset variable falls back to the default:

```tsx
const runtime = useAssistedRuntime({
  key: process.env.NEXT_PUBLIC_SUPER_ASSIST_KEY!,
  host: process.env.NEXT_PUBLIC_SUPER_ASSIST_HOST,
});
```

## Point at a route of your own

Super Assist's dashboard chats with an agent over a route its session cookie authenticates, with no publishable key. `basePath` points the runtime at such a route on the page's own origin: the thread list opens on `basePath`, and each thread on `basePath/:id`, both the Cloudflare Agents sockets the hosted route serves. Pass a key or a `basePath`, not both:

```tsx
const runtime = useAssistedRuntime({ basePath: `api/v1/agents/${agent.id}/threads` });
```

## Keep the open thread in the URL

The hook picks a thread on its own: the one you pass as `thread`, else the most recent, and a new one when there are none. `onThreadChange` reports every pick, so a page can keep the open thread in its URL and open the same thread after a reload:

```tsx
const runtime = useAssistedRuntime({
  key: process.env.NEXT_PUBLIC_SUPER_ASSIST_KEY!,
  thread: searchParams.get("thread") ?? undefined,
  onThreadChange: (id) => router.replace(`?thread=${id}`),
});
```

## Handle a refused connection

Super Assist checks the key, the page's origin, the agent and the end user before it opens anything. A refused connection closes with a code, and the hook does not retry it:

| Code   | Why                                                                              | Fix                                                             |
| ------ | -------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `4401` | The publishable key is unknown, or it was rolled.                                | Use the project's current key.                                  |
| `4403` | The page's origin is not one of the project's allowed origins.                   | Add the origin under **Allowed origins** on the project's page. |
| `4404` | The project has no default agent, or `agent` names no agent of the organization. | Pick the project's **Default agent**, or pass an agent's id.    |
| `4400` | Neither a user nor a visitor id was sent.                                        | Pass a `user` with an `id`, or leave `user` out for a visitor.  |

A new project allows `http://localhost:3000` and `http://localhost:5173`, so add your production origin before you deploy. Open the project in the dashboard, enter the origin under **Allowed origins**, and press **Add**. The [API](https://superassist.app/docs/api) sets `allowedOrigins` and `defaultAgentId` too, with `PATCH /api/v1/projects/{id}`.

An allowed origin is a scheme, host and optional port, such as `https://shop.example.com`, or `https://*.example.com` for every subdomain.

`onConnectionError` gets the error with the code in `error.code` and the reason in `error.reason`. It logs to the console by default. To show it, keep it in state:

```tsx
const [refused, setRefused] = useState<string>();
const runtime = useAssistedRuntime({
  key: process.env.NEXT_PUBLIC_SUPER_ASSIST_KEY!,
  onConnectionError: (error) => setRefused(error.reason),
});
```