Skip to main content
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 40 seconds).
  • 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
A stream cannot exist without a connection, but a connection can exist without a stream.

​
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
Open a connection when you are ready to stream. Close the connection when you are done.

​
Summary

ConceptPurpose
ConnectionReserves resources and enables fast stream startup
StreamProduces real-time world model output
Key ruleStreams require a connection; connections do not require a stream
Best practiceAlways close connections when finished

Next: Session Management

Learn how to manage connection lifecycle, cleanup, and reconnection patterns.