---
title: "Sessions"
description: "Create, control, stream, and export Carina sessions."
source: https://carina.nebutra.com/api/sessions/
---

# Sessions

> Create, control, stream, and export Carina sessions.

A session binds conversation state, a **permission profile**, and a **workspace root**. Workspaces are bound at `session.create` via `workspace_root` — there is no separate registration method.

  </div>

## Core methods

| Method | Purpose |
| --- | --- |
| `session.create` | Create session with workspace + profile |
| `session.get` / `session.list` | Metadata and active/archived listing |
| `session.archive` / `session.unarchive` | Reversible archive and restore; active work is rejected |
| `session.pause` / `session.resume` | Suspend / continue |
| `session.close` | Compatibility alias for archive |
| `session.replay` | Replay raw audit event stream |
| `session.items` | Normalized item stream for UI/SDK |
| `session.review` | Governance projection over items |
| `session.events.stream` | Live notifications (`since` cursor, `event_mode`) |

JSONL / SQLite export is provided by `audit.export` (`format: jsonl|sqlite`), not a `session.*` method.

## Task operations

| Method | Purpose |
| --- | --- |
| `execution.start` | Submit a prompt/task into a session |
| `execution.cancel` | Cancel a running task |
| `execution.status` | Query task state |
| `governance.action.approve` / `governance.action.deny` | Resolve pending approval (optional `role`) |

Task events are consumed through `session.events.stream` — there is no separate task event stream.

## Goals

At most one goal per session:

`goal.set` / `get` / `clear` / `pause` / `resume` / `complete` / `continue`

- `goal.continue` is an **explicit, operator-triggered** task submission
- No unattended continuation loop
- Fails closed while a task is in-flight, after continuation limit, or when token budget is exhausted
- Interrupting an active TUI task pauses the goal

TUI: `/goal [--tokens N] OBJECTIVE` plus `clear|pause|resume|complete|continue`.

## Checkpoints

`session.checkpoint.compact` compacts only a **paused** task's persisted latest checkpoint. It never aliases `context.compress`. Compaction is WAL-backed, idempotent on retry, and leaves the source checkpoint available.

TUI: `/compact`.

## SDK sketch

```ts title="client.ts"

const client = await CarinaClient.connect();
const session = await client.sessions.create({
  workspace_root: process.cwd(),
  profile: 'safe-edit',
});

for await (const event of session.events()) {
  console.log(event.type, event.payload);
}
```

  Prefer `safe-edit` for interactive coding. Use `read-only` for review-only agents and sub-agents.

## Source of truth

- Lifecycle notes: `docs/tui-session-lifecycle.md`
- RPC families: `session.*` · `goal.*` · `session.checkpoint.*`
- CLI: `carina sessions` · `carina resume` · `carina items` · `carina session review`
- Related: [JSON-RPC](/api/json-rpc/) · [Method catalog](/api/methods/) · [Audit](/concepts/audit/)

## Next

- [Quickstart](/getting-started/quickstart/) — create a session from the CLI
- [Traces](/observability/traces/) — items, events, cost

---
Source: https://carina.nebutra.com/api/sessions/
Markdown: https://carina.nebutra.com/api/sessions/index.md