Sessions

Documentation Index

Fetch the complete documentation index at: https://docs.mistle.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

Sessions are interactive agent workspaces started from a sandbox profile. Use sessions for work such as:

• debugging failing tests
• reviewing code changes
• implementing repository changes
• investigating logs or provider state through integrations
• preparing pull requests

Each session runs in a sandbox environment with the tools, setup, and integration access defined by the selected sandbox profile and organization configuration.

​

How Sessions Start

When a user starts a session, Mistle selects the requested sandbox profile version and creates a sandbox for the agent. If the profile version has a usable snapshot, the sandbox can start from that prepared image. This avoids repeating setup work that was already captured by the profile snapshot. When a repository is selected at session start, Mistle uses it as the agent’s startup working directory. That working directory determines which repo-local instructions and skills the agent sees when the session begins.

​

Start A Session

To start interactive agent work:

1. Open Sessions.
2. Create a new session.
3. Choose the sandbox profile for the work.
4. Choose the repository or workspace where the agent should start.
5. Describe the task for the agent.
6. Start the session.

If the profile is not available for new sessions, check that the profile has a published version and a ready snapshot.

​

Use A Session

After a session starts, the session workbench becomes the main place where you collaborate with the agent, inspect the sandbox, and review changes before the work leaves Mistle. The header controls expose the active sandbox and repository state:

​

Choose The Primary Repository

Profiles can expose one or more repositories or workspaces. Use the Primary repository selector to choose the working directory for the current turn. The primary repository sets where new agent threads, the Codex TUI, terminals, repository status checks, and code diffs run. Set it to the repository where the agent should do the work. This matters because repo-local instructions and skills are discovered from the working directory. Choosing the wrong repository can start the agent without the project-specific guidance it needs. If a session does not have a repository, repository-dependent controls show an unavailable state instead of guessing which directory to use.

​

Chat And TUI

The default session view is chat. Use it for normal agent instructions, follow-up questions, file attachments, approvals, and review comments. Use TUI when you want to work directly in the agent’s native terminal interface. The TUI replaces the chat pane while it is open, and you can return to chat from the same header control.

​

Review Code Changes

Open Changes to review the current repository diff without leaving the session. The changes panel compares the selected repository with its default branch, shows tracked and untracked file changes, and keeps the review beside the conversation. Use this when you want to inspect the agent’s work before asking for revisions, approving a file change, or preparing a pull request. You can leave line-level comments on the diff. Pending diff comments are attached to the composer so the next message can refer to exact files and lines.

​

Run Terminal Commands

Open Terminal to run shell commands in the session sandbox. The terminal opens as a resizable bottom workspace and can contain multiple terminal tabs. Use the terminal for direct checks such as package-manager commands, local scripts, repository inspection, or quick probes that do not need to go through the agent.

​

Open Running Ports

When a process inside the sandbox listens on loopback, open Processes to expose the HTTP port in a new browser tab. This is useful for previewing development servers, docs sites, Storybook, API explorers, or other local web tools started by the agent or by a terminal command. Ports are available only while the sandbox is running and Mistle can connect to the session.

​

Agent Access

Agents can use configured integrations to interact with external systems. Credentials are managed by Mistle and are not placed directly inside the sandbox as long-lived secrets. The exact tools and provider access available in a session come from the profile, organization settings, and connected integrations.

​

External Activity Links

When an agent writes back to supported external systems, Mistle adds a link back to the session where the work happened. For example, Slack messages, GitHub comments or pull requests, Jira issues or comments, and Linear issues or comments can include a View session link. That link lets teammates open the Mistle session behind the external update and inspect the work context.

​

Persistence

Sessions are workspaces for ongoing agent work. By default, session sandboxes are ephemeral. Use Snapshots when a workflow needs a reusable prepared environment for many future sessions. Use Persistent Sandboxes when a specific session’s working state should survive compute stops, resumes, or provider expiry. Persistent sandboxes are experimental and require both organization-level enablement and profile-level opt-in.

​

Next Steps

• Read Sandbox Profiles to configure the environment sessions start from.
• Read Persistent Sandboxes when session workspace state needs to survive compute lifecycle changes.
• Read Integrations to connect external systems.
• Read Automations for event-triggered agent sessions.