Session
Understand the bounded connection that carries tool requests and results between an agent and a sandbox.
A session is the active connection between an MCP-capable agent and one Jio sandbox. It gives every tool request a workspace identity, an authorization context, and a defined lifetime.
The sandbox owns the execution environment. The session owns the connection to it. Closing a session does not have to destroy a persistent sandbox, while ending an ephemeral task may close both together.
What a session carries
| Session context | Why it matters |
|---|---|
| Sandbox identity | Ensures tools operate against the intended environment |
| Available capabilities | Tells the agent which reads, writes, and execution tools exist |
| Approval state | Keeps authorization decisions attached to the active connection |
| Activity and time limits | Bounds idle or long-running work |
| Structured results | Returns output, exit status, and policy errors to the agent |
Session lifecycle
Connect
The local bridge selects a sandbox and establishes an authenticated path to the runtime.
Discover
The agent learns which capabilities are available and which policy applies to the session.
Work
Tool requests cross the session boundary and results return to the local agent loop.
Close
Jio releases session-scoped resources and applies the sandbox's retention or destruction policy.
Scope sessions narrowly
Prefer a session tied to one sandbox and one workload over a connection that can silently switch between unrelated environments. A narrow scope makes requests easier to audit and reduces the consequence of selecting the wrong target.
A session is not the sandbox
Sessions are connections; sandboxes are execution environments. Treating them as separate concepts lets a trusted project sandbox outlive one client connection without making every task permanent.