Dormice అంటే ఏమిటి? Self-hosted agent sandboxes గైడ్

Dormice అంటే ఏమిటి, మరియు ఏమి కాదు

Dormice అనేది ఒక self-hosted agent sandbox: ఇది మీరు సొంతంగా కలిగి ఉన్న Linux VPS పై నడిచే ఒక daemon. మీ agent code, నమ్మదగని (untrusted) కోడ్‌ను ఒక isolated container లో రన్ చేయడానికి HTTP ద్వారా దీనిని పిలుస్తుంది. మీ ప్రోగ్రామ్ ఒక sandbox ను పేరుతో అడుగుతుంది, అది ఏ స్థితిలో ఉన్నా అదే sandbox ను తిరిగి పొందుతుంది, అందులో ఒక command ను రన్ చేస్తుంది, మరియు output ను చదువుతుంది. ఈ sandbox ఒక programmatic resource, మీరు లాగిన్ అయ్యే machine కాదు.

ఒక agent కు పూర్తి కంప్యూటర్‌ను ఇవ్వడం కంటే ఇది భిన్నమైన పద్ధతి. ఒక coding agent కోసం throwaway VM అనేది మీరు SSH ద్వారా లాగిన్ అయ్యే ఒక బాక్స్, దీనిని agent పాడు చేసిన తర్వాత మీరు తొలగిస్తారు. Dormice ఒక స్థాయి కింద ఉంటుంది: మీ ప్రోగ్రామ్ వద్ద ఇప్పటికే కోడ్ ఉన్నప్పుడు మరియు దానిని రన్ చేయడానికి సురక్షితమైన చోటు అవసరమైనప్పుడు పిలిచే execution API ఇది. పని యొక్క యూనిట్ ఒక పూర్తి machine అయినప్పుడు throwaway VM ని ఉపయోగించండి. పని యొక్క యూనిట్ ఒకే ఒక exec call అయినప్పుడు మరియు వందల సంఖ్యలో VMs లేకుండా రోజుకు వంద సార్లు రన్ చేయాలనుకున్నప్పుడు Dormice ని ఉపయోగించండి.

ఈ ప్రాజెక్ట్ తనను తాను E2B compatible అని పిలుచుకుంటుంది. E2B అనేది ఒక hosted sandbox service, దీని client library ని ఇప్పటికే అనేక agent frameworks ఉపయోగిస్తున్నాయి. Dormice అదే protocol ను తన సొంత URL prefixes కింద అందిస్తుంది, కాబట్టి అధికారిక e2b package కోసం రాసిన అప్లికేషన్, మీరు దానిని మీ సొంత బాక్స్‌కు పాయింట్ చేసినప్పుడు కూడా పనిచేస్తుంది. అప్లికేషన్ కోడ్‌లో ఎటువంటి మార్పు ఉండదు. కేవలం రెండు URLs మరియు ఒక API key prefix మాత్రమే మారుతాయి.

"ఏజెంట్ శాండ్‌బాక్స్‌ల SQLite" అంటే ఆచరణలో ఏమిటి

SQLite అనేది మీరు ఆపరేట్ చేసే సర్వీస్ కాదు, మీరు ఎంబెడ్ చేసే డేటాబేస్. Dormice ఈ పోలికను నేరుగా తీసుకుంటుంది. ఒకే డెమోన్, లెడ్జర్ కోసం ఒకే SQLite ఫైల్, ఒకే TCP పోర్ట్. Kubernetes లేదు, ప్రత్యేక డేటాబేస్ లేదు, షెడ్యూలర్ లేదు. ఈ డెమోన్ తన లెడ్జర్ పక్కనే ఒక లాక్‌ను తీసుకుంటుంది; లెడ్జర్ మరియు అది ఉన్న మెషీన్ ఒకదానికొకటి సరిపోకపోతే, అది ప్రారంభం కావడానికి నిరాకరిస్తుంది. కాబట్టి, split brain సమస్య నిశ్శబ్దంగా జరగదు. ఒకే మెషీన్ అనేది దీని డిజైన్. మీకు అనేక హోస్ట్‌లలో ఫ్లీట్ అవసరమైతే, వేరే దేనినైనా ఎంచుకోమని README స్పష్టంగా చెబుతుంది, మీరు దానిని పాటించాలి.

ఈ ఆలోచనలో రెండో భాగం ఖర్చు గురించి. హోస్ట్ చేసిన శాండ్‌బాక్స్ అది ఉన్న ప్రతి సెకనుకు బిల్లు వేస్తుంది, కాబట్టి హోస్ట్ చేసిన శాండ్‌బాక్స్‌లు డిజైన్ పరంగానే డిస్పోజబుల్ (వాడి పారేసేవి). Dormice మీరు ఇప్పటికే డబ్బు చెల్లిస్తున్న హార్డ్‌వేర్‌పై నడుస్తుంది, కాబట్టి దీని శాండ్‌బాక్స్‌లు శాశ్వతమైనవి మరియు అవి ఎంత ఎక్కువ కాలం ఉంటే అంత చౌకగా మారుతాయి. ఒక శాండ్‌బాక్స్ ఒక్కో మెట్టుగా కూల్ డౌన్ అవుతుంది: active, ఆపై frozen, ఆపై stopped, చివరగా archived. ఏదైనా acquire అభ్యర్థన అది ఏ మెట్టుకు చేరుకున్నా సరే, దానిని తిరిగి పైకి తీసుకువస్తుంది.

ఫ్రీజింగ్ (freezing) అనేది అర్థం చేసుకోవలసిన ముఖ్యమైన భాగం, ఎందుకంటే ప్రతి ఏజెంట్ శాండ్‌బాక్స్‌ను శాశ్వతంగా ఉంచుకోవడాన్ని ఇది సరసమైనదిగా చేస్తుంది. ఇవి ప్రాజెక్ట్ స్వయంగా ప్రచురించిన గణాంకాలు, ఇవి మీ హార్డ్‌వేర్‌పై కాకుండా, వారి హార్డ్‌వేర్‌పై కొలవబడినవి.

[
  {
    "label": "Active, holding 1 GiB",
    "resident_memory_mib": 1024,
    "wake_ms": 0
  },
  {
    "label": "Frozen",
    "resident_memory_mib": 5,
    "wake_ms": 50
  }
]

1024 MiB మెమరీని కలిగి ఉన్న ఒక ఐడిల్ శాండ్‌బాక్స్, ఫ్రీజ్ అయిన తర్వాత 5 MiB రెసిడెంట్ మెమరీకి పడిపోతుంది, మరియు సుమారు 50 ms లలో తిరిగి వస్తుంది. ప్రాసెస్‌లు ఉన్నచోటే సస్పెండ్ మరియు రిజ్యూమ్ అవుతాయి, కాబట్టి ఎక్కువ కాలం ఉండే ఏజెంట్ తన షెల్ స్టేట్‌ను మరియు సగం పూర్తయిన పనిని ఫ్రీజ్ అంతటా అలాగే ఉంచుకుంటుంది. దీనిని బట్టి మీరు కెపాసిటీ ప్లాన్ చేసుకునే ముందు మీ స్వంత హోస్ట్‌పై దీనిని పరీక్షించండి.

ఇన్‌స్టాలేషన్‌కు ముందు హోస్ట్ అవసరాలు

హోస్ట్ తప్పనిసరిగా x86_64 ఆర్కిటెక్చర్‌పై Ubuntu లేదా Debian అయి ఉండాలి మరియు ఇన్‌స్టాలర్‌కు root అనుమతులు అవసరం. ఈ daemon లూప్ మౌంట్‌లను నిర్వహించడం మరియు cgroups లోకి రాయడం వంటి పనుల కోసం రన్‌టైమ్‌లో root అనుమతులను కలిగి ఉంటుంది.

శాండ్‌బాక్స్‌లు gVisor (కంటైనర్ మరియు హోస్ట్ కెర్నల్ మధ్య యూజర్‌స్పేస్ కెర్నల్‌ను ఉంచే కంటైనర్ రన్‌టైమ్) తో Docker లో నడుస్తాయి. ఇది ప్రతి శాండ్‌బాక్స్ ఉపయోగించే runsc రన్‌టైమ్‌ను అందిస్తుంది. ఈ daemon ను నడపడానికి Node 22 లేదా అంతకంటే కొత్త వెర్షన్ అవసరం. ఇన్‌స్టాలర్ తన సొంత Node కాపీని కలిగి ఉంటుంది, కాబట్టి మీ సిస్టమ్‌లోని Node వెర్షన్‌తో ఎటువంటి సంబంధం ఉండదు.

సిస్టమ్‌లో Swap తప్పనిసరిగా ఉండాలి మరియు vm.swappiness విలువ 100 ఉండాలి. ఇది కేవలం పనితీరును మెరుగుపరిచే సలహా కాదు, ఇది ఒక క్రియాత్మక అవసరం (functional requirement). ఖాళీగా ఉన్న శాండ్‌బాక్స్ మెమరీని swap లోకి పంపడం ద్వారా ఫ్రీజింగ్ ప్రక్రియ జరుగుతుంది. gVisor శాండ్‌బాక్స్ మెమరీని షేర్డ్ మెమరీగా ఉంచుతుంది, డిఫాల్ట్ swappiness విలువ వద్ద కెర్నల్ షేర్డ్ మెమరీని swap చేయదు. డిఫాల్ట్ విలువ వద్ద 0 బైట్ల మెమరీ మాత్రమే విడుదలవుతుందని, అదే 100 వద్ద 99.5 శాతం మెమరీ విడుదలవుతుందని ప్రాజెక్ట్ పరీక్షల్లో తేలింది. కెర్నల్ ప్రస్తుతం ఉపయోగిస్తున్న విలువను తనిఖీ చేయండి, ఎందుకంటే కొన్ని క్లౌడ్ ఇమేజ్‌లు మీరు ఎప్పటికీ చూడని ఫైల్‌లో vm.swappiness = 0 సెట్టింగ్‌ను కలిగి ఉంటాయి.

sysctl vm.swappiness
swapon --show

sysctl vm.swappiness కమాండ్ vm.swappiness = 100 అని చూపాలి మరియు swapon --show కమాండ్ ఒక swapfile ను జాబితా చేయాలి. ఒకవేళ swappiness విలువ 0 అని చూపిస్తే, ప్రతి ఫ్రీజ్ ప్రక్రియ విఫలమవుతుంది మరియు ఖాళీగా ఉన్న ప్రతి శాండ్‌బాక్స్ కోసం మీరు పూర్తి మెమరీ ఖర్చును భరించాల్సి వస్తుంది.

Ubuntu పై Dormice ను ఇన్‌స్టాల్ చేయడం

డాక్యుమెంట్ చేయబడిన ఇన్‌స్టాలేషన్ ప్రక్రియ bash లోకి ఒక పైప్ (pipe) ద్వారా జరుగుతుంది:

curl -fsSL https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/install.sh | bash

దీనిని రన్ చేసే ముందు డౌన్‌లోడ్ చేసి చదవండి. ఈ స్క్రిప్ట్ root యూజర్‌గా రన్ అవుతుంది మరియు మీ హోస్ట్ కాన్ఫిగరేషన్‌ను మారుస్తుంది: ఇది Docker లేకపోతే ఇన్‌స్టాల్ చేస్తుంది, checksum వెరిఫికేషన్‌తో gVisor మరియు Caddy లను డౌన్‌లోడ్ చేస్తుంది, swapfile ను సృష్టిస్తుంది, systemd యూనిట్లను రాస్తుంది మరియు firewall నియమాలను జోడిస్తుంది.

curl -fsSL https://raw.githubusercontent.com/BitMiracle-AI/Dormice/main/deploy/install.sh -o dormice-install.sh
less dormice-install.sh
sudo bash dormice-install.sh --swap-gb 8

--swap-gb అనేది swapfile పరిమాణాన్ని సెట్ చేస్తుంది, దీని డిఫాల్ట్ విలువ 16. చిన్న VPS లలో ఇది ఎక్కువ డిస్క్ స్థలాన్ని తీసుకుంటుంది. --mirror cn డౌన్‌లోడ్‌లను మెయిన్‌ల్యాండ్ చైనా నుండి అందుబాటులో ఉండే మిర్రర్‌లకు మారుస్తుంది. ఇన్‌స్టాలర్‌ను మళ్లీ రన్ చేయడం ద్వారా కోడ్ అప్‌గ్రేడ్ అవుతుంది మరియు మార్పులు సరిచేయబడతాయి, ఇది మీ API token ను ఎప్పటికీ మార్చదు.

కోడ్ /opt/dormice లో, కాన్ఫిగరేషన్ /etc/dormice/env లో, శాండ్‌బాక్స్ డేటా /var/lib/dormice లో, మరియు dormice, dor కమాండ్లు /usr/local/bin లో ఉంటాయి. ఇన్‌స్టాలర్ ఇన్‌స్టాలేషన్ సమయంలో API token ను జనరేట్ చేసి, 600 మోడ్‌తో /etc/dormice/env లో సేవ్ చేస్తుంది.

ఇన్‌స్టాల్ చేయడానికి ఎటువంటి ట్యాగ్ చేయబడిన రిలీజ్ అందుబాటులో లేదు. 4 ఆగస్టు 2026 నాటికి, రిపోజిటరీలో ఎటువంటి git ట్యాగ్‌లు లేదా GitHub రిలీజ్‌లు లేవు, కాబట్టి ఇన్‌స్టాలర్ main ను క్లోన్ చేస్తుంది మరియు ఆ రోజు అందుబాటులో ఉన్న తాజా కోడ్ మీకు లభిస్తుంది. కాబట్టి, ఒక వెర్షన్‌ను స్థిరంగా ఉంచాలంటే (pinning), మీరు ఇన్‌స్టాల్ చేసిన commit హ్యాష్‌ను నోట్ చేసుకోవాలి.

git -C /opt/dormice rev-parse HEAD

ఆ హ్యాష్‌ను మీ డిప్లాయ్ నోట్స్‌లో సేవ్ చేయండి. అప్‌గ్రేడ్ వల్ల ఏదైనా సమస్య వస్తే, ఆ commit మాత్రమే మీకు తిరిగి వెళ్లే మార్గం, ఎందుకంటే అడగడానికి ఎటువంటి వెర్షన్ నంబర్ ఉండదు.

ఇన్‌స్టాలర్ చివరగా dor doctor ను రన్ చేస్తుంది. ఇది కేవలం రీడ్-ఓన్లీ హోస్ట్ చెక్, ఇది ప్యాకేజీ జాబితాను నమ్మకుండా, రన్‌టైమ్ పనిచేస్తుందో లేదో నిర్ధారించడానికి నిజమైన gVisor కంటైనర్లను బూట్ చేస్తుంది. డెమోన్ (daemon) సరిగ్గా పనిచేయనప్పుడు దీనిని మళ్లీ రన్ చేయండి.

sudo dor doctor
systemctl is-active dormice

systemctl is-active dormice రన్ చేసినప్పుడు active అని ప్రింట్ అవ్వాలి. ఒకవేళ failed అని వస్తే, journalctl -u dormice -n 50 లో దానికి కారణం ఉంటుంది. సాధారణంగా స్టార్ట్ అవ్వకపోవడానికి కారణం డెమోన్ కాకుండా swap లేదా gVisor అవసరాలు తీరకపోవడమే.

ఇన్‌స్టాలర్ Caddy ని కూడా ఇన్‌స్టాల్ చేస్తుంది, కాబట్టి firewall పని పూర్తయిందని అనుకునే ముందు ఏ పోర్ట్‌లు వింటున్నాయో (listening) చూడండి.

sudo ss -lntp

ఈ డెమోన్ 127.0.0.1:3676 కి బైండ్ అవుతుంది, దీనిని మార్చడానికి ఎటువంటి సెట్టింగ్ లేదు, ఇది డిజైన్ ప్రకారం అలా ఉంటుంది. మీ ల్యాప్‌టాప్ నుండి దీనిని యాక్సెస్ చేయడం అనేది ఉద్దేశపూర్వక చర్య, దీనికి సులభమైన మార్గం SSH టన్నెల్.

ssh -L 3676:127.0.0.1:3676 root@your-server

టన్నెల్ ఓపెన్ చేసిన తర్వాత, మీ ల్యాప్‌టాప్‌లో http://127.0.0.1:3676/console వెబ్ కన్సోల్‌ను ఓపెన్ చేస్తుంది. టోకెన్‌తో ఒక్కసారి సైన్ ఇన్ అవ్వండి, అది httpOnly సెషన్ కుకీగా మారుతుంది, కాబట్టి పేజీ చదవగలిగే చోట టోకెన్ ఎప్పటికీ స్టోర్ అవ్వదు. అక్కడ ఉన్న Connect పేజీలో మీ సొంత ఎండ్‌పాయింట్‌కు పాయింట్ చేయబడిన క్లయింట్ స్నిప్పెట్‌లు ఉంటాయి, వాటిని కాపీ-పేస్ట్ చేసుకోవచ్చు.

శాండ్‌బాక్స్‌ను సృష్టించి, అందులో కోడ్‌ను అమలు చేయడం

శాండ్‌బాక్స్‌ను సృష్టించడానికి ఒకే ఒక ఆపరేషన్ ఉంది: acquire. ఇది idempotent (అంటే ఎన్నిసార్లు చేసినా ఒకే ఫలితం వస్తుంది), కాబట్టి ఒకే కీని ఉపయోగిస్తే ఎల్లప్పుడూ అదే శాండ్‌బాక్స్ వస్తుంది; అవసరమైతే అది సృష్టించబడుతుంది, మేల్కొల్పబడుతుంది, ప్రారంభించబడుతుంది లేదా పునరుద్ధరించబడుతుంది. మిగిలిన అన్ని క్రియలు, ఇంతకు ముందు చూడని కీ కోసం 404 ఎర్రర్‌ను ఇస్తాయి. dor CLI లో acquire అనే క్రియ లేదు, కాబట్టి మీ మొదటి శాండ్‌బాక్స్‌ను కన్సోల్ లేదా క్లయింట్ లైబ్రరీ ద్వారా పొందాలి.

కన్సోల్ మార్గం అత్యంత వేగవంతమైనది. టన్నెల్ ద్వారా /console ని ఓపెన్ చేసి, my-agent పేరుతో ఒక శాండ్‌బాక్స్‌ను సృష్టించండి. ఆ తర్వాత CLI దానిపై పనిచేస్తుంది.

sudo grep DORMICE_API_TOKEN /etc/dormice/env
export DORMICE_ENDPOINT=http://127.0.0.1:3676
export DORMICE_API_TOKEN=paste-the-value-here
dor sandbox ls
dor sandbox exec my-agent 'python3 --version'

dor sandbox ls ప్రతి శాండ్‌బాక్స్‌ను దాని లైఫ్‌సైకిల్ స్థితితో సహా జాబితా చేస్తుంది, దీని ద్వారా అది active నుండి frozen స్థితికి ఎలా మారుతుందో మీరు గమనించవచ్చు. dor sandbox exec పైథాన్ 3.12 వెర్షన్‌ను ప్రింట్ చేస్తుంది, ఎందుకంటే స్టాక్ ఇమేజ్ Ubuntu 24.04 లో పైథాన్ 3.12, Node 24, git మరియు ripgrep ఇప్పటికే ఇన్‌స్టాల్ చేయబడి ఉంటాయి. ఒకవేళ authentication ఎర్రర్ వస్తే, మీరు కాపీ చేసిన టోకెన్ లైన్‌లో వేరియబుల్ పేరు కూడా ఉందని అర్థం.

ఫైళ్లు dor sandbox push my-agent ./script.py తో తరలించబడతాయి, ఇవి /home/user/script.py వద్ద చేరుతాయి, మరియు dor sandbox pull my-agent notes.txt ద్వారా తిరిగి పొందవచ్చు. నేటివ్ ఫైల్ క్రియలు ఒక్కో ఫైల్‌కు 16 MiB పరిమితిని కలిగి ఉంటాయి, అయితే E2B ఫైల్ సర్ఫేస్ స్ట్రీమింగ్‌ను అనుమతిస్తుంది, దీనివల్ల శాండ్‌బాక్స్ డిస్క్ కోటా మాత్రమే ఏకైక పరిమితిగా ఉంటుంది.

Destroying (ధ్వంసం చేయడం) అనేది డేటాను కోల్పోయే ఏకైక క్రియ, మరియు ఇది ప్రాజెక్ట్ యొక్క వయస్సును తెలిపే ఒక మంచి ఉదాహరణ: ప్రధాన README మరియు దానితో పాటు ఉన్న ఏజెంట్ స్కిల్ రెండూ dor sandbox destroy <key> గురించి వివరిస్తాయి, అయితే CLI ప్యాకేజీ README లో dor sandbox release <key> గురించి ఉంది. మీ స్వంత బిల్డ్‌పై dor sandbox --help ని రన్ చేయండి మరియు దానినే నమ్మండి.

మీ ప్రస్తుత E2B కోడ్‌ను మీ స్వంత సర్వర్‌కు మళ్లించండి

దీని కోసమే మీరు దీనిని పరిగణనలోకి తీసుకోవాలి. npm నుండి లభించే అధికారిక e2b ప్యాకేజీ, ఎటువంటి మార్పులు లేకుండానే, Dormice తో కమ్యూనికేట్ చేస్తుంది. మీ ల్యాప్‌టాప్ నుండి SSH టన్నెల్ ఓపెన్ చేసి దీనిని రన్ చేయండి, తద్వారా సర్వర్‌లో కొత్తగా ఏదీ వినబడదు (listen అవ్వదు).

npm init -y
npm i e2b tsx

import { Sandbox } from 'e2b';

const sbx = await Sandbox.create({
  apiKey: `e2b_${process.env.DORMICE_API_TOKEN}`,
  apiUrl: 'http://127.0.0.1:3676/e2b/api',
  sandboxUrl: 'http://127.0.0.1:3676/e2b/envd',
});

const result = await sbx.commands.run('python3 -c "print(6 * 7)"');
console.log(result.exitCode, result.stdout);

await sbx.kill();

DORMICE_API_TOKEN=paste-the-value-here npx tsx index.ts

సరిగ్గా రన్ అయినప్పుడు ఎగ్జిట్ కోడ్ 0 మరియు 42 ప్రింట్ అవుతాయి. మీ API కీ అనేది మీ Dormice టోకెన్, దీనికి ముందు e2b_ ప్రిఫిక్స్‌ను చేర్చాలి; కంపాటబిలిటీ లేయర్ ఆశించే ఫార్మాట్ ఇదే.

ఈ కంపాటబిలిటీ కేవలం ఒక స్టబ్ (stub) మాత్రమే కాదు. స్ట్రీమింగ్ stdout మరియు stderr, బ్యాక్‌గ్రౌండ్ కమాండ్‌లు, ఇంటరాక్టివ్ PTY, సైన్డ్ అప్‌లోడ్ మరియు డౌన్‌లోడ్ URLలు, డైరెక్టరీ వాచింగ్ మరియు పోర్ట్ ప్రాక్సీ వంటివన్నీ అధికారిక ప్యాకేజీ ద్వారా, ప్రాజెక్ట్ యొక్క ఎండ్-టు-ఎండ్ సూట్ ఉపయోగించి నిజమైన Docker మరియు gVisor డెమన్‌లపై పరీక్షించబడ్డాయి. మీరు ఏదైనా ముఖ్యమైన దానిని మైగ్రేట్ చేసే ముందు ఈ క్రింది వ్యత్యాసాలను గమనించండి:

• టెంప్లేట్ బిల్డ్‌లు అమలు చేయబడలేదు. టెంప్లేట్ అనేది మీరు స్వయంగా బిల్డ్ చేసి dor template add తో రిజిస్టర్ చేసే ఒక docker ఇమేజ్, దీనిని Sandbox.create('name') రిజాల్వ్ చేస్తుంది. రిజిస్టర్ చేయని పేరును ఇస్తే, అది ఏదో ఒకటి చూపించడానికి ప్రయత్నించకుండా 404 ఎర్రర్‌ను ఇస్తుంది.
• E2B ఇంటర్‌ఫేస్ ద్వారా సృష్టించబడిన శాండ్‌బాక్స్‌లకు నిజమైన డెడ్‌లైన్‌లు ఉంటాయి, ఎందుకంటే E2B సెమాంటిక్స్ వాటిని కోరుతాయి. నేటివ్ API ద్వారా సృష్టించబడిన శాండ్‌బాక్స్‌లకు ఎటువంటి డెడ్‌లైన్‌లు ఉండవు.
• ఫ్రీజ్ చేయబడిన శాండ్‌బాక్స్ దాని ప్రాసెస్‌లను అలాగే ఉంచి, మధ్యలోనే తిరిగి ప్రారంభిస్తుంది (resume). కాబట్టి ఇక్కడ పాజ్ మరియు రిజ్యూమ్ అనేది మీరు అలవాటు పడిన స్టాప్ మరియు కోల్డ్ స్టార్ట్ వంటివి కావు.

శాండ్‌బాక్స్ దేనిని అడ్డుకుంటుంది, దేనిని అడ్డుకోదు

gVisor కంటైనర్ యొక్క సిస్టమ్ కాల్‌లను యూజర్‌స్పేస్‌లో అడ్డుకుని, వాటిని తానే నిర్వహిస్తుంది. కాబట్టి శాండ్‌బాక్స్‌లో ఉన్న కోడ్ నేరుగా మీ హోస్ట్ కెర్నల్‌తో సంభాషించదు. శాండ్‌బాక్స్ లోపల, ప్రతిదీ uid 1000 అనే అన్‌ప్రివిలేజ్డ్ యూజర్‌గా నడుస్తుంది. ఈ కలయిక సాధారణ పరిస్థితులను చక్కబెడుతుంది: ఉదాహరణకు, ఒక జనరేటెడ్ స్క్రిప్ట్ rm -rf / ని రన్ చేసినా, డిస్క్‌ను నింపేసినా, లేదా ఏదైనా ఆగిపోయే వరకు ఫోర్క్ (fork) చేసినా, అది తన సొంత శాండ్‌బాక్స్‌కు మాత్రమే పరిమితమై ఆగిపోతుంది.

ఇది అడ్డుకోలేని విషయాలు ఇక్కడ ఉన్నాయి. వీటిని నిర్వహించడం మీ బాధ్యత.

• శాండ్‌బాక్స్‌కు బయటకు వెళ్లే నెట్‌వర్క్ సౌకర్యం ఉంటుంది. జనరేటెడ్ కోడ్ తనకు నచ్చిన దాన్ని డౌన్‌లోడ్ చేసుకోవచ్చు మరియు దొరికిన సమాచారాన్ని ఎక్కడికైనా పంపవచ్చు. ఇన్‌స్టాలర్ యొక్క నెట్‌వర్క్ హార్డెనింగ్ రెండు నిర్దిష్ట విషయాలను కవర్ చేస్తుంది: ఇది 169.254.0.0/16 వద్ద ఉన్న క్లౌడ్ మెటాడేటా సర్వీస్‌కు కంటైనర్ ట్రాఫిక్‌ను నిలిపివేస్తుంది (ఇక్కడ నుంచే క్లౌడ్ ఇన్‌స్టాన్స్ క్రెడెన్షియల్స్ పొందుతుంది), మరియు Docker యొక్క daemon.json లో "icc": false ద్వారా కంటైనర్-టు-కంటైనర్ ట్రాఫిక్‌ను ఆపివేస్తుంది. వీటిని మించి మరేదీ బ్లాక్ చేయబడదు. sudo iptables -S DOCKER-USER ని చదవండి మరియు శాండ్‌బాక్స్‌కు సంబంధం లేని ప్రైవేట్ రేంజ్‌ల కోసం మీ స్వంత DROP రూల్స్‌ను జోడించండి.
• Docker తన సొంత రూల్స్‌ను మీ ఫైర్‌వాల్ కంటే ముందుగా ఇన్‌సర్ట్ చేస్తుంది. కాబట్టి, ufw క్లోజ్ అని చూపిస్తున్నా, పబ్లిష్ చేసిన కంటైనర్ పోర్ట్ ఇంటర్నెట్ నుండి స్పందించవచ్చు. ఈ హోస్ట్‌లో దేనినైనా ఎక్స్‌పోజ్ చేసే ముందు Docker ఎలా పోర్ట్‌లను ufw దాటి పబ్లిష్ చేస్తుంది మరియు VPS కోసం ufw ఫైర్‌వాల్ ప్రాథమికాంశాలు చదవండి.
• gVisor అనేది యూజర్‌స్పేస్ కెర్నల్, హైపర్‌వైజర్ కాదు. ఇది ఉద్దేశపూర్వకమైన నిర్ణయం, ఎందుకంటే ఫ్రీజింగ్ కోసం శాండ్‌బాక్స్‌లు ప్రాసెస్‌లుగా ఉండాలి, మరియు KVM అవసరమైతే ఎక్కడైనా ఇన్‌స్టాల్ చేయడం సాధ్యపడదు. మీ థ్రెట్ మోడల్‌కు హార్డ్‌వేర్ వర్చువలైజేషన్ అవసరమైతే, Firecracker-స్థాయి ఐసోలేషన్‌ను ఉపయోగించండి మరియు దానితో వచ్చే నిర్వహణ ఖర్చును అంగీకరించండి.
• క్లయింట్ వైపు API టోకెన్ అనేది పూర్తి భద్రతా సరిహద్దు. DORMICE_API_TOKEN కలిగి ఉన్న ఏదైనా, మెషీన్‌లోని ప్రతి శాండ్‌బాక్స్‌ను సృష్టించగలదు, చదవగలదు మరియు నాశనం చేయగలదు. ఏజెంట్ ప్రాసెస్‌కు దాని స్వంత VPSపై కనిష్ట అధికారాలు కలిగిన యూజర్ను కేటాయించండి మరియు టోకెన్‌ను మీరు SSH కీని చూసే విధంగానే జాగ్రత్తగా చూడండి. VPSపై Claude Code సురక్షితంగా రన్ చేయడం నుండి నేర్చుకున్న అలవాట్లు ఇక్కడ నేరుగా వర్తిస్తాయి.

డెమోన్ స్వయంగా మీ హోస్ట్‌లో root గా నడుస్తుంది. gVisor శాండ్‌బాక్స్ లోపల ఉన్న కోడ్ నుండి హోస్ట్‌ను రక్షిస్తుంది, కానీ డెమోన్ నుండి లేదా దాని టోకెన్ కలిగి ఉన్న వారి నుండి హోస్ట్‌ను ఏదీ రక్షించదు. కాబట్టి Dormice నడిపే మెషీన్ కేవలం ఆ పని మాత్రమే చేసేలా ఉండాలి. మీ ఏజెంట్ MCP (model context protocol) ద్వారా టూల్స్‌ను చేరుకుంటే, అదే కారణంతో ఆ MCP సర్వర్లను వేరే VPSలో ఉంచండి.

4 GB మరియు 8 GB RAMలో ఎన్ని sandboxes సరిపోతాయి?

మెమరీని ప్రధానంగా రెండు అంశాలు వినియోగిస్తాయి: హోస్ట్ యొక్క బేస్‌లైన్ మరియు ప్రస్తుతం రన్ అవుతున్న ప్రతి sandbox యొక్క వర్కింగ్ సెట్. Ubuntu, Docker మరియు daemon కోసం సుమారు 1 GB మెమరీని కేటాయించండి. మిగిలిన మెమరీని మీ sandbox వాస్తవంగా వినియోగించే మెమరీతో భాగించండి. కొన్ని ఫైళ్లను చదివే Python స్క్రిప్ట్‌ను రన్ చేసే sandbox సుమారు 200 నుండి 300 MiB మెమరీని తీసుకుంటుంది. కంపైలర్ లేదా పూర్తి టెస్ట్ సూట్‌ను రన్ చేసే sandbox ఒక gibibyte కంటే ఎక్కువ మెమరీని తీసుకోవచ్చు.

[
  {
    "host": "4 GB VPS",
    "active_at_512_mib": 6,
    "active_at_1_gib": 3,
    "frozen_on_16gb_swap": 16
  },
  {
    "host": "8 GB VPS",
    "active_at_512_mib": 14,
    "active_at_1_gib": 7,
    "frozen_on_16gb_swap": 16
  }
]

ఒక 4 GB VPS లో, ప్రతి sandbox 512 MiB ఉపయోగిస్తే ఒకేసారి 6 sandboxes, లేదా ప్రతిదీ ఒక పూర్తి gibibyte ఉపయోగిస్తే 3 sandboxes రన్ అవుతాయి. 8 GB VPS లో ఈ సంఖ్య 14 మరియు 7 కి పెరుగుతుంది. ఇవి ఏకకాలంలో పనిచేసే పనుల కోసం గరిష్ట పరిమితులు మాత్రమే; ఇవి కేవలం గణితపరమైన అంచనాలు కాబట్టి, మీ లోడ్ రన్ అవుతున్నప్పుడు free -m ని గమనిస్తూ ఉండండి.

Frozen sandboxes RAMకు బదులుగా swap ద్వారా పరిమితం చేయబడతాయి, ఇదే ఈ డిజైన్ యొక్క ముఖ్య ఉద్దేశ్యం. ఒక gibibyte మెమరీని ఆక్రమించిన frozen sandbox, swap లో దాదాపు అంతే మొత్తాన్ని ఉంచుకుని, RAMలో ఏమీ లేకుండా చూసుకుంటుంది. కాబట్టి, ఇన్‌స్టాలర్ యొక్క డిఫాల్ట్ 16 GB swapfile సుమారు 16 sandboxes ను నిల్వ చేయగలదు. ఆ పరిమితి దాటిన తర్వాత, అవి stopped స్థితికి చేరుకోవాలి, అక్కడ అవి కేవలం డిస్క్ స్థలాన్ని మాత్రమే ఆక్రమిస్తాయి. దీర్ఘకాలంలో డిస్క్ స్థలమే అసలైన పరిమితి: ప్రతి sandbox తన ఫైల్‌సిస్టమ్‌ను కలిగి ఉంటుంది. కొన్ని డజన్ల ఏజెంట్లు, ప్రతి ఒక్కటి node_modules డైరెక్టరీని కలిగి ఉంటే, మెమరీ సమస్య రాకముందే చిన్న వాల్యూమ్ నిండిపోతుంది.

Freeze, stop, archive: జీవితచక్ర నియంత్రణలు

డిఫాల్ట్‌గా, 10 నిమిషాల పాటు నిష్క్రియంగా (idle) ఉంటే freeze, 3 రోజుల తర్వాత stop, మరియు archiving కాన్ఫిగర్ చేసినప్పుడు 7 రోజుల తర్వాత archive అవుతాయి. stopAfterSeconds ను null కి సెట్ చేస్తే, అది resident agent గా మారుతుంది: ఇది నిష్క్రియంగా ఉన్నప్పుడు freeze అవ్వవచ్చు, కానీ ఎప్పటికీ cold start అవ్వదు.

Archiving అనేది ఐచ్ఛికం, మరియు daemon దీని విషయంలో పారదర్శకంగా ఉంటుంది. నాలుగు DORMICE_S3_* వేరియబుల్స్‌ను సెట్ చేస్తే, ఆగిపోయిన sandbox యొక్క డిస్క్ tar మరియు zstd తో ప్యాక్ చేయబడి, ఏదైనా S3-compatible బకెట్‌కు పంపబడుతుంది (shipped), ఆపై స్థానికంగా ఖాళీ చేయబడుతుంది. ఆ బకెట్ మీరు స్వయంగా హోస్ట్ చేసుకునే MinIO బకెట్ కావచ్చు, ఇది మీ మరొక మెషీన్‌లో ఉంటుంది. వేరియబుల్స్‌ను సెట్ చేయకుండా వదిలేస్తే, sandboxes శాశ్వతంగా stopped స్థితిలోనే ఉంటాయి, మరియు archive చేయమని కోరే పాలసీని నిశ్శబ్దంగా విస్మరించకుండా తిరస్కరిస్తుంది. Restore ప్రక్రియలు నిశ్శబ్దంగా కాకుండా కనిపిస్తాయి: తదుపరి acquire అభ్యర్థన వెంటనే restoring స్థితిని మరియు progress విలువను చూపుతుంది, ఆపై డిస్క్ తిరిగి వచ్చిన తర్వాత ready స్థితికి మారుతుంది.

దీనిపై ఇంకా ఆధారపడవచ్చా?

నేరుగా చెప్పాలంటే: మీరు తిరిగి నిర్మించలేని దేనికీ దీనిని వాడకండి. ఈ రిపోజిటరీలోని మొదటి కమిట్ 8 July 2026 నాటిది. 4 August 2026 నాటికి, ఇది 446 స్టార్లను, 37 ఫోర్కులను కలిగి ఉంది, Apache-2.0 లైసెన్స్‌తో ఉంది, కానీ ఇప్పటివరకు ఎటువంటి tagged release లేదు. README లోని స్టేటస్ లైన్ ప్రకారం, ఇందులో ఏదీ ప్రొడక్షన్ కోసం సిద్ధంగా లేదు.

ఈ కలయిక ఒక ప్రత్యేకమైన ప్రమాదాన్ని కలిగిస్తుంది. ఇన్‌స్టాలర్ main ని ట్రాక్ చేస్తుంది కాబట్టి, కోడ్ నిరంతరం మారుతూ ఉంటుంది. ఇంటర్‌ఫేస్ ఇంకా స్థిరపడలేదు, అందుకే ఒకే రిపోజిటరీలోని రెండు వేర్వేరు ఫైళ్లలో 'delete' అనే క్రియకు రెండు వేర్వేరు పేర్లు ఉన్నాయి. నాలుగు వారాల వయస్సు ఉన్న ప్రాజెక్ట్ ఎప్పుడైనా ఆగిపోవచ్చు, ఎందుకంటే ప్రాజెక్ట్‌ను కొనసాగించాల్సిన బాధ్యత ఏ లైసెన్స్ నిబంధనలోనూ లేదు.

ఈ ప్రమాదాన్ని తట్టుకోగలగడానికి కారణం E2B అనుకూలత (compatibility). మీ అప్లికేషన్ ఒక ప్రోటోకాల్‌తో మాట్లాడుతుంది, దాని వెనుక హోస్ట్ చేసిన ఇంప్లిమెంటేషన్ ఉంది. కాబట్టి Dormice ఆగిపోతే, మీరు రెండు URLలను మార్చి పనిని కొనసాగించవచ్చు. నేటివ్ API కి బదులుగా E2B ఇంటర్‌ఫేస్‌పై మీ ఏజెంట్‌ను రూపొందించండి, తద్వారా మీరు బయటపడే మార్గాన్ని కలిగి ఉంటారు. నేటివ్ @dormice/sdk ప్యాకేజీ ఇంకా npm లో లేదు, కాబట్టి దానిని ఉపయోగించాలంటే రిపోజిటరీ నుండి బిల్డ్ చేయాల్సి ఉంటుంది. ఇది కూడా అనుకూలమైన మార్గంతో ప్రారంభించడానికి రెండవ కారణం.

దీనిని మీరు కోల్పోయినా పర్వాలేదు అనుకునే చోట మాత్రమే రన్ చేయండి. హోస్ట్‌ను స్క్రిప్ట్ ద్వారా తిరిగి నిర్మించండి, టోకెన్‌ను ప్రతి ప్రాంప్ట్ మరియు ప్రతి కమిట్ నుండి దూరంగా ఉంచండి, మరియు భద్రపరచాల్సిన దేనినైనా మీ స్వంత బ్యాకప్ షెడ్యూల్ ప్రకారం శాండ్‌బాక్స్‌ల నుండి బయటకు తీయండి.

FAQ

Dormice ప్రొడక్షన్ కోసం సిద్ధంగా ఉందా?

లేదు, ఈ ప్రాజెక్ట్ స్వయంగా ఇదే విషయాన్ని పేర్కొంది. README లోని స్టేటస్ లైన్ ప్రకారం, అందులోని ఏదీ ఇంకా ప్రొడక్షన్ కోసం సిద్ధంగా లేదు. 4 ఆగస్టు 2026 నాటికి, ఈ రిపోజిటరీ సుమారు నాలుగు వారాల క్రితమే ప్రారంభమైంది; ఇందులో ఎటువంటి git tags లేదా releases లేవు, కాబట్టి పిన్ చేయడానికి వెర్షన్ నంబర్ కూడా లేదు. ఇన్‌స్టాలర్ main బ్రాంచ్‌ను క్లోన్ చేస్తుంది, అంటే ప్రతి రన్ మీకు సరికొత్త కమిట్‌ను అందిస్తుంది. ప్రతి ఇన్‌స్టాలేషన్ తర్వాత git -C /opt/dormice rev-parse HEAD రికార్డ్ చేయండి, మరియు విలువైన సమాచారాన్ని శాండ్‌బాక్స్‌ల వెలుపల ఉంచండి.

నా ఏజెంట్‌కు డిస్పోజబుల్ VM ఇవ్వడానికి, Dormice కి తేడా ఏమిటి?

డిస్పోజబుల్ VM అనేది ఒక సెషన్ కోసం మీరు సృష్టించి, ఆ తర్వాత తొలగించే SSH కలిగిన మెషిన్. Dormice అనేది ఒక ఎగ్జిక్యూషన్ API: మీ ప్రోగ్రామ్ acquire, ఆపై exec కాల్ చేస్తుంది, మధ్యలో ఎటువంటి షెల్ సెషన్ లేకుండానే stdout మరియు ఎగ్జిట్ కోడ్‌ను తిరిగి పొందుతుంది. ఒక మనిషికి లేదా కొంత సమయం పాటు పూర్తి కంప్యూటర్ అవసరమైన ఏజెంట్‌కు VM సరిపోతుంది. రోజుకు అనేకసార్లు జనరేట్ చేసిన కోడ్‌ను రన్ చేసే అప్లికేషన్‌కు, ప్రతి రన్‌కు మెషిన్ సెటప్ మరియు టేర్‌డౌన్ అవసరం లేని Dormice సరిపోతుంది.

అధికారిక E2B SDK నిజంగా కోడ్ మార్పులు లేకుండా పనిచేస్తుందా?

అవును, కాన్ఫిగరేషన్ మార్పులతో పనిచేస్తుంది. apiUrl మరియు sandboxUrl లను మీ డెమన్‌లోని /e2b/api మరియు /e2b/envd కి పాయింట్ చేయండి, మరియు మీ Dormice టోకెన్‌ను e2b_ ప్రిఫిక్స్‌తో API కీగా అందించండి. కమాండ్ ఎగ్జిక్యూషన్, PTY సెషన్లు, ఫైల్ ట్రాన్స్‌ఫర్, సైన్డ్ URLలు మరియు పోర్ట్ ప్రాక్సీ అన్నీ అధికారిక ప్యాకేజీ ద్వారా రన్ అయ్యే ప్రాజెక్ట్ యొక్క ఎండ్-టు-ఎండ్ సూట్ ద్వారా కవర్ చేయబడతాయి. టెంప్లేట్ బిల్డింగ్ అనేది ఒక ముఖ్యమైన లోపం: e2b template build అమలు చేయబడలేదు, కాబట్టి టెంప్లేట్ అనేది మీరు బిల్డ్ చేసి dor template add తో రిజిస్టర్ చేసే ఒక Docker ఇమేజ్ మాత్రమే.

4 GB VPS పై ఎన్ని శాండ్‌బాక్స్‌లు సరిపోతాయి?

ఆపరేటింగ్ సిస్టమ్, Docker మరియు డెమన్ కోసం సుమారు 1 GB రిజర్వ్ చేసిన తర్వాత, ప్రతి శాండ్‌బాక్స్ 512 MiB ఉపయోగిస్తే ఒకే సమయంలో 6 శాండ్‌బాక్స్‌లు, లేదా ప్రతిదీ ఒక పూర్తి గిబిబైట్ ఉపయోగిస్తే 3 శాండ్‌బాక్స్‌లు రన్ అవుతాయి. ఫ్రోజెన్ (Frozen) శాండ్‌బాక్స్‌లు swap ద్వారా పరిమితం చేయబడతాయి, కాబట్టి ఇన్‌స్టాలర్ యొక్క డిఫాల్ట్ 16 GB swapfile సుమారు 16 శాండ్‌బాక్స్‌లను ఉంచగలదు (ప్రతిదీ ఒక గిబిబైట్ కలిగి ఉంటే). వాస్తవ లోడ్ కింద free -m తో మీ స్వంత కొలతలను తీసుకోండి, ఎందుకంటే టెస్ట్ సూట్‌ను రన్ చేసే శాండ్‌బాక్స్, చిన్న స్క్రిప్ట్‌ను రన్ చేసే దానికంటే చాలా ఎక్కువ మెమరీని ఉపయోగిస్తుంది.

Dormice కి vm.swappiness ను 100 కి సెట్ చేయడం ఎందుకు అవసరం?

శాండ్‌బాక్స్‌ను ఫ్రీజ్ చేయడం అంటే దాని ఐడిల్ మెమరీని swap లోకి పంపడం. gVisor శాండ్‌బాక్స్ మెమరీని షేర్డ్ మెమరీగా ఉంచుతుంది, మరియు Linux కెర్నల్ డిఫాల్ట్ swappiness వద్ద షేర్డ్ మెమరీని swap చేయదు. కాబట్టి డిఫాల్ట్ సెట్టింగ్‌లో ఫ్రీజ్ చేసినప్పుడు ఏమీ రికవరీ అవ్వదు మరియు శాండ్‌బాక్స్ పూర్తి మెమరీని వినియోగిస్తూనే ఉంటుంది. డిఫాల్ట్ సెట్టింగ్‌లో 0 బైట్లు రికవరీ అవ్వగా, 100 వద్ద 99.5 శాతం రికవరీ అవుతుందని ప్రాజెక్ట్ పరీక్షల్లో తేలింది. కాన్ఫిగరేషన్ ఫైళ్లను చదవడం కంటే sysctl vm.swappiness తో ఎఫెక్టివ్ వాల్యూని తనిఖీ చేయండి, ఎందుకంటే కొన్ని క్లౌడ్ ఇమేజ్‌లు 0 వాల్యూతో వస్తాయి.