← Engineering blog

An interactive shell has a different lifetime

When an agent gets stuck, opening a shell in its workspace is often the quickest way to see what happened. You may need to answer a prompt, inspect a process, or watch a command run. A short HTTP request won’t cover all of that. Mainbrella offers a browser terminal and SSH into the same machine, with a shell you can reattach to after losing the connection.

Reload the page, reattach to the shell

The browser terminal uses xterm.js over a WebSocket. It authenticates with the browser’s HttpOnly session cookie and a trusted Origin, so an API key alone won’t open that connection. The request includes the selected machine’s creation timestamp and the terminal dimensions.

Behind the connection is a fixed tmux session named main. Closing the terminal panel detaches your client; it doesn’t shut down the shell. Reload the page while that machine is still alive and you can reattach. After an abnormal disconnect, the browser client retries up to five times with exponential backoff. A clean exit stays closed.

That’s useful recovery from a dropped connection, but the machine still has to exist. If polling shows that it stopped or the slot now holds a different instance, the client closes the terminal. Reconnecting must never quietly drop you into a different task, and tmux won’t preserve files after the machine stops.

Use your own terminal over SSH

The dashboard or POST /containers/ssh returns an SSH command for the selected running machine. Access goes through ssh.mainbrella.com using cloudflared on your computer. You don’t need a public IP for the container or a Mainbrella CLI.

That command contains a credential, so paste it into your terminal and keep it out of repositories, shared transcripts, and diagnostic logs. The token lasts at most 15 minutes, or until the machine’s hard deadline if that comes first. Stopping or recreating the machine invalidates it.

A busy terminal still has a deadline

Terminal input and output renew the idle lease. Reading status and requesting an SSH token don’t. Reconnection won’t extend the hard deadline either. Sending a command every few minutes can prevent an idle timeout, but it can’t turn a fixed session into a machine that runs forever.

Each container permits four combined browser and SSH terminal connections, and each account permits ten live SSH tokens. HTTP commands use a separate concurrent-operation pool. If a terminal connection fails because its pool is full, telling the user that the entire account is full sends them debugging the wrong problem. The limits reference lists the separate pools.

Use HTTP execution when you need a bounded foreground command with structured stdout, stderr, and exit status. Use SSH or the browser terminal when you need to interact. Before ending the session, export the files you want to keep or save a workspace.