Skip to main content

Key concepts

Remote Dev Environments share the same building blocks across every client — the CLI, the web UI, the MCP server, and the API. Understanding these concepts helps you move between them.

SessionsClick to copy link​

A session is a single Remote Dev Environment instance: one cloud machine that you connect to and work on. You create a session either from a template or directly by choosing a stack and a machine type.

Each session belongs to the workspace it was created in and is owned either by the user who created it or, for workspace-owned sessions, by the workspace itself. See Can several people share one session? in the FAQ. You can connect to it in several ways — see Connecting to a session.

Session lifecycleClick to copy link​

A session moves through a few states during its life:

  • Running: the machine is provisioned and ready to connect to. When you create or restore a session, it becomes running after a short startup.
  • Terminated: the machine is stopped, but the session and its persistent disk are kept. Terminating is reversible.
  • Deleted: the session is permanently removed. You can only delete a session that's already terminated.

Terminating a session preserves its persistent disk, so when you restore it your files and changes are still there. There is no time limit on how long a terminated session is kept - it stays until you delete it, or until the stack it was created from is removed from Bitrise.

A session's disk stores only the changes you have made on top of the stack image it was created from, so the session can only be started while that stack image is still available. Stacks are removed on a published schedule, with at least four weeks' notice - see Stack deprecation and removal policy. When a stack is removed, sessions created from it are permanently erased and cannot be restored. Create a new session from a current stack, and commit or export anything you want to keep, before then.

To avoid leaving machines running, every session has an auto-terminate timer:

  • The default is 5 days of inactivity.
  • You can set it to anything up to 30 days, or turn it off so the session never auto-terminates.
  • Sessions in free-trial workspaces are capped at 8 hours and can't change this.

Stacks and machine typesClick to copy link​

When you create a session you choose two things:

  • A stack: the operating system image and the tools preinstalled on it, such as a specific Xcode version on macOS. These are the same stacks used by Bitrise CI.
  • A machine type: the size of the machine, defined by its CPU and RAM. macOS uses Apple silicon machine types; Linux machine types range from small shared instances to large dedicated ones.

A template can set these for you, or you can pick them directly when creating a session. The available stacks and machine types depend on your workspace.

Your session stays tied to the stack you choose. The stack isn't only a starting point - a session keeps a permanent dependency on the stack image it was created from. Your session's disk stores only the changes you make on top of that image, so the session can be started only while that image is still available on Bitrise. You cannot move an existing session to a different stack; to move to a newer stack, create a new session from it. Because stacks are eventually removed on a published schedule, this also determines how long a session can be kept - see Session lifecycle.

Virtual devicesClick to copy link​

A session can also boot an iOS simulator or Android emulator, making it a device session, and a device preview link opens an app build on such a device for anyone who has the link. See Virtual devices.

TemplatesClick to copy link​

A template is a reusable session configuration. Instead of choosing a stack, machine type, and setup steps every time, you define them once in a template and create sessions from it. A template can include:

  • A stack, a machine type, and a working directory.
  • A warmup script that runs once when the session is first created, and a startup script that runs on every start.
  • Template variables and session inputs: values the session needs, which can be exposed as environment variables and marked as secret.
  • Workspace links: shortcut buttons that open a specific folder in your IDE.

For details, see Templates.

Warm poolsClick to copy link​

A warm pool keeps a number of sessions of one configuration booted and idle, so creating a session from it takes seconds: the session is claimed from the pool instead of booting a fresh machine, and the pool boots a replacement. A pool stores a template with its inputs and overrides, belongs to you or to the workspace, and has a pool size you can change at any time, including on a schedule.

For details, see Warm pools.

Saved inputsClick to copy link​

A saved input is a reusable value or credential — such as an SSH public key, an API token, or a Claude Code credential — that you store once and map into sessions as needed. Saved inputs are scoped to your user account, not to a single workspace, and secret values are encrypted at rest.

For details, see Saved inputs.

See also