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

# Connection vs. Stream

When working with Odyssey, it’s important to understand how connections and streams relate to each other. They are separate concepts, and managing them correctly affects performance.

These two concepts are related but **not the same thing**.

## **What is a Connection?**

A **connection** represents an active session between your application and Odyssey.

When you open a connection:

* Odyssey **reserves resources** (including a GPU-backed streamer)
* The connection remains active until you explicitly close it, or until it times out due to inactivity (currently after 15 minutes)
* No visual output is produced by default

A connection can exist **with or without an active stream**.

Think of a connection like an open socket. Data may or may not be flowing, but the socket remains open, and resources remain allocated until it’s closed.

## **What is a Stream?**

A **stream** is the actual, real-time output generated by the world model.

Streams:

* They are created **within an existing connection**
* Can be started and stopped multiple times
* Produce real-time video frames
* Do not require reconnecting each time

<Note>
  A stream **cannot exist without a connection**, but a connection **can exist without a stream**.
</Note>

## **Why are these separate by design?**

This separation is intentional. Keeping a connection open allows Odyssey to reserve resources and for you to start streams quickly, without waiting for connection setup each time. 

The design is optimized for:

* interactive workflows
* live control loops
* rapid iteration during development
* real-time production environments

## **Common pitfall: Leaving connections open**

Because connections reserve resources, leaving them open when no streams are active can lead to **idle time**.

Be mindful to avoid the following patterns:

* Opening connections without ever starting a stream
* Leaving connections open after streaming has finished
* Unintentionally creating multiple connections, such as inside a loop or hot-reload workflow

These issues typically occur when connections aren’t explicitly closed, when the connection lifecycle isn’t tied to the application lifecycle, or when development tools restart code without proper cleanup.

## **Best practices**

Recommended patterns:

* Open one connection per session or user
* Reuse the same connection for multiple streams
* Explicitly close the connection when streaming is complete
* Avoid opening connections inside tight loops or auto-reloading code paths

<Tip>
  **Open a connection when you are ready to stream. Close the connection when you are done.**
</Tip>

## **Summary**

| **Concept**   | **Purpose**                                                       |
| :------------ | :---------------------------------------------------------------- |
| Connection    | Reserves resources and enables fast stream startup                |
| Stream        | Produces real-time world model output                             |
| Key rule      | Streams require a connection; connections do not require a stream |
| Best practice | Always close connections when finished                            |

<Card title="Next: Session Management" icon="sparkles" href="/session-management">
  Learn how to manage connection lifecycle, cleanup, and reconnection patterns.
</Card>