> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bonya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# session

> Managed session operations on a sandbox — create, list, attach, kill

## `bonya session`

> [!NOTE]
>
> Aliases: `sess`, `s`

Managed sessions are named terminals that keep running after you disconnect, and survive the sandbox suspending and resuming. Reattaching replays what the session produced while nobody was watching.

For the common case — "give me a shell" — use [`bonya console`](https://docs.bonya.ai/cli-reference/console) instead, which is a shortcut for attaching to a session named `console`. Use `bonya session` directly when you want a named, scriptable session (a dev server, a long build) that isn't the interactive console.

## `create`

Creates a named managed session running a given command.

```shell theme={null}
bonya session create [sandbox] <name> -- cmd [args...]
```

| Flag | Default | Description |
| - | - | - |
| `--cols` | server default | TTY columns. |
| `--rows` | server default | TTY rows. |
| `--by-name` | `false` | Treat the sandbox argument as a name even if it looks like an id. |

```shell theme={null}
bonya session create web dev -- npm run dev
```

## `list`

Lists a sandbox's managed sessions.

```shell theme={null}
bonya session list [sandbox]
```

```shell theme={null}
bonya session list web
```

If the sandbox is currently suspended, the listing is served from a suspend-time snapshot and the output notes that explicitly.

On a real terminal, `bonya session list` looks like this:

## `attach`

Connects to a running managed session.

```shell theme={null}
bonya session attach [sandbox] <name>
```

| Flag | Default | Description |
| - | - | - |
| `--cols` | your terminal | TTY columns to apply at attach time. |
| `--rows` | your terminal | TTY rows to apply at attach time. |
| `--by-name` | `false` | Treat the sandbox argument as a name even if it looks like an id. |

From a terminal, `attach` is fully interactive: stdin is forwarded and window resizes propagate. Piped or redirected, it streams the session's output read-only:

```shell theme={null}
bonya session attach web dev | tee log
```

> [!WARNING]
>
> Attaching **preempts** any other client already attached to that session — only one live attachment exists at a time. Detaching (Ctrl+D, closing the terminal) leaves the session itself running.

## `kill`

Kills a managed session.

```shell theme={null}
bonya session kill [sandbox] <name> [--signal TERM] [--grace-ms 5000]
```

| Flag | Default | Description |
| - | - | - |
| `--signal` | `TERM` | Signal to send. |
| `--grace-ms` | `5000` | Milliseconds to wait after the signal before sending `SIGKILL`. |
| `--by-name` | `false` | Treat the sandbox argument as a name even if it looks like an id. |

```shell Graceful kill (default) theme={null}
bonya session kill web dev
```

```shell Force kill immediately theme={null}
bonya session kill web dev --signal KILL
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.