Stop and resume

A session does not have to run until its work is done. Stop it and pick it up later: the whole browser goes with it, with tabs and their history, logins and every site’s storage. See What a session keeps. If a machine is lost, the platform starts the session again on a new one from its last checkpoint: see Checkpoints and a lost machine.

Stop

POST/v1/sessions/:id/stop

Stopping saves the session exactly as it is, frees the machine and stops billing. It returns the session with status STOPPED, with stoppedAt, stopReason and deletesAt. Use it when your agent is done for now, or waits on something slow, such as a human approval, and you do not want to pay for an idle machine.

curl -X POST https://api.boxline.dev/v1/sessions/$SESSION_ID/stop \  -H "x-api-key: $BOXLINE_API_KEY"

What a stop keeps:

• The browser: open tabs with their history, cookies, every site’s storage and form values. See What a session keeps.
• Files: the contents of /workspace, including browser downloads, for every session.
• Proxy: the session’s proxy, set on the new machine before any page reopens. A sticky IP stays the same while the provider still has it. Resuming a session with one of the platform’s proxies needs proxy data left for the month (otherwise 402 spend_limit).
• Browser settings: the page size (viewport) and the browser mode (clock and language).
• Shell: each persistent shell’s directory and exported variables, stored encrypted (a variable whose value holds a credential’s value is not stored: export it again), and the session’s env and credentials, set again on resume. See With a shell.
• Its record: the recording, the logs, the pages and the steps of agent runs in it stay while the session is stopped.

With a shell

A session’s shell is saved too, but not its running processes:

• Each persistent shell continues in the same directory, with the variables it exported. The session’s env and exported credentials are set again on the new machine.
• Running commands, servers and background jobs stop. A lifecycle event lists them (“processes stopped by the stop”).
• Only /workspace is kept on disk, so setup commands run again first.

The full list of what is kept is on the Shell page: What a stop and resume keeps.

A stop carries the browser up to 1 GB compressed (3 GB unpacked). A bigger one is not saved whole: the session keeps what its open tabs held, and a lifecycle warning says so. See When the browser cannot be saved whole. If the state cannot be saved at all, the stop call fails and the session keeps running: stop it again.

A stopped session is free: no running time, no charge for what it kept. It does not count towards your concurrent sessions. It is kept for your plan’s retention days (Free 7, Hobby 30, Startup 30, Scale 90), counted from the stop, then deleted. Its deletesAt says when. See How long a stopped session is kept.

The platform also stops a session for you when its time runs out, it goes idle, its last client leaves, an agent run finishes with it, or a limit is reached. Those stops save the session the same way. See Why a session stopped.

Resume

POST/v1/sessions/:id/resume

Resuming brings a stopped session back on a fresh machine, with the same id and everything as it was when it stopped. It returns the session with status RUNNING and restarts per-second billing. The session gets a full timeout again from the moment it resumes, and fresh connectUrl, liveUrl and terminalUrl: a stop rotates the session’s URLs, so the ones you held before it stay refused. Resuming counts toward your plan’s concurrent sessions (shared by all the projects of your organization) and toward the project’s own cap, if it has one.

curl -X POST https://api.boxline.dev/v1/sessions/$SESSION_ID/resume \  -H "x-api-key: $BOXLINE_API_KEY"

A call on a stopped session does not resume it. Connecting, browser actions, commands, writing files and the live view answer 409 session_not_running: call resume first. Reading its files is the exception, see Files of a stopped session. An agent run given a stopped sessionId resumes it itself.

In the SDKs, nothing_saved is a NothingSavedError. See the Lifecycle page for an example.

What a session keeps

A stop and resume, and a recovery from a checkpoint, both keep the whole browser, not only its cookies. After either, your agent is still signed in and the tabs are where it left them.

Not kept: the browser’s caches (HTTP cache, compiled code, GPU caches), so pages load from the network again. Pages also reload: a page’s scripts and their memory start again. Running processes (commands, servers, background jobs) stop and are not started again. Form history, autofill and saved passwords are off in the browser, so a saved copy never holds them.

Sites that keep a sign-in in IndexedDB, or in the storage of a tab you already closed, stay signed in. The files in /workspace and the shell are kept as well: see the Shell page, What a stop and resume keeps. This is separate from a browser profile: a profile is a login you save on purpose, to start new sessions with.

• A stop stores the browser with the session’s other saved state. The platform seals it (AES-256-GCM), on top of the store’s own encryption. A resume deletes the stored copy: the next stop makes a new one.
• A checkpoint copies it while the browser keeps running, so a recovery can miss the last few seconds of changes. See Checkpoints and a lost machine.

When the browser cannot be saved whole

The session still goes on. It comes back with what its open tabs held: each tab’s address, its cookies, the localStorage and sessionStorage of the tab’s own site, form values and scroll position. This happens when:

• the browser’s data is over 1 GB compressed or 3 GB unpacked for a stop (256 MB compressed for a checkpoint);
• the session runs on a machine from an older version;
• copying the browser failed.

The session’s log then gets a lifecycle event with level warn. Its data says why and when:

A checkpoint gives this warning once per session and reason, not at every checkpoint.

How the browser came back

The lifecycle events resumed and recovered… have data.browserProfile, and so has moved, which the platform logs when it moves a session to another machine itself:

The stopped event has data.browserProfile as true or false, data.reason (the stopReason) and data.saved: "state", "checkpoint" (the state could not be taken, so the last checkpoint was kept) or "nothing". resumed, recovered… and moved also have profileMs: how long the browser copy took.

While an agent run with secret values works

A stop or a checkpoint taken while an agent run with secret variables works in the session stores the browser without its history, the tabs to restore, autofill and saved passwords. Tabs reopen at their addresses, without query strings, so a value that a page put into an address is not stored. When the platform moves the session to another machine itself, it copies the browser across and carries it whole.

Stops and checkpoints taken after the run carry the history again, so an address that a page put a value into stays in it. See Hidden everywhere.

Checkpoints and a lost machine

About every 5 minutes the platform saves every running session’s whole browser and its workspace. This is a checkpoint; checkpointAt shows the last one.

If a machine is lost (a crash, or a lost server), the platform starts the session again on a new one from its last checkpoint. You do nothing: the session keeps its id and its URLs, and recoveries counts how often it happened. Work done after that checkpoint is lost, and running processes start again.

If no machine can be had to start it on, the session stops with stopReason: "machine_lost" and keeps its last checkpoint as what it saved. A resume brings it back from there, or answers 409 nothing_saved when it had no checkpoint yet. See Checkpoints and recovery.

Stop, delete or keep running?

• Keep running while the agent is actively working.
• Stop when you will need this exact session again, with its tabs and files, or when you are simply done: it is free, and it goes away by itself after your plan’s retention days.
• Delete when you will not need it again and want its saved browser, files, recording and logs gone now. This cannot be undone. If you only need the login next time, a browser profile is lighter than a stopped session.