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

# Session sidecar

A sidecar runs your Node.js or Python program inside the session's virtual machine. Upload a single file or a gzip tar archive with an entry file. The process runs for the session's lifetime.

The browser's CDP address is available in `TILION_CDP_URL`. The program must listen for HTTP on the port specified by `PORT`. The passthrough endpoint provides external access because the sidecar has no independent network access.

Sidecars must be enabled for the account. Otherwise, these routes return `403 sidecar_not_enabled`.

## PUT /v1/session/\{session\_id}/sidecar

Upload and start the session's sidecar.

Auth: Bearer API key (`sessions:write`).

Request:

| Field | Type | Default | Meaning |
| - | - | - | - |
| `runtime` | string | required | `node` or `python` |
| `entry` | string | required | the file to run, 1 to 200 characters |
| `bundle_b64` | string | required | base64 of the source file or of a gzip tarball containing `entry`; up to 3,000,000 characters (about 2.2 MB) |

Response: `{"session_id": "...", "state": "..."}`.

Errors: 403 `sidecar_not_enabled`; 404 or 410 for a session that is not yours or has ended; 409 `sidecar_unavailable` (`this session has no sidecar slot (create a new session)`); 422 `bundle_b64 is not base64`, 422 `sidecar_start_failed` with the runner's message, or a 422 validation list for a bad `runtime` or `entry`.

## GET /v1/session/\{session\_id}/sidecar

The sidecar's state. Add `?log=true` for its output so far in `log`.

Auth: Bearer API key.

On a session with no sidecar:

```json theme={"dark"}
{"session_id": "sess_3d245e1dc50046628f3573aa7d79f8dc", "state": "idle", "error": null}
```

| Field | Meaning |
| - | - |
| `state` | `idle` until you start one; after a start, the runner's state for your program |
| `error` | the runner's error text when the program failed, else null |
| `log` | with `?log=true`, the program's output so far |

Errors: 403 `sidecar_not_enabled`; 409 `sidecar_unavailable`; 404 or 410 for the session.

## DELETE /v1/session/\{session\_id}/sidecar

Stop the sidecar. The session keeps running. Answers `204 No Content`.

Errors: 403, 409, 404 or 410 as above.

## GET, POST, PUT, PATCH, DELETE /v1/session/\{session\_id}/sidecar/http/\{path}

Call your sidecar's own HTTP API. The path after `/http/`, the query string, the body and the `Content-Type` and `Accept` headers pass through; the sidecar's status, body and content type come back as it wrote them. A call may run for up to 300 seconds.

Auth: Bearer API key with `sessions:write`, for every method including GET.

With no sidecar running:

```json theme={"dark"}
{"detail": {"error": "sidecar_unreachable", "message": "the sidecar is not answering on its PORT"}}
```

Errors: 502 `sidecar_unreachable` when nothing is listening on the port (not started, crashed, or still starting); 403 `sidecar_not_enabled`; 409 `sidecar_unavailable`; 404 or 410 for the session.


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