Run an agent

Start an agent run by creating a session 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.

Before you start

• A Ren account with at least one pod and project - An agent version deployed to that project

In the UI

In the UI

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.

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.

Claude Code Codex opencode Hermes CLI API TypeScript

Select client Claude CodeCodexopencodeHermesCLIAPITypeScript

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.

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 for install instructions.

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.

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.

Create a session on a pod and project:

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

List sessions to find IDs:

ren sessions list --pod-id pod_abc123

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

ren sessions url ses_abc123

Create a session with POST /api/sessions:

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.

Use the TypeScript client to create a session:

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

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