1
Tag each sandbox with your user's ID
Keep the API key on your server. Find the user’s sandbox by metadata, resume it if it exists, create it if not:Keys starting with
sandbox_for_user.py
anona. are reserved; pick your own prefix. On plans without a maximum lifetime, timeout=-1 removes the deadline and idle pause alone decides (Lifecycle).2
Show it in your page
Your server mints a short-lived viewer token and your page puts the URL in an iframe. Tokens last up to 10 minutes; the embed asks your page for a fresh one before that. See Embed it. To show a web app the user built, use a preview link instead.
pty gives the user a terminal, desktop a screen:viewer_url.py
3
Keep your own records in step
Subscribe a webhook to
sandbox.lifecycle.paused, resumed and killed, and update your database from it rather than polling. Deliveries are at least once and unordered: deduplicate on webhook-id and order by timestamp.4
Know what each user costs
OpenTelemetry export sends per-sandbox CPU, memory and network to your own backend every minute, tagged with the sandbox ID, so you can bill or limit per user.
examples/python/sandbox_per_user.py in the public SDK repository. It prints what happens at each step.