Timeouts
Timeouts determine when a session will be automatically terminated. They can be used to prevent excessive usage, terminate inactive sessions, add paywalls, and more.
Want to jump into the code? See our timeout example.
Types of Timeouts
There are three types of timeouts:
- Absolute timeout
- Offline timeout
- Inactive timeout
🛑 Absolute Timeout
The absolute timeout is the amount of time (in seconds) after session creation before the virtual browser is automatically terminated. It is primarily used to enforce hard limits on session time.
💤 Offline Timeout
The offline timeout is the amount of time (in seconds) that no users have been connected, after which the virtual browser is automatically terminated. It is used to terminate sessions where all users have disconnected.
👻 Inactive Timeout
The inactive timeout is the amount of time (in seconds) since the last user input, after which the virtual browser is automatically terminated. It is used to terminate sessions where users remain connected but are not necessarily using the virtual browser.
You can programmatically reset the inactive timeout using
hb.ping()
.
Default Values
Timeout | Default Value (in seconds) |
---|---|
Offline | 3600 |
Inactive | null |
Absolute | null |
⚠️ Warning Value
You can provide a callback, onCloseWarning
,
which can be used used to notify the user of an upcoming timeout.
const hb = await Hyperbeam(hbContainer, computer.embed_url, {
onCloseWarning(e) {
if (e.deadline) {
showCloseWarning(e.type, e.deadline.delay);
} else {
hideCloseWarning(e.type);
}
}
});
The warning value is the amount of time (in seconds) between
onCloseWarning
being called and the session being terminated.
Its default value is 60
.
How to Set Timeout Values
You can set timeout values during session creation by setting the timeout
object parameter.
curl --request POST \
--url https://engine.hyperbeam.com/v0/vm \
--header 'Authorization: Bearer AUTH_VALUE' \
--header 'Content-Type: application/json' \
--data '{
"timeout": {
"absolute": 1000,
"inactive": 100,
"offline": 3600,
"warning": 60,
"webhook": {
"url": "<webhook url>",
"bearer": "<webhook auth>""
}
},
}'
Webhooks
The Hyperbeam timeout system allows you to send webhook events when a timeout is triggered. To use webhooks, add the webhook.url
and webhook.bearer
parameters to the request when starting a session (see example above).
Updating Timeouts for Active Sessions
You can update timeouts for active sessions by hitting the <base_url>/timeout
endpoint, and passing in new timeout values.
When you update the timeouts, the timeout counters are reset e.g. absolute
timeout will calculate the amount of time from the timeout update (instead of
session creation) before the session is terminated. To prevent the timeout
counters from being reset, you must set the reset
parameter to false
(see
example request).
Example Request
curl --request POST \
--url <base_url>/timeout \
--header 'Authorization: Bearer AUTH_VALUE' \
--header 'Content-Type: application/json' \
--data '{
"absolute": 1000,
"inactive": 100,
"offline": 3600,
"warning": 60,
"reset": false
}'
Looking for more detailed examples? See our timeout example.