VPSలో KiroCrewను self-host చేయడం ఎలా?

ల్యాప్‌టాప్‌కు బదులుగా VPSలో KiroCrewను ఎందుకు self-host చేయాలి

KiroCrewను ఎల్లప్పుడూ ఆన్‌లో ఉండే యంత్రంపై self-host చేయడం మాత్రమే ప్రయోజనకరం, అందుకే దీనికి VPS సరైనది, ల్యాప్‌టాప్ కాదు. KiroCrew సెషన్ హిస్టరీ, సెమాంటిక్ మెమరీ, షెడ్యూల్ చేసిన పనులు మరియు అప్రూవల్ క్యూను డిస్క్‌లో భద్రపరుస్తుంది, ప్రాసెస్ రీస్టార్ట్ అయినప్పుడు వీటన్నింటినీ తిరిగి లోడ్ చేస్తుంది. షెడ్యూల్ చేసిన పని జరగాల్సిన 03:00 గంటల సమయంలో ప్రాసెస్ రన్ అవ్వకపోతే ఇవేవీ ఉపయోగపడవు, మూసివేసిన ల్యాప్‌టాప్‌లో ఇది రన్ అవ్వదు.

KiroCrew అనేది Kiro టీమ్ నుండి వచ్చిన ఓపెన్ సోర్స్ ఏజెంట్ వర్క్‌స్పేస్, ఇది Apache 2.0 లైసెన్స్‌తో ఉంటుంది. దీని మొదటి పబ్లిక్ releases 2026 ఆగస్టు ప్రారంభంలో వచ్చాయి. గేట్‌వే అని పిలువబడే ఒకే ఒక ప్రాసెస్, స్టేట్‌ను కలిగి ఉండి, 5476 పోర్ట్‌లో వెబ్ డ్యాష్‌బోర్డ్‌ను అందిస్తుంది. మీరు ఈ గేట్‌వేను డ్యాష్‌బోర్డ్ నుండి, kirocrew CLI నుండి లేదా Slack వంటి చాట్ ఛానల్ నుండి యాక్సెస్ చేయవచ్చు. మీరు self-host చేస్తున్నది ఈ గేట్‌వేను మాత్రమే, కాబట్టి ఈ గైడ్ దానిని నిరంతరం రన్ చేయడం, పబ్లిక్ ఇంటర్నెట్‌కు దూరంగా ఉంచడం మరియు ఏదైనా అప్‌గ్రేడ్ విఫలమైతే తిరిగి పునరుద్ధరించడం గురించి వివరిస్తుంది.

మీరు ప్రారంభించే ముందు రెండు విషయాలు తెలుసుకోవాలి. KiroCrew అనేది kiro-cliను నడుపుతుంది, దీనికి Kiro ఖాతాతో ఒకసారి సైన్-ఇన్ అవసరం. ఏజెంట్ ఇన్ఫరెన్స్ (inference) Kiro ప్లాన్ ద్వారా బిల్ చేయబడుతుంది, కాబట్టి 2026 ఆగస్టు నాటికి ఇది పూర్తిగా ఆఫ్‌లైన్ సెటప్ కాదు. ఈ ప్రాజెక్ట్ ప్రారంభమై కొన్ని వారాలే అవుతోంది. ఏదో ఒక సమయంలో మీరు వెర్షన్‌ను రోల్ బ్యాక్ చేయాల్సి వస్తుందని భావించండి, కాబట్టి అందుకు వీలుగా దీన్ని ఇన్‌స్టాల్ చేయండి. మీరు ఇంతకుముందు సర్వర్‌పై ఏజెంట్‌ను రన్ చేయకపోతే, VPSలో కోడింగ్ ఏజెంట్‌ను రన్ చేయడం అనే గైడ్ ఈ గైడ్‌కు అవసరమైన ప్రాథమిక సూత్రాలను వివరిస్తుంది.

KiroCrew కు అవసరమైనవి మరియు దాని స్థితి ఎక్కడ నిక్షిప్తమవుతుంది

నేటివ్ ఇన్‌స్టాలేషన్‌కు Python 3.10 లేదా అంతకంటే కొత్త వెర్షన్ (ప్రాజెక్ట్ 3.12ని సిఫార్సు చేస్తుంది), మీరు డాష్‌బోర్డ్‌ను సోర్స్ నుండి బిల్డ్ చేస్తే Node.js 18 లేదా అంతకంటే కొత్త వెర్షన్, మరియు kiro-cli అవసరం. మొదటిసారి లాంచ్ చేసినప్పుడు ఇది మీ కోసం ఇన్‌స్టాల్ అయ్యి, సైన్ ఇన్ అవుతుంది. కంటైనర్ ఇన్‌స్టాలేషన్‌కు హోస్ట్ మెషీన్‌లో వీటిలో ఏదీ అవసరం లేదు. దీనికి కేవలం Docker ఉంటే సరిపోతుంది. దీన్ని ఎంచుకోవడానికి ఇదే ప్రధాన కారణం.

స్టేట్ (స్థితి) ~/.kiro/crew లో నిక్షిప్తమవుతుంది, మరియు KIROCREW_HOME ఎన్విరాన్‌మెంట్ వేరియబుల్ ద్వారా దీన్ని వేరే చోటికి మార్చవచ్చు. ఇందులో ఉండేవి:

• config.json: గేట్‌వే సెట్టింగ్‌లు మరియు చాట్ ఛానల్ క్రెడెన్షియల్స్.
• .env: సీక్రెట్స్.
• workspace/memory/: ప్రాధాన్యతలు, ప్రాజెక్ట్ నోట్స్ మరియు చాట్ హిస్టరీ.
• memory.db మరియు memory_index.db: సెమాంటిక్ మరియు ఫుల్-టెక్స్ట్ ఇండెక్స్‌లు.
• models/: ఎంబెడ్డింగ్ మోడల్, ఇది మొదటిసారి రన్ చేసినప్పుడు డౌన్‌లోడ్ అవుతుంది.
• gateway.log మరియు security_events.jsonl: రన్‌టైమ్ లాగ్ మరియు సెక్యూరిటీ ఈవెంట్ లాగ్.

ఆ డైరెక్టరీయే మీ ఇన్‌స్టాలేషన్. దాన్ని కొత్త VPSకి కాపీ చేస్తే మీ ఏజెంట్ అక్కడికి మారుతుంది, అందుకే ఇన్‌స్టాలేషన్ విభాగం కంటే కింద ఉన్న బ్యాకప్ విభాగం చాలా ముఖ్యం.

RAM కంటే డిస్క్ స్పేస్ కోసం ప్లాన్ చేసుకోండి. గేట్‌వే అనేది ఒక Python ప్రాసెస్; ఏజెంట్ రన్ చేసే బిల్డ్ లేదా టెస్ట్ సూట్ వంటివే అసలైన లోడ్‌ను కలిగిస్తాయి. చాట్ హిస్టరీ పెరిగేకొద్దీ స్టేట్ డైరెక్టరీ పరిమాణం పెరుగుతుంది, మరియు ఎంబెడ్డింగ్ మోడల్ మొదటి స్టార్టప్‌లోనే వస్తుంది. కాబట్టి, ప్రాజెక్ట్ ప్రారంభమైన మొదటి నెలలో ప్రచురించిన గణాంకాలను నమ్మే బదులు, కొన్ని వారాల తర్వాత మీ సొంత బాక్స్‌లో du -sh ~/.kiro/crew ఉపయోగించి పరిమాణాన్ని కొలవండి.

మూడు ఇన్‌స్టాలేషన్ మార్గాలలో దేనిని ఎంచుకోవాలి

ఈ ప్రాజెక్ట్ మూడు మార్గాలను అందిస్తుంది. వన్-లైన్ ఇన్‌స్టాలర్ ఒక wheel ఫైల్‌ను డౌన్‌లోడ్ చేసి, kirocrew ను మీ PATH లో ఉంచుతుంది:

curl -fsSL https://download.crew.kiro.dev/cli.sh | sh

ఇది ఒక channel ఫ్లాగ్ మరియు ఒక version ఫ్లాగ్‌ను తీసుకుంటుంది:

curl -fsSL https://download.crew.kiro.dev/cli.sh | sh -s -- --channel insider
curl -fsSL https://download.crew.kiro.dev/cli.sh | sh -s -- --version 0.1.3

కంటైనర్ ఇమేజ్ ghcr.io/kirodotdev/kirocrew వద్ద, ప్రతి ట్యాగ్ కింద linux/amd64 మరియు linux/arm64 కోసం ప్రచురించబడుతుంది. సోర్స్ బిల్డ్ అనేది git clone మరియు make build ల కలయిక, ఇది కోడ్‌ను మార్చే వారి కోసం ఉద్దేశించబడింది, కేవలం రన్ చేసే వారి కోసం కాదు.

కంటైనర్‌ను ఉపయోగించండి. నేటివ్ ఇన్‌స్టాలేషన్ ద్వారా Python ప్యాకేజీలు, Node మరియు kiro-cli మీ ఇతర సేవలు నడుస్తున్న అదే హోస్ట్‌పై ఇన్‌స్టాల్ అవుతాయి. దీనివల్ల ఏదైనా అప్‌గ్రేడ్ విఫలమైతే, మీరు వాటిని మాన్యువల్‌గా సరిచేయాల్సి ఉంటుంది. కంటైనర్ రన్‌టైమ్‌ను ఒకే ఇమేజ్‌లో మరియు స్టేట్‌ను ఒకే వాల్యూమ్‌లో ఉంచుతుంది, దీనివల్ల రోల్‌బ్యాక్ చేయడం అంటే కేవలం ట్యాగ్‌ను మార్చి రీస్టార్ట్ చేయడం మాత్రమే అవుతుంది.

ఇమేజ్‌ను ఒక release tagకి పిన్ చేయండి, stableకి కాదు

ఈ ప్రాజెక్ట్ యొక్క సొంత ఉదాహరణ stable ట్యాగ్‌ను ఉపయోగిస్తుంది:

docker run -d --name kirocrew \
  -p 127.0.0.1:5476:5476 \
  -v kirocrew-home:/home/kirocrew \
  ghcr.io/kirodotdev/kirocrew:stable

stable అనేది మారుతూ ఉండే (moving) ట్యాగ్. ఇది ఆ సమయంలో అందుబాటులో ఉన్న సరికొత్త stable releaseని సూచిస్తుంది. కాబట్టి, మీరు తదుపరిసారి pull చేసినప్పుడు, మీరు ఎంచుకోకుండానే రన్ అవుతున్న వెర్షన్ మారిపోవచ్చు మరియు ఆ ట్యాగ్ ఏ వెర్షన్ రన్ అవుతుందో ఎక్కడా నమోదు చేయదు. వెర్షన్ ట్యాగ్‌లు మార్చలేనివి (immutable), కాబట్టి ఒక నిర్దిష్ట వెర్షన్‌ను పిన్ చేయండి. 6 August 2026 నాటికి సరికొత్త release 0.1.3, ఇది 5 August 2026న ప్రచురించబడింది. ఇందులో nightly అనే ట్యాగ్ కూడా ఉంది, ఇంత కొత్త ప్రాజెక్ట్‌లో దీని అర్థం ఈ ఉదయమే కోడ్ మార్చబడిందని.

/opt/kirocrew/compose.yamlని ఇలా రాయండి:

services:
  kirocrew:
    image: ghcr.io/kirodotdev/kirocrew:0.1.3
    container_name: kirocrew
    restart: unless-stopped
    ports:
      - "127.0.0.1:5476:5476"
    volumes:
      - kirocrew-home:/home/kirocrew

volumes:
  kirocrew-home:

దీనిని ప్రారంభించండి, ఆపై ఇమేజ్ దాని స్వంత HEALTHCHECK కోసం ఉపయోగించే health endpointని తనిఖీ చేయండి:

cd /opt/kirocrew
docker compose up -d
docker compose ps
curl -s http://127.0.0.1:5476/api/health

docker compose ps కంటైనర్‌ను ఒక నిమిషం లోపు healthyగా చూపించాలి, మరియు /api/health టోకెన్ లేకుండానే సమాధానం ఇస్తుంది (/api/live మరియు /api/ready కూడా అలాగే చేస్తాయి, అందుకే వీటిని probesగా ఉపయోగించవచ్చు). ఒకవేళ స్థితి starting వద్దే ఉండిపోతే, దేనినీ మార్చకముందే docker logs kirocrewని చదవండి. మొదటిసారి రన్ చేసినప్పుడు embedding model డౌన్‌లోడ్ అవుతుంది, కాబట్టి నెట్‌వర్క్ నెమ్మదిగా ఉంటే మొదటిసారి ప్రారంభం కావడానికి సమయం పడుతుంది.

systemd తో సేవను నిరంతరాయంగా ఉంచడం

restart: unless-stopped, Docker స్వయంగా బూట్ సమయంలో ప్రారంభమైనంత వరకు, క్రాష్ అయిన తర్వాత లేదా రీబూట్ తర్వాత కంటైనర్‌ను తిరిగి తీసుకువస్తుంది. ఒక unit file ఆ డిపెండెన్సీని స్పష్టంగా తెలియజేస్తుంది మరియు బ్యాకప్ చేయడానికి ముందు మొత్తం స్టాక్‌ను ఆపివేయడానికి ఒకే కమాండ్‌ను అందిస్తుంది. బూట్ సమయంలో Docker Compose స్టాక్‌ను ప్రారంభించడం ఈ సాధారణ పద్ధతిని వివరిస్తుంది. KiroCrew శైలిలో ఇది /etc/systemd/system/kirocrew.service లో ఉంది:

[Unit]
Description=KiroCrew gateway
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/kirocrew
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now kirocrew
systemctl status kirocrew

systemctl status kirocrew లో active (exited) అని ఉండాలి, ఇది ఈ యూనిట్‌కు ఆరోగ్యకరమైన ఫలితం. RemainAfterExit=yes తో కూడిన Type=oneshot ఇక్కడ సరైనది, ఎందుకంటే కంటైనర్ ప్రారంభమైన వెంటనే docker compose up -d తిరిగి వస్తుంది: స్టాక్ రన్ అవుతోందనే విషయాన్ని systemd ట్రాక్ చేస్తుంది, ఫోర్‌గ్రౌండ్ ప్రాసెస్‌ను కాదు. దీనికి బదులుగా Type=simple అని రాస్తే, కమాండ్ వెంటనే ఎగ్జిట్ అయినట్లు systemd భావిస్తుంది, సర్వీస్‌ను dead అని గుర్తిస్తుంది, ఆపై మీ Restart= సెట్టింగ్‌ను బట్టి ప్రయత్నాన్ని వదిలేస్తుంది లేదా restart-loop లోకి వెళ్తుంది. నేటివ్ ఇన్‌స్టాలేషన్ కోసం, ఈ ప్రాజెక్ట్ దాని స్వంత సమానమైన kirocrew service install ని అందిస్తుంది, ఇది /etc/systemd/system/kirocrew.service ని రాసి, మీ యూజర్ ద్వారా గేట్‌వేని రన్ చేస్తుంది. ఈ రెండు యూనిట్లను ఒకేసారి రన్ చేయవద్దు. ఈ అంశంపై మరింత విస్తృతమైన సమాచారం VPS పై systemd సర్వీసులు మరియు టైమర్లు లో ఉంది.

మొదటి రన్: సైన్ ఇన్ చేసి డాష్‌బోర్డ్ టోకెన్‌ను పొందడం

కంటైనర్ గేట్‌వేను ప్రారంభిస్తుంది, కానీ ఏజెంట్ రన్‌టైమ్ ఇంకా సైన్ ఇన్ కాలేదు. కంటైనర్ లోపల సైన్ ఇన్ చేయండి:

docker exec -it kirocrew kiro-cli login

ఇది ఒక డివైజ్ కోడ్ మరియు మీరు మీ బ్రౌజర్‌లో ఓపెన్ చేయాల్సిన URLను చూపిస్తుంది. ఆ తర్వాత డాష్‌బోర్డ్ టోకెన్‌ను రూపొందించండి:

docker exec kirocrew kirocrew token --ttl 2h

డాష్‌బోర్డ్ URL http://localhost:5476/?token=<the token>. టోకెన్‌లు ఎక్స్‌పైర్ అవుతాయి: సెషన్‌లు డిఫాల్ట్‌గా ఒక గంట పాటు ఉంటాయి మరియు డాక్యుమెంట్ చేయబడిన గరిష్ట సమయం ఇరవై గంటలు. డాష్‌బోర్డ్ ఖాళీగా లోడ్ అయినా లేదా మిమ్మల్ని వెంటనే బయటకు పంపినా, సాధారణంగా టోకెన్ ఎక్స్‌పైర్ అయిందని అర్థం, కాబట్టి మరొకటి రూపొందించండి. టోకెన్‌ను ఎప్పుడూ టికెట్లలో లేదా చాట్ మెసేజ్‌లలో పేస్ట్ చేయవద్దు, ఎందుకంటే అది ఎవరి దగ్గర ఉంటే వారికి మీ ఏజెంట్ నియంత్రణ లభిస్తుంది.

SSH ద్వారా డాష్‌బోర్డ్‌ను చేరుకోండి, మరియు 5476 పోర్ట్‌ను ఎప్పుడూ పబ్లిక్ చేయకండి

ప్రాజెక్ట్ ఉదాహరణలోని bind అడ్రస్‌ను మళ్ళీ చూడండి: -p 127.0.0.1:5476:5476. కంటైనర్ లోపల గేట్‌వే 0.0.0.0 వద్ద వింటుంది (listen), ఎందుకంటే అది పోర్ట్ మ్యాపింగ్ ద్వారా అందుబాటులో ఉండాలి, కానీ ఆ మ్యాపింగ్ హోస్ట్ యొక్క లూప్‌బ్యాక్ (loopback) కు మాత్రమే పబ్లిష్ అవుతుంది. 127.0.0.1: ప్రిఫిక్స్‌ను తొలగిస్తే, ఆ పోర్ట్‌ను స్కాన్ చేసే ఎవరికైనా గేట్‌వే పబ్లిక్ ఇంటర్నెట్‌లో కనిపిస్తుంది. ఫైర్‌వాల్ రూల్ కూడా మిమ్మల్ని కాపాడలేదు: Docker పోర్ట్‌లను DNAT రూల్స్ రాయడం ద్వారా పబ్లిష్ చేస్తుంది, ఇవి ufw ఫిల్టరింగ్‌కు ముందే అమలు చేయబడతాయి, కాబట్టి ufw deny 5476 పబ్లిష్ చేయబడిన పోర్ట్‌పై ఎటువంటి ప్రభావం చూపదు. Docker ports bypassing ufw ఈ విధానాన్ని వివరంగా వివరిస్తుంది.

దానికి బదులుగా మీ ల్యాప్‌టాప్ నుండి SSH ద్వారా పోర్ట్‌ను ఫార్వర్డ్ చేయండి:

ssh -N -L 5476:127.0.0.1:5476 you@your-server.example.com

దాన్ని రన్ అవుతూనే ఉంచి, స్థానికంగా http://localhost:5476/?token=<the token> ను ఓపెన్ చేయండి. ప్రతి కనెక్షన్‌కు ఈ ఫార్వర్డ్ ఆటోమేటిక్‌గా జరగాలంటే, దాన్ని ~/.ssh/config లో ఉంచండి:

Host your-server.example.com
    LocalForward 5476 127.0.0.1:5476

ఒకవేళ మీ ల్యాప్‌టాప్‌లో 5476 పోర్ట్ ఇప్పటికే వాడుకలో ఉంటే, ఎడమవైపు ఉన్న నంబర్‌ను మాత్రమే మార్చండి: ssh -N -L 45476:127.0.0.1:5476 you@your-server.example.com, ఆపై http://localhost:45476/?token=... కు బ్రౌజ్ చేయండి.

టన్నెల్ ద్వారా ఆశించదగ్గ ఒక డాక్యుమెంట్ చేయబడిన ప్రవర్తన: గేట్‌వే ఫార్వర్డ్ చేయబడిన అభ్యర్థనలను రిమోట్ అభ్యర్థనలుగా గుర్తిస్తుంది, కాబట్టి డాష్‌బోర్డ్‌లోని config-write మరియు secret-reveal ఎండ్‌పాయింట్లు వాటిని తిరస్కరిస్తాయి. SSH ద్వారా సెట్టింగ్స్ మార్పు సేవ్ కాకపోవడం అనేది బగ్ కాదు, ఇది ఆశించదగ్గ ప్రవర్తనే. దానికి బదులుగా హోస్ట్‌పై కాన్ఫిగరేషన్‌ను ఎడిట్ చేయండి:

docker cp kirocrew:/home/kirocrew/.kiro/crew/config.json .
# edit config.json here
docker cp config.json kirocrew:/home/kirocrew/.kiro/crew/config.json
docker exec -u 0 kirocrew chown kirocrew:kirocrew /home/kirocrew/.kiro/crew/config.json
docker restart kirocrew

ఫోన్ ద్వారా యాక్సెస్ చేయడానికి, ప్రాజెక్ట్ Tailscale యొక్క tailscale serve ను సూచిస్తుంది, ఇది డాష్‌బోర్డ్‌ను పబ్లిక్ హోస్ట్‌నేమ్‌లో కాకుండా మీ స్వంత tailnet లోనే ఉంచుతుంది. పబ్లిక్ రివర్స్ ప్రాక్సీ కంటే దీన్నే ఎంచుకోండి. టోకెన్ URL లో ప్రయాణిస్తుంది, మరియు ఆ మార్గంలోని ప్రతి యాక్సెస్ లాగ్‌లో URL నమోదు చేయబడుతుంది.

ఏజెంట్‌కు సాధ్యమైనంత తక్కువ ప్రభావ పరిధిని (blast radius) కేటాయించండి

కంటైనర్ మొదటిసారి ప్రారంభమైనప్పుడు శాండ్‌బాక్స్ మద్దతు కోసం తనిఖీ చేస్తుంది, ఆ ఫలితాన్ని బట్టి ఏజెంట్లు ఏదైనా అమలు చేయగలవా లేదా అనేది నిర్ణయించబడుతుంది. ఒకవేళ నేమ్‌స్పేస్ ఐసోలేషన్ అందుబాటులో ఉంటే, ఏజెంట్ సబ్‌ప్రాసెస్‌లు ఐసోలేట్ చేయబడి రన్ అవుతాయి. ఒకవేళ అది అందుబాటులో లేక, KIROCREW_ALLOW_UNSANDBOXED=1 సెట్ చేయబడకపోతే, అన్‌కన్‌ఫైన్డ్ (unconfined) పద్ధతిలో రన్ చేయడానికి బదులుగా ఎగ్జిక్యూషన్ నిరాకరించబడుతుంది. కాబట్టి, ప్రతి టాస్క్ ఆగిపోయి, గేట్‌వే మాత్రం ఆరోగ్యంగా కనిపిస్తుంటే, సాధారణంగా సమస్య ఇదే అని అర్థం. ఆ మొదటి రన్ నుండి వచ్చిన నిర్ణయం docker logs kirocrew లో ఉంటుంది. ఈ ప్రాజెక్ట్ ఒక seccomp (secure computing mode) ప్రొఫైల్‌ను కూడా విడుదల చేస్తుంది, మీరు దానిని అప్లై చేయవచ్చు:

curl -fsSL https://raw.githubusercontent.com/kirodotdev/KiroCrew/main/docker/seccomp/kirocrew-seccomp.json \
  -o /opt/kirocrew/kirocrew-seccomp.json

    security_opt:
      - seccomp:./kirocrew-seccomp.json

ఒకవేళ మీరు KIROCREW_ALLOW_UNSANDBOXED=1 ని సెట్ చేస్తే, ఏమి మారిందో స్పష్టంగా తెలుసుకోండి: ఇప్పుడు ఏజెంట్‌కు మరియు మీ సర్వర్‌కు మధ్య ఉన్న ఏకైక అడ్డుగోడ ఈ కంటైనర్ మాత్రమే. ఈ ప్రాజెక్ట్ ఇచ్చే హెచ్చరికను పూర్తిగా మళ్ళీ గుర్తుంచుకోవడం అవసరం. మీరు ఏజెంట్‌కు నేరుగా ఇవ్వకూడదనుకునే హోస్ట్ పాత్‌లను మౌంట్ చేయకండి. ఆచరణలో, ఇది Docker సాకెట్‌ను, / యొక్క ఏదైనా బైండ్ మౌంట్‌ను, మరియు మరొక సర్వీస్ డేటాను కలిగి ఉన్న ఏ డైరెక్టరీని అయినా మౌంట్ చేయకుండా నిరోధిస్తుంది.

మిగిలినది కమాండ్లను రన్ చేయడానికి అనుమతించబడిన ప్రతి ఏజెంట్‌కు వర్తించే ఫ్రేమ్. దాని క్రెడెన్షియల్స్‌ను దానికి అవసరమైన ఒక రిపోజిటరీకి లేదా ఒక బకెట్‌కు మాత్రమే పరిమితం చేయండి, ఎప్పుడూ అకౌంట్ మొత్తం హక్కులు ఉన్న పర్సనల్ టోకెన్‌ను వాడకండి. దాని హోమ్ డైరెక్టరీలో మరేమీ లేని ఒక ప్రత్యేక యూజర్‌గా దీనిని రన్ చేయండి, దీని కోసమే VPSపై కనీస అధికారాలు కలిగిన యూజర్లు ఉపయోగపడుతుంది. ఏజెంట్ కోడ్‌ను రాసి, ఆపై ఆ కోడ్‌ను రన్ చేస్తున్నప్పుడు, అది పాడు చేయడానికి అనుమతి ఉన్న ఒక మెషీన్‌ను దానికి ఇవ్వండి: కోడింగ్ ఏజెంట్ల కోసం డిస్పోజబుల్ VM అనేది ఈ compose ఫైల్‌లోని ఏ ఫ్లాగ్ కంటే బలమైన అడ్డుగోడ, ఎందుకంటే మీరు దానిని క్లీన్ చేయడానికి బదులుగా డిలీట్ చేస్తారు. ఇదే ఆలోచన VPSపై OpenClaw ను సురక్షితంగా రన్ చేయడం మరియు VPSపై Hermes ఏజెంట్‌ను self-host చేయడం వంటి వాటికి కూడా వర్తిస్తుంది. టూల్స్ కూడా ప్రభావ పరిధి (blast radius) కిందకే వస్తాయి: ఏజెంట్‌కు వెబ్ సెర్చ్ సౌకర్యం కల్పిస్తే, అది తీసుకునే ప్రతి పేజీ నమ్మదగని ఇన్‌పుట్‌గా మారుతుంది, కాబట్టి మీ సొంత SearXNG ఇన్‌స్టన్స్‌ను దానికి అనుసంధానించడం అనేది ప్లంబింగ్ నిర్ణయంతో పాటు ప్రాంప్ట్ ఇంజెక్షన్ నిర్ణయం కూడా అవుతుంది. షెడ్యూల్ చేసిన పనులు మీరు నిద్రపోతున్నప్పుడు కూడా ఖర్చును పెంచుతాయి, ఎందుకంటే ఇన్ఫరెన్స్ మీ Kiro ప్లాన్‌కు బిల్ అవుతుంది, కాబట్టి రాత్రిపూట చేసే జాబ్‌ను జోడించే ముందు VPSపై AI ఏజెంట్ ఖర్చులను నియంత్రించడం లో వివరించిన పరిమితులను సెట్ చేయండి.

ప్రతి అప్‌గ్రేడ్‌కు ముందు state volume ను బ్యాకప్ చేయండి

ముందుగా అసలైన volume పేరును కనుగొనండి. Compose, ప్రాజెక్ట్ పేరుతో volume లకు ప్రిఫిక్స్‌లను జోడిస్తుంది. ప్రాజెక్ట్ పేరు డిఫాల్ట్‌గా డైరెక్టరీ పేరుగా ఉంటుంది, కాబట్టి /opt/kirocrew/compose.yaml లో kirocrew-home గా ప్రకటించిన volume, kirocrew_kirocrew-home గా సృష్టించబడుతుంది:

docker volume ls

ఏదైనా కాపీ చేసే ముందు gateway ను ఆపివేయండి. memory.db మరియు memory_index.db అనేవి SQLite డేటాబేస్‌లు. డేటాబేస్ వ్రాయబడుతున్న సమయంలో దానిని కాపీ చేస్తే, అసంపూర్తిగా ఉన్న ట్రాన్సాక్షన్ కాపీ అయ్యే అవకాశం ఉంది, ఇది పునరుద్ధరించినప్పుడు ఫైల్ పాడైపోయేలా చేస్తుంది. ప్రాజెక్ట్ యొక్క మైగ్రేషన్ సూచనలు కూడా ఇదే చెబుతున్నాయి: gateway లు ఆగిపోయినప్పుడు మాత్రమే మెమరీని తరలించండి.

sudo systemctl stop kirocrew
docker run --rm -v kirocrew_kirocrew-home:/data:ro -v "$PWD":/backup \
  alpine tar czf /backup/kirocrew-2026-08-06.tgz -C /data .
sudo systemctl start kirocrew

ఆర్కైవ్‌ను బాక్స్ (సర్వర్) నుండి బయటకు కాపీ చేయండి. పునరుద్ధరించడం కూడా ఇదే కమాండ్ ద్వారా జరుగుతుంది, అయితే కంటైనర్‌ను ఆపివేసి, tar czf స్థానంలో tar xzf ను ఉపయోగించాలి:

sudo systemctl stop kirocrew
docker run --rm -v kirocrew_kirocrew-home:/data -v "$PWD":/backup \
  alpine tar xzf /backup/kirocrew-2026-08-06.tgz -C /data
sudo systemctl start kirocrew

కొత్త హోస్ట్‌కు మారడం అనేది ఉన్న చోటే పునరుద్ధరించడం కంటే భిన్నమైన ప్రక్రియ, దీని గురించి ప్రాజెక్ట్ ప్రత్యేకంగా పేర్కొంది. workspace/memory/ కింద ఉన్న చాట్ హిస్టరీ మరియు ప్రాజెక్ట్ నోట్స్, అలాగే రెండు డేటాబేస్ ఫైళ్లు మరియు config.json కొత్త హోస్ట్‌కు బదిలీ అవుతాయి. PID ఫైళ్లు, సెక్యూరిటీ ఈవెంట్ లాగ్ మరియు .env పాత హోస్ట్‌కు సంబంధించినవి, కాబట్టి వాటిని వదిలేయండి మరియు కొత్త బాక్స్‌లో secrets ను మళ్లీ నమోదు చేయండి.

విఫలమైన అప్‌గ్రేడ్‌ను వెనక్కి (roll back) తీసుకోవడం ఎలా

అప్‌గ్రేడ్ ప్రక్రియ చాలా తక్కువ సమయంలో పూర్తవుతుంది, మరియు మీరు ఒక నిర్దిష్ట వెర్షన్‌ను పిన్ (pin) చేశారు కాబట్టి ఇది సురక్షితం. ముందుగా బ్యాకప్ తీసుకోండి, ఆపై tag ను మార్చండి:

sudo systemctl stop kirocrew
# take the backup here, as above
sudo nano /opt/kirocrew/compose.yaml   # set the new image tag
sudo systemctl start kirocrew
docker compose -f /opt/kirocrew/compose.yaml ps
curl -s http://127.0.0.1:5476/api/health

docker compose up -d ఆ image బాక్స్‌లో లేకపోతే దానిని డౌన్‌లోడ్ చేస్తుంది, కాబట్టి tag ను సవరించడమే పూర్తి అప్‌గ్రేడ్ ప్రక్రియ. పాత వెర్షన్ నంబర్‌తో ఇదే క్రమాన్ని అనుసరించడం ద్వారా roll back చేయవచ్చు. వెర్షన్ tags మార్చలేనివి (immutable) కాబట్టి, ఇది మీకు అంతకుముందు ఉన్న ఖచ్చితమైన image ను అందిస్తుంది.

బైనరీ సులభంగా వెనక్కి మళ్లుతుంది. కానీ డేటా స్థితి (state) అలా ఉండకపోవచ్చు. కొత్త gateway, config.json ను తిరిగి రాయవచ్చు లేదా మెమరీ డేటాబేస్‌లను పాత gateway చదవలేని ఆకృతిలోకి మార్చవచ్చు. ఆగస్టు 2026 నాటికి ఎటువంటి downgrade మార్గం డాక్యుమెంట్ చేయబడలేదు. కాబట్టి పాత image ప్రారంభమై వింతగా ప్రవర్తిస్తే, దానిని డీబగ్ చేయడానికి ప్రయత్నించకండి. దానిని ఆపివేసి, అప్‌గ్రేడ్‌కు ముందు మీరు తీసుకున్న బ్యాకప్‌ను restore చేసి, మళ్లీ ప్రారంభించండి. బ్యాకప్‌ను ముందుగా తీసుకోవడానికి గల కారణం ఇదే. అందుకే, ముందుగా అప్‌గ్రేడ్ చేసి తర్వాత బ్యాకప్ తీసుకునే అలవాటు ఇంత కొత్త ప్రాజెక్టులలో విఫలమవుతుంది.

ఇక్కడ నిరూపితం కాని అంశాలు

ఈ సాఫ్ట్‌వేర్ వయస్సు గురించి నిజాయితీగా ఉండండి. ఈ గైడ్ రాసే సమయానికి వెర్షన్ 0.1.3 విడుదలై కొన్ని రోజులే అయింది. దీని release notes లో మైగ్రేషన్ సూచనలకు బదులుగా ఆటోమేటెడ్ changelog లింకులు మాత్రమే ఉన్నాయి, మరియు అప్‌గ్రేడ్‌లకు సంబంధించి ఇప్పటివరకు ఎటువంటి ట్రాక్ రికార్డ్ లేదు. ఈ గైడ్‌లోని ఏదీ దీర్ఘకాలిక ఫలితం కాదు, కాబట్టి మెమరీ పెరుగుదల, డేటాబేస్ పరిమాణం మరియు షెడ్యూలర్ విశ్వసనీయత వంటి అంశాలను మీ సొంత సర్వర్‌లో మీరే స్వయంగా పరీక్షించుకోవాలి, వాటిని ముందే ఊహించుకోకూడదు.

మీరు వీటిపై ఆధారపడే ముందు రెండు ప్రవర్తనలను స్వయంగా పరీక్షించడం మంచిది. మొదటిది, కొత్త వెర్షన్ రాసిన డేటాను పాత వెర్షన్‌కు downgrade చేసినప్పుడు అది చదవగలదా అనేది చూడండి: దీన్ని ఏదైనా సమస్య లేని సమయంలో, వాల్యూమ్ కాపీపై ప్రయత్నించండి, సర్వర్ పనిచేయని సమయంలో (outage) కాదు. రెండవది, షెడ్యూల్ చేసిన జాబ్ నడవాల్సిన సమయంలో Kiro సైన్-ఇన్ గడువు ముగిస్తే గేట్‌వే ఎలా స్పందిస్తుందో చూడండి. ఇవి రెండూ కొత్త ప్రాజెక్ట్‌లలో ఉండే చిన్న చిన్న లోపాలు, వీటిని డెవలపర్లు విడుదలల మధ్యలో నిశ్శబ్దంగా సరిచేస్తుంటారు. వీటిని ఇప్పుడే పరీక్షించుకోవడం సులభం.

FAQ

నా సర్వర్ పబ్లిక్ IPపై KiroCrew డాష్‌బోర్డ్ ఎందుకు తెరవబడటం లేదు?

ఎందుకంటే అందించిన ఉదాహరణలో port ను loopback కు bind చేయడం జరిగింది. -p 127.0.0.1:5476:5476 కంటైనర్ యొక్క port ను హోస్ట్ యొక్క loopback అడ్రస్‌కు మాత్రమే మ్యాప్ చేస్తుంది, ఇది ఉద్దేశపూర్వకంగా చేసిన ఏర్పాటు. దీన్ని యాక్సెస్ చేయడానికి ssh -N -L 5476:127.0.0.1:5476 you@your-server తో SSH ద్వారా port ను ఫార్వర్డ్ చేసి, ఆపై మీ ల్యాప్‌టాప్‌లో http://localhost:5476/?token=<token> ను తెరవండి. దీన్ని పబ్లిక్ ఇంటర్నెట్‌లో అందుబాటులోకి తెచ్చేందుకు 127.0.0.1: ప్రిఫిక్స్‌ను తొలగిస్తే, గేట్‌వే పబ్లిక్ ఇంటర్నెట్‌కు బహిర్గతమవుతుంది. Docker యొక్క published-port DNAT రూల్స్ ufw ఫిల్టర్ల కంటే ముందే అమలు చేయబడతాయి కాబట్టి, కేవలం ఫైర్‌వాల్ రూల్స్ ద్వారా దీన్ని నియంత్రించడం సాధ్యం కాదు.

KiroCrew తన డేటాను ఎక్కడ నిల్వ చేస్తుంది, నేను దేనిని బ్యాకప్ చేయాలి?

అంతా ~/.kiro/crew కింద ఉంటుంది, ఇది కంటైనర్ ఇమేజ్ లోపల /home/kirocrew/.kiro/crew గా ఉంటుంది, మరియు KIROCREW_HOME దీన్ని మారుస్తుంది. గేట్‌వేని ఆపివేసి, మొత్తం డైరెక్టరీని లేదా మొత్తం Docker వాల్యూమ్‌ను బ్యాకప్ చేయండి. memory.db మరియు memory_index.db అనేవి SQLite డేటాబేస్‌లు, కాబట్టి గేట్‌వే డేటాను రాస్తున్నప్పుడు కాపీ తీస్తే అవి అస్థిరంగా (inconsistent) మారవచ్చు. కొత్త హోస్ట్‌కు మారేటప్పుడు, workspace/memory/, రెండు డేటాబేస్ ఫైళ్లు మరియు config.json లను తరలించండి; PID ఫైళ్లు, సెక్యూరిటీ ఈవెంట్ లాగ్ మరియు .env పాత హోస్ట్‌కు సంబంధించినవి.

నేను stable ట్యాగ్‌ని వాడాలా లేదా వెర్షన్ ట్యాగ్‌ని వాడాలా?

వెర్షన్ ట్యాగ్‌ని వాడండి. stable ప్రతి కొత్త రిలీజ్ విడుదలైనప్పుడు మారుతూ ఉంటుంది, కాబట్టి మీరు తదుపరిసారి pull చేసినప్పుడు మీరు రన్ చేస్తున్న వెర్షన్ తెలియకుండానే మారిపోవచ్చు, మరియు ఆ ట్యాగ్ ద్వారా మీరు ఏ వెర్షన్ వాడుతున్నారో కూడా తెలియదు. 0.1.3 వంటి వెర్షన్ ట్యాగ్‌లు మార్పులేనివి (immutable), రోల్‌బ్యాక్ (rollback) చేయడానికి ఇవే కీలకం: మీరు పాత నంబర్‌ను తిరిగి సెట్ చేస్తే, అదే ఇమేజ్ మళ్ళీ వస్తుంది. 6 ఆగస్టు 2026 నాటికి సరికొత్త రిలీజ్ 0.1.3.

నా ఏజెంట్ ఎటువంటి కమాండ్లను ఎందుకు రన్ చేయడం లేదు?

కంటైనర్ మొదటిసారి ప్రారంభమైనప్పుడు sandbox సపోర్ట్ కోసం తనిఖీ చేస్తుంది. ఒకవేళ అది ఏజెంట్ సబ్‌ప్రాసెస్‌లను ఐసోలేట్ చేయలేకపోయినా మరియు KIROCREW_ALLOW_UNSANDBOXED=1 సెట్ చేయబడకపోయినా, అది వాటిని అన్‌కన్‌ఫైన్డ్ (unconfined) పద్ధతిలో రన్ చేయకుండా నిరాకరిస్తుంది. దీనివల్ల గేట్‌వే ఆరోగ్యంగా ఉన్నట్లు కనిపిస్తుంది కానీ ఏ టాస్క్ పూర్తి కాదు. docker logs kirocrew ఆ మొదటి రన్ నుండి sandbox నిర్ణయాన్ని చూపుతుంది. ఈ వేరియబుల్‌ను సెట్ చేయడం ద్వారా ఏజెంట్‌కు మరియు హోస్ట్‌కు మధ్య కంటైనర్ మాత్రమే సరిహద్దుగా ఉంటుంది, కాబట్టి మీరు దీన్ని సెట్ చేస్తే, ఏజెంట్‌కు నేరుగా ఇవ్వకూడని దేనినీ మౌంట్ చేయకండి.

KiroCrewని self-host చేయడానికి నాకు Kiro అకౌంట్ అవసరమా?

అవును, ఆగస్టు 2026 నాటికి ఇది అవసరం. KiroCrew అనేది Apache 2.0 లైసెన్స్ కింద ఉచిత సాఫ్ట్‌వేర్, కానీ ఇది kiro-cli ద్వారా పనిచేస్తుంది, దీనికి ఒకసారి సైన్-ఇన్ అవసరం, మరియు ఏజెంట్ ఇన్ఫరెన్స్ (inference) కోసం Kiro ప్లాన్ ద్వారా బిల్లింగ్ జరుగుతుంది. కంటైనర్‌లో, docker exec -it kirocrew kiro-cli login రన్ చేసి మీ బ్రౌజర్‌లో డివైజ్ కోడ్‌ను ఆమోదించండి. ఆ సైన్-ఇన్ పూర్తయ్యే వరకు, గేట్‌వే ప్రారంభమవుతుంది మరియు డాష్‌బోర్డ్ లోడ్ అవుతుంది, కానీ ఏజెంట్‌కు కమ్యూనికేట్ చేయడానికి ఎటువంటి మోడల్ అందుబాటులో ఉండదు.