# How it runs (/docs/run)



One turn looks like this:

1. Your app or Studio sends input on a session: text, data, or
   [files](/docs/run/files). A [trigger](/docs/run/triggers) or a wake the
   agent booked can start a turn too. A message sent while a turn runs waits in
   the session's [queue](/docs/run/sessions#messages-while-a-turn-runs).
2. The Runtime calls the Tenant's model.
3. When the model calls a tool, the Runtime applies the Tenant's
   [tool policy](/docs/run/tool-policy): the call runs, waits for a person's
   approval, or is denied.
4. The Runtime runs the call: an [HTTP tool](/docs/build/tools) is one request
   to your service, and an MCP tool a call to a remote MCP server, both through
   the gateway with the secrets of the session's [Agent](/docs/run/agents). A
   shell command runs in that Agent's sandbox. An Agent is made from a saved
   [agent manifest](/docs/run/agent-manifests) and moves to new versions of it
   in place.
5. The Runtime records the turn in history.

The Runtime runs the agent from the manifest version its Agent runs, and never
calls your code during a session. Model calls, tool calls, skills, and Agents
all run in the Runtime.

```ts
import { createClient } from "@nylorun/agents";

const client = await createClient();
const session = await client.createSession({
  agent: "assistant",
  ownerUserId: "user-123",
});

await session.input("Look up order demo-123", {
  idempotencyKey: crypto.randomUUID(),
});
```

`createClient()` finds the Runtime through the project link locally, or through
`NYLORUN_RUNTIME_URL` and `NYLORUN_SERVER_KEY`.

## Pages [#pages]

| Page                                             | Basic usage                                                                    |
| ------------------------------------------------ | ------------------------------------------------------------------------------ |
| [Local Tenants](/docs/run/tenants)               | `npx nylorun start`                                                            |
| [Models](/docs/run/models)                       | `npx nylorun tenant models set`                                                |
| [Tool policy](/docs/run/tool-policy)             | `admin.toolPolicy.put({ rules })`                                              |
| [Runtime limits](/docs/run/limits)               | `admin.settings.limits.put({ limits })`                                        |
| [CLI](/docs/run/cli)                             | `nylorun <group> <command>`, `npm create`                                      |
| [Agents](/docs/run/agents)                       | `client.agents.put(id, { manifest })`                                          |
| [Saving manifests](/docs/run/agent-manifests)    | `client.agentManifests.save({ agent, runtime })` · `npx nylorun apply`         |
| [Secrets and credentials](/docs/run/credentials) | `client.agents.secrets.put(id, name, { value })`                               |
| [Triggers and wakes](/docs/run/triggers)         | `runtime.triggers` · `client.agents.runs(id)`                                  |
| [Agent memory](/docs/run/memory)                 | `harness.memory` · `client.agents.memories.put(id, path, content)`             |
| [Sessions](/docs/run/sessions)                   | `client.createSession({ agent, ownerUserId })`                                 |
| [Events](/docs/run/events)                       | `session.history()` · `session.observe()`                                      |
| [Traces](/docs/run/traces)                       | `session.trace(turnId)`                                                        |
| [Pauses and control](/docs/run/control)          | `session.cancel({ idempotencyKey })`                                           |
| [Files](/docs/run/files)                         | `client.artifacts.upload(…)` · `session.inputParts(parts, { idempotencyKey })` |
| [Studio](/docs/run/studio)                       | `npx nylorun studio`                                                           |

Under `npm run dev`, saving a file saves each agent again as a new version of
its manifest. The starter's Agent tracks its manifest, so it moves to each new
version in place, and each session's next turn runs it; a turn already running
ends on its version.

## Next step [#next-step]

<Cards>
  <Card title="Local Tenants" description="Start, stop, and inspect the installation." href="/docs/run/tenants" />

  <Card title="Sessions" description="Create a session and send input." href="/docs/run/sessions" />
</Cards>
