# Run an agent

import { Steps } from "@astrojs/starlight/components"
import Prereqs from "@docs/Prereqs.astro"
import UiWalkthrough from "@docs/UiWalkthrough.astro"
import ClientTabs from "@docs/ClientTabs.astro"

Start an agent run by creating a [session](/docs/deep-dives/concepts/agents/sessions/) on a project and sending it a prompt. A session is a single conversation with an agent. It tracks messages, permissions, and state from idle through completion.

This guide covers starting a run interactively. To kick off unattended runs from CI or your own scripts, see [Trigger from your code](/docs/guides/automate/trigger-session-via-api/).

<Prereqs>
  - A Ren account with at least one [pod](/docs/deep-dives/concepts/compute/pods/) and
  [project](/docs/deep-dives/concepts/compute/projects/) - An [agent](/docs/deep-dives/concepts/agents/agents/) version
  deployed to that project
</Prereqs>

## In the UI

<UiWalkthrough>
  {/* TODO(demo): screen recording – navigating to a project and clicking Run to start a session, ~10s loop */}
</UiWalkthrough>

<Steps>

1. Open the project you want to run the agent in.

2. Click **Run** (or the play icon next to the agent version).

3. Type your prompt and press Enter. The session starts in `busy` state and transitions to `idle` when the agent finishes.

4. To continue the conversation, type another message. The session stays open until you archive it.

</Steps>

## Programmatically

Sessions are created against a pod and project. You need the pod ID and project ID. Both are visible in the UI, or list them with `ren pods list` / `ren projects list`.

A session moves through these statuses: `idle` (waiting for input), `busy` (agent is working), `waiting` (agent needs a permission decision), and `error`.

<ClientTabs clients={["claude-code", "codex", "opencode", "hermes", "cli", "api", "typescript"]}>
  <Fragment slot="claude-code">
    Use the `/ren:run` slash command inside a Claude Code session, or paste a prompt that starts with `ren:`:

    ```
    /ren:run my-agent
    ```

    This creates a session on your default pod and project, sends the prompt, and streams the agent's reply back into the Claude Code chat. For non-interactive runs (CI, automation), permissions are auto-allowed. See the [Give your agent access to Ren](/docs/tutorials/give-agent-access-to-ren/).

  </Fragment>
  <Fragment slot="codex">
    Use the `$ren-onboarding` command to start a session, or invoke the Ren MCP tool directly:

    ```
    $ren-onboarding
    ```

    For subsequent runs, the Ren MCP tool `session.create` is available. See [Give your agent access to Ren](/docs/tutorials/give-agent-access-to-ren/) for install instructions.

  </Fragment>
  <Fragment slot="opencode">
    Use the `/ren:run` slash command:

    ```
    /ren:run my-agent
    ```

    This creates a session and sends the prompt. The agent's response streams back into the opencode chat.

  </Fragment>
  <Fragment slot="hermes">
    Use the `/ren-onboarding` command to start a session:

    ```
    /ren-onboarding
    ```

    After onboarding, the Ren MCP tools (`session.create`, `session.list`) are available in the Hermes chat for programmatic session management.

  </Fragment>
  <Fragment slot="cli">
    Create a session on a pod and project:

    ```bash
    ren sessions create \
      --pod-id pod_abc123 \
      --project-id prj_def456 \
      --title "First run"
    ```

    List sessions to find IDs:

    ```bash
    ren sessions list --pod-id pod_abc123
    ```

    Get a session's connection URL (for browser access or driving the session):

    ```bash
    ren sessions url ses_abc123
    ```

  </Fragment>
  <Fragment slot="api">
    Create a session with `POST /api/sessions`:

    ```bash
    curl -X POST https://api.renai.build/api/sessions \
      -H "Authorization: Bearer $REN_PAT_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "podId": "pod_abc123",
        "projectId": "prj_def456",
        "title": "First run"
      }'
    ```

    The response includes the session `id`, `status`, and `slug`. To connect after creation, get the session's connection URL with `GET /api/sessions/{id}/url`.

  </Fragment>
  <Fragment slot="typescript">
    Use the [TypeScript client](/docs/developers/typescript-client/) to create a session:

    ```ts
    import { createRenClient, pat } from "@renai-labs/sdk"

    const client = createRenClient({
      baseUrl: "https://api.renai.build",
      auth: pat(process.env.REN_PAT_TOKEN!),
    })

    const { data: session, error } = await client.session.create({
      body: {
        podId: "pod_abc123",
        projectId: "prj_def456",
        title: "First run",
      },
    })
    if (error) throw error
    console.log(session.id, session.status) // "ses_abc123" "busy"
    ```

    To get the session's connection URL (for connecting a WebSocket or browser):

    ```ts
    const { data: urlData } = await client.session.url({
      path: { id: session.id },
    })
    console.log(urlData.authedUrl) // "https://…"
    ```

  </Fragment>
</ClientTabs>