Skip to main content
Version: 3.5.x

Sessions

What is a session?​

A session is created automatically when a WebSocket client connects to port 10001. One connection = one session. When the connection closes, the session is destroyed and its configuration is discarded.

Each session has:

  • A numeric ID (auto-assigned by the service)
  • An optional profile name (you set this)
  • Its own view of every device: basis, mount, preset, filters, and workspace transform

Multiple sessions can coexist — e.g., your Unity app on one session and Haply Hub observing on another. They each see the same physical device but with their own coordinate settings.

Setting a profile name​

It's strongly recommended to set a profile name on your first message:

{
  "session": {
    "configure": {
      "profile": {
        "name": "co.mycompany.myapp:main-scene"
      }
    }
  }
}

Why it matters:

  • Haply Hub uses the profile name to recognise your simulation and let you tweak device settings (workspace, basis, mount, filters) from its UI.
  • Those tweaks are persisted — next time you run the same app, Hub automatically re-applies them without any code change on your side.
  • Other sessions (or HTTP clients) can target your session by profile name using a session selector: ?session=myapp:0.

Remote control (cross-session configuration)​

A session's devices can be reconfigured from outside — by another WebSocket session, or by an HTTP client with no WebSocket connection at all. This is how Haply Hub tweaks your app's settings.

The HTTP client uses session selectors to target the right session:

# List all sessions
curl http://localhost:10001/sessions

# Change the basis on session with profile "myapp" (first match)
curl -X POST "http://localhost:10001/inverse3/0/config/basis?session=myapp:0" \
     -H "Content-Type: application/json" \
     -d '{"permutation": "XZY"}'

See the Remote Config tutorial for a full worked example of cross-session HTTP control.

Session lifecycle​

Sessions are ephemeral — they don't survive a service restart. The profile name enables Haply Hub to re-apply settings on the next connection.