Launch a Session
A session is the live runner for a workspace. It gives you a terminal-first environment backed by a configured container image and Cloud Run service.
Choose an Image
Session image choices are configured by the app. Pick the smallest image that contains the language runtime and tools the project needs. Heavier images are useful for agent stacks with preinstalled CLIs, but they take longer to build and maintain.
| Image | Terminal or agent mode | Preview support | Function or tool support | Recommended use case |
|---|---|---|---|---|
pi-basic | Pi agent terminal | No browser preview | Standard terminal tools, no function runner | Agent-led terminal work that does not need a web preview. |
pi-web | Pi agent terminal | Browser preview and preview QA | Web preview plus function-capable tooling | Agent-led web app work where you need to inspect and test the running UI. |
codex-basic | Codex terminal | No browser preview | Standard terminal tools, no function runner | Code changes and command-line verification without a browser-served app. |
codex-web | Codex terminal | Browser preview and preview QA | Web preview plus function-capable tooling | Codex-driven frontend or full-stack work that needs a live browser preview. |
Choose a *-basic image when terminal access is enough. Choose a *-web image
when the project needs an in-browser preview, preview QA, or function-capable
tooling.
Start the Runner
- Select a workspace.
- Choose New Session.
- Select the runtime image.
- Launch the session.
- Wait for the terminal to attach.
The terminal, file tree, and agent commands operate inside the workspace boundary. If the runner image changes, launch a new session so Cloud Run gets a fresh revision.
Stop Idle Work
Stop sessions when active work is finished. Mapache is designed around serverless runners, so keeping idle containers around is unnecessary cost.