How to Self-Host KiroCrew on VPS 24/7
Learn how to run KiroCrew as a pinned Docker container with systemd, SSH, backups and rollback, so memory and scheduled jobs survive VPS reboots.
Kialaman self-host KiroCrew for VPS instead of laptop
Self-hosting KiroCrew only dey useful for machine wey no dey sleep, so VPS na the correct place for am, no be laptop. KiroCrew dey keep session history, semantic memory, scheduled jobs and approval queue for disk, and e dey load all of dem again whenever process restart. None of dis one help if process no dey run by 03:00 when scheduled job suppose run, and closed laptop no dey run am.
KiroCrew na open source agent workspace from Kiro team, under Apache 2.0 license, with 0.1.0 released on 22 July 2026. One process, wey dem call gateway, dey own the state and dey serve web dashboard for port 5476. You fit reach gateway from dashboard, from kirocrew CLI, or from chat channel like Slack. Gateway na the only thing wey you dey self-host, so dis guide na about keeping am alive, keeping am away from public internet, and restoring am after bad upgrade.
Get two things wey you need know before you start. Since 0.11.0, new KiroCrew installs wey no get saved harness choice dey default to KAS without needing kiro-cli; existing explicit Kiro CLI selections dey preserved. Inference for Kiro backends dey use your Kiro plan, so as of 1 November 2026, dis default setup no dey offline. The project still young and e dey change fast: stable releases move from 0.1.3 on 5 August 2026 to 0.10.0 on 25 October 2026, with 0.8.0 on 9 October and 0.9.0 on 16 October between dem, and 0.11.0 release candidate don already come out as pre-release on 25 October. Assume say you go need roll back at some point, and install am in a way wey go allow you do am. If you never run agent for server before, run coding agent for VPS explain the basic rules wey dis guide dey build on. If agent side still new to you pass server side, learn wetin agent loop, im tools and im memory really be first; e go make the choices below look like decisions instead of incantations.
KiroCrew need wetin, and where e keep im state
Native install need Python 3.12 or newer. E also need Node.js 22.12.0 or newer if you build the dashboard from source. The project recommend Node 24 LTS. Kiro CLI backend need kiro-cli. Authenticate am with kiro-cli login or use an API key for automated use. Since 0.10.0, the built-in KAS engine fit run without kiro-cli installed. 0.11.0 make am the default for new installs when no harness choice dey saved. Container install no need any of these things for the host. E need Docker. Na the main reason to prefer am.
State dey inside ~/.kiro/crew. The KIROCREW_HOME environment variable fit move am go another place. These things dey inside:
config.json: gateway settings and chat channel credentials..env: secrets.workspace/memory/: preferences, project notes and chat history.memory.dbandmemory_index.db: semantic and full-text indexes.models/: embedding model, wey download for first run.security_events.jsonl: security event log.
That directory na the install. Copy am go new VPS and you don move your agent. Na why the backup section below matter pass the install section.
Plan for disk instead of RAM. The gateway na Python process. Wetin really load the machine na whatever the agent dey run, whether na build or test suite. The state directory go grow as chat history increase. The embedding model go arrive for first start. So measure am for your own machine with du -sh ~/.kiro/crew after some weeks. No rely on any figure wey dem publish during the first months of a project. Compare this with runtime wey give every worker im own container and browser. For that setup, self-hosting OpenBot AI coworkers make RAM the first sizing concern before disk.
Tori which of the four install paths you suppose use
The project get four options: desktop app, one-line wheel, source, and Docker. The one-line installer go fetch a wheel and create a kirocrew launcher. If the launcher directory no dey for your PATH, e go print instructions for how to add am:
curl -fsSL https://download.crew.kiro.dev/cli.sh | shE dey accept a channel flag and a version flag:
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.8.0The container image dey published for ghcr.io/kirodotdev/kirocrew, for linux/amd64 and linux/arm64 under every tag. The source build na git clone plus make build, and e dey for people wey dey change the code, not people wey just wan run am.
Use the container. Native source install go put Python packages and Node for the same host wey dey run your other services, plus kiro-cli when you dey use the Kiro CLI backend. So if upgrade get problem, you go need sort out the changes by hand. The container keep the runtime inside one image and the state inside one volume. This make rollback simply changing the tag and restarting.
Pin image to release tag, no be stable
The project example itself dey use stable tag:
docker run -d --name kirocrew \
-p 127.0.0.1:5476:5476 \
-v kirocrew-home:/home/kirocrew \
ghcr.io/kirodotdev/kirocrew:stablestable na moving tag, and latest too, wey dey point to the same release. E dey point to whichever stable release be the newest at that time, so the next pull fit change the version wey you dey run without you choosing am. The tag no dey record which version e be. Version tags no dey change, so pin one. The newest stable release as of 1 November 2026 na 0.11.1, wey dem publish on 31 October 2026. Na hot patch for memory integrity and KAS fixes inside 0.11.0. The 0.8.0 example below dey use Kiro CLI. insider and nightly tags dey available too; nightly dey follow builds from main.
Write /opt/kirocrew/compose.yaml:
services:
kirocrew:
image: ghcr.io/kirodotdev/kirocrew:0.8.0
container_name: kirocrew
restart: unless-stopped
ports:
- "127.0.0.1:5476:5476"
volumes:
- kirocrew-home:/home/kirocrew
volumes:
kirocrew-home:Start am, then check the health endpoint wey the image also dey use for its own HEALTHCHECK:
cd /opt/kirocrew
docker compose up -d
docker compose ps
curl -s http://127.0.0.1:5476/api/healthdocker compose ps suppose report say the container healthy within about one minute, and /api/health dey answer without token. /api/live and /api/ready dey do the same thing, and na wetin make dem useful as probes. If the state remain starting, read docker logs kirocrew before you change anything. The first run dey download the embedding model for background. Until e arrive, memory search dey use keyword matching.
Make e continue with systemd
restart: unless-stopped dey bring the container back after crash and reboot, as long as Docker itself dey start when system boot. Unit file dey make this dependency clear and give you one command wey go stop the whole stack before backup. Start Docker Compose stack when system boot explain the general pattern. This na how KiroCrew take arrange am, for /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.targetsudo systemctl daemon-reload
sudo systemctl enable --now kirocrew
systemctl status kirocrewsystemctl status kirocrew suppose read active (exited). Na the healthy result for this unit. Type=oneshot with RemainAfterExit=yes correct here because docker compose up -d dey return immediately after e start the container: systemd dey track say the stack don come up, no be foreground process. If you write Type=simple instead, systemd go see say the command exit immediately, mark the service as dead, then either give up or enter restart loop, depending on your Restart= setting. For native install, the project ship its own equivalent, kirocrew service install, wey write /etc/systemd/system/kirocrew.service and run the gateway as your user. No run both units. You fit read the broader explanation for systemd services and timers on a VPS. Unit wey fail to come back go remain silent unless you make am report the problem. So add an OnFailure= handler wey send alert go your own ntfy server, and you go hear say the gateway dey down from your phone, instead of finding out through scheduled job wey never run.
First run: sign in and collect dashboard token
Container go start gateway, but default Kiro CLI runtime for the pinned 0.8.0 image still need authentication. Sign in inside container, or pass KIRO_API_KEY through container environment for automated use:
docker exec -it kirocrew kiro-cli loginThat one go print device code and URL wey you go open for your own browser. Then create dashboard token:
docker exec kirocrew kirocrew token --ttl 2hDashboard URL na http://localhost:5476/?token=<the token>. Tokens dey expire: you must open the printed link within five minutes after you create am, and this command dey request access cookie wey last two hours. Documented maximum na twenty hours. Browser go also receive refresh cookie wey get 30-day sliding idle window, so active session fit renew without another link. If dashboard load blank or e send you straight back outside, token don usually expire. Create another one and open am immediately. Never paste token for ticket or chat message, because anybody wey hold am get control of your agent.
Reach dashboard through SSH, and make sure you never publish port 5476
Look again at the bind address for the project example: -p 127.0.0.1:5476:5476. Inside the container, gateway dey listen on 0.0.0.0, because port mapping need reach am. But the mapping publish am only to loopback for the host. If you delete the 127.0.0.1: prefix, gateway go dey available on public internet for anybody wey scan that port. ufw rule no go save you too: Docker publish ports by writing DNAT rules wey route traffic before ufw rules apply, so ufw deny 5476 no dey affect published port. With Docker default iptables backend, Docker own method na to put filtering rules inside DOCKER-USER chain. E work, but those rules see container internal address and port unless you match with conntrack extension. So loopback bind remain the simpler control and the one wey hard to configure wrong. Docker nftables backend instead dey use separate nftables tables and base chains for custom filtering. How Docker ports dey bypass ufw explain that mechanism step by step.
Forward the port through SSH from your laptop instead:
ssh -N -L 5476:127.0.0.1:5476 you@your-server.example.comLeave am running, then open http://localhost:5476/?token=<the token> locally. To make the forward happen automatically for every connection, put am inside ~/.ssh/config:
Host your-server.example.com
LocalForward 5476 127.0.0.1:5476If port 5476 already dey use on your laptop, change only the number for the left side: ssh -N -L 45476:127.0.0.1:5476 you@your-server.example.com. Then open http://localhost:45476/?token=.... You no need extra loopback-port setting or container recreation: the loopback Origin match the request own Host, so CSRF check accept am. You go dey stack forwards like this once another agent share the box, because self-hosting open-kritt for security scanning put another loopback-only dashboard for the same server, on port 5173.
Two documented behaviours determine the settings wey you fit change from dashboard. First, gateway treat any request wey carry forwarding headers (Forwarded, X-Forwarded-* or X-Real-IP) as remote. Its config-write and secret-reveal endpoints reject those requests. Reverse proxy add those headers; plain ssh -L forward add none, so gateway see am as local and no reject am for that reason. Second, inside the container image, channel-credential pages and secret-revealing views dey read-only for any browser wey no be direct-local. The image no come with text editor. If channel credential no save from dashboard, na this restriction cause am, no be bug. Edit the config on the host instead:
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 kirocrewFor phone access, the project recommend Tailscale tailscale serve. E keep dashboard inside your own tailnet instead of exposing am on public hostname. Prefer this over public reverse proxy. The token dey inside URL, and URL dey written into every access log along the path. This rule concern wetin dey behind the port, not the port itself: something like Halcyon, wey rebuild Jellyfin library into browsable 90s video store dey made for other people to open, so e fit be good candidate for reverse proxy. But gateway wey fit run commands on your server no be.
Give the agent the smallest blast radius you fit
The container dey check for sandbox support the first time e start, and the result decide whether agents fit execute anything. If namespace isolation dey available, agent subprocesses go run isolated. If e no dey available and KIROCREW_ALLOW_UNSANDBOXED=1 no set, execution go refuse instead of running unconfined. So, if gateway dey look healthy but every task dey stall, na usually this be the cause. The decision dey inside docker logs kirocrew from that first run. The project also publishes a seccomp (secure computing mode) profile wey you fit apply:
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.jsonFor host wey AppArmor dey enabled, the project's Docker guide talk say the seccomp profile na only half of the change, because Docker also dey attach its docker-default AppArmor profile, and e pair the profile with apparmor=unconfined. That option only remove AppArmor's per-container rules; the seccomp profile, the dropped capabilities, and the non-root user still dey apply.
If you set KIROCREW_ALLOW_UNSANDBOXED=1, understand clearly wetin change: the container na now the only boundary between the agent and your server. The project's warning worth repeating complete. No mount host paths wey you no go hand directly to the agent. For practice, that means no Docker socket, no bind mount of /, and no directory wey hold another service's data.
The rest na the security setup wey apply to every agent wey you allow to run commands. Limit its credentials to the one repository or the one bucket wey e need. Never use personal token wey get account-wide rights. Run am as dedicated user wey home directory no hold anything else. Na this least privilege users on a VPS dey help you do. When agent write code and then run that code, give am machine wey e fit break: a disposable VM for coding agents na stronger boundary than any flag for this compose file, because you fit delete am instead of cleaning am. The same thinking guide running OpenClaw safely on a VPS and self-hosting the Hermes agent on a VPS. Tools also count as blast radius. If you give the agent web search, every page e fetch become untrusted input. So pointing it at your own SearXNG instance na prompt injection decision as much as na plumbing decision. Scheduled work fit also spend money while you dey sleep, because inference on the Kiro backends dey use your Kiro plan. So set the limits wey controlling what an AI agent costs on a VPS describe before you add nightly job.
Back up state volume before every upgrade
First find the real volume name. Compose dey add project name before named volumes. By default, e dey use directory name. So the volume wey you declare as kirocrew-home for /opt/kirocrew/compose.yaml go create as kirocrew_kirocrew-home:
docker volume lsStop the gateway before you copy anything. memory.db and memory_index.db na SQLite databases. If you copy database while e dey write, you fit capture transaction wey never finish. When you restore am, the file fit corrupt. The project migration instructions talk the same thing: only move memory after you stop the gateways. This stop-first rule no be only for KiroCrew. If photo server dey share the same box, the PhotoPrism and Immich comparison get the exact backup commands wey each one need.
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 kirocrewCopy the archive comot from the box. To restore am, use the same command while the container dey stopped, and put tar xzf where tar czf dey:
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 kirocrewMoving go new host no be the same work as restoring for the same host. The project instructions clear about this. Chat history and project notes inside workspace/memory/ go carry over. The two database files and config.json go carry over too. PID files, security event log, and .env dey tied to the old host, so leave dem there and enter the secrets again for the new box.
Sabi how you go roll back bad upgrade
Upgrade dey short, and e safe only because you pin one version. First take backup, then change the 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/healthdocker compose up -d go pull the image if e no dey already for the box, so na the tag edit be the complete upgrade. Rollback na the same sequence with the old number, and e go give you the exact image wey you get before, because version tags no dey change.
The binary go roll back cleanly. Na the state fit get problem. Newer gateway fit rewrite config.json or migrate the memory databases enter format wey older gateway no fit read, and no documented downgrade path for state dey available as of 12 October 2026. The install guide talk one case clearly: data wey move comot from legacy ~/.kirocrew home no get rollback, and release wey older than ~/.kiro/crew go start empty. So if the older image start and then dey behave strangely, no debug am. Stop am, restore the backup wey you take before the upgrade, then start again. Na this be the whole reason backup dey come first, and na why the habit of upgrading now and backing up later dey fail for project wey still young.
Wetin no dey proven here
Make we honest about how old this software be. Version 0.1.3 release on 5 August 2026, and by 12 October 2026 the stable line don reach 0.8.0. Most release notes still be automated changelogs; the 0.8.0 notes na hand-written, but dem no get migration section, and the public release history na about three months long. Nothing for this guide be long-run result, so measure memory growth, database size, and scheduler reliability for your own box instead of assuming say dem go behave one particular way.
Two behaviours dey worth testing by yourself before you depend on dem. First, check whether downgrade fit read state wey newer version write: try am on copy of the volume when e no matter, no be during outage. Second, check wetin the gateway go do when Kiro sign-in expire while scheduled job dey due. Both na the kind rough edge wey young project dey quietly fix between releases, and both cheap to check now.
FAQ
Why KiroCrew dashboard no dey open for my server public IP?
Because the published example bind the port to loopback. -p 127.0.0.1:5476:5476 maps the container port to the host loopback address only, and na deliberate. Forward the port over SSH with ssh -N -L 5476:127.0.0.1:5476 you@your-server, then open http://localhost:5476/?token=<token> for your laptop. If you remove the 127.0.0.1: prefix, the gateway go become reachable from public internet. ufw no go contain am because Docker published-port DNAT rules route the traffic before ufw rules apply. Use Docker DOCKER-USER chain with its iptables backend, or separate nftables base chains with its nftables backend, to filter published ports. Keeping the loopback bind na simpler.
Where KiroCrew dey store its data, and wetin I suppose back up?
Everything dey under ~/.kiro/crew. Inside the container image, this na /home/kirocrew/.kiro/crew, and KIROCREW_HOME relocate am. Back up the whole directory, or the whole Docker volume, after you stop the gateway. memory.db and memory_index.db na SQLite databases, so copy wey you take while the gateway dey write fit get inconsistent data. When you move to new host, workspace/memory/, the two database files, and config.json go move across. PID files, the security event log, and .env belong to the old host.
I suppose use stable tag or version tag?
Use version tag. stable dey change whenever new release come out. So the version wey you dey run fit change under you for the next pull, and the tag itself no tell you wetin dey run. Version tags like 0.8.0 no dey change. Na this make rollback work: put back the old number and you go get the same image. As of 1 November 2026, the newest stable release na 0.11.1.
Why my agent dey refuse to run any commands?
The container dey check for sandbox support the first time e start. If e no fit isolate agent subprocesses and KIROCREW_ALLOW_UNSANDBOXED=1 no set, e refuse to execute dem instead of running dem without isolation. Because of this, the gateway go look healthy while every task dey stall. docker logs kirocrew show the sandbox decision from that first run. If you set the variable, the container become the only boundary between the agent and the host. So mount only files wey you go give the agent directly.
I need Kiro account to self-host KiroCrew?
For Kiro backends, yes, as of 1 November 2026. KiroCrew na free software under Apache 2.0, but inference for those backends dey use your Kiro plan. The pinned 0.8.0 container dey use Kiro CLI. Run docker exec -it kirocrew kiro-cli login and approve the device code for your browser, or pass KIRO_API_KEY through the container environment for automated use. Until you configure authentication, the gateway go start and the dashboard go load, but its default harness no get model to talk to. Since 0.10.0, built-in KAS engine dey available too, and e no need kiro-cli installed. 0.11.0 make KAS the default for new installs wey no get saved harness choice, while explicit Kiro CLI selections still dey work. KAS dey use Crew own sign-in instead of kiro-cli login. The project custom backend guide let a claude harness send the main model turns to any Anthropic-compatible endpoint wey you choose. But kiro-cli sign-in still dey required for Kiro-specific features.