I Tried Running the Official KiroCrew Docker Image on EC2 and Connecting via Tailscale

I Tried Running the Official KiroCrew Docker Image on EC2 and Connecting via Tailscale

I tried running KiroCrew, previously installed directly on EC2, in a Docker container as an isolation boundary, accessible from within the tailnet via Tailscale Serve. Also covers SSM setup, named volumes, and access logs.
2026.08.06

This page has been translated by machine translation. View original

Introduction

Last time, I installed KiroCrew directly on EC2 and accessed it through an SSH tunnel. This time, I ran the official KiroCrew Docker image as a container and verified a setup where it is accessed from within the tailnet via Tailscale Serve.

https://dev.classmethod.jp/articles/kiro-crew-remote-on-ec2/

Tailscale Serve is a feature that exposes a local service to devices within the tailnet. I restricted Docker's port publishing to the loopback address and went all the way to actually connecting from another device in the tailnet. I also looked at the configuration of the named volume that retains sessions and settings, as well as what gets recorded in the access log.

https://tailscale.com/docs/features/tailscale-serve

Verification Details

Verification Environment

Item Configuration
Infrastructure Amazon EC2 built with CloudFormation
EC2 t4g.medium / arm64 / Amazon Linux 2023 / ap-northeast-1
Software Docker 25.0.16 / Compose v5.4.0 / Tailscale 1.102.2 / KiroCrew 0.1.3
Storage named volume (/home/kirocrew)
KiroCrew ghcr.io/kirodotdev/kirocrew:stable (started with Docker Compose)
Access path Access within the tailnet via Tailscale Serve

The EC2 instance, VPC, and security group were created with a CloudFormation template, and connections to the instance are done through SSM Session Manager.

Isolating KiroCrew in a Docker Container

KiroCrew is started with Docker Compose using /opt/kirocrew/compose.yaml. The port is published only to the loopback address. Only Tailscale Serve is responsible for exposing it to the tailnet.

services:
  kirocrew:
    image: ghcr.io/kirodotdev/kirocrew:stable
    ports:
      - "127.0.0.1:5478:5476"
    environment:
      - KIROCREW_ALLOW_UNSANDBOXED=1

When I checked the port publishing state after startup, it was bound only to the loopback as intended.

127.0.0.1:5478->5476/tcp

KIROCREW_ALLOW_UNSANDBOXED=1 is set as a prerequisite of this setup, in which the isolation boundary is placed at the Docker container; it does not guarantee the safety of KiroCrew in general.

Performing Initial Setup via SSM

The initial setup includes Tailscale authentication, Kiro CLI device flow authentication, kirocrew setup, and Tailscale Serve configuration. All of these involve interactive operations such as displaying an authentication URL and entering a code, so I did not automate this initial setup and instead performed it as terminal operations via SSM Session Manager.

aws ssm start-session --target "<INSTANCE_ID>"
cd /opt/kirocrew

# Tailscale authentication (open the displayed URL in a browser and approve)
sudo tailscale up

# Initial setup of Kiro CLI and KiroCrew inside the container
sudo docker compose exec kirocrew kiro-cli login --use-device-flow
sudo docker compose exec kirocrew kirocrew setup

Specify the port published on the loopback as the forwarding destination of Tailscale Serve.

sudo tailscale serve --bg --yes "http://127.0.0.1:5478"
sudo tailscale serve status
https://<HOSTNAME>.<TAILNET_NAME>.ts.net (tailnet only)
|-- / proxy http://127.0.0.1:5478

tailnet only is a setting that limits the exposure scope to within the tailnet. funnel is not used in this verification.

To use the Serve URL in subsequent settings, obtain it from the output of tailscale serve status.

SERVE_URL="$(sudo tailscale serve status | awk '$1 ~ /^https:\/\// {print $1; exit}')"
case "$SERVE_URL" in
  https://*) echo "Serve URL: $SERVE_URL" ;;
  *) echo "ERROR: Tailscale Serve URL not found" >&2; exit 1 ;;
esac

Register the obtained Serve URL in KiroCrew and restart it.

sudo docker compose exec -T kirocrew kirocrew config set \
  dashboard.url "$SERVE_URL"

sudo docker compose restart kirocrew
sudo docker compose exec -T kirocrew kirocrew config get dashboard.url
sudo docker compose ps
curl --fail --silent http://127.0.0.1:5478/api/health

The configuration value, container state, and local health response were all as expected.

Connecting via Tailscale Serve

From another device already connected to Tailscale, I sent a health check to the URL assigned by Serve.

curl "https://<HOSTNAME>.<TAILNET_NAME>.ts.net/api/health"
{"ok": true}

Temporarily Saving the Dashboard Access Token

To open the dashboard, issue a dashboard token inside the container. The token is not output to chat, logs, or Git, and is saved to a temporary file local to the EC2 instance.

cd /opt/kirocrew
SERVE_URL="$(sudo tailscale serve status | awk '$1 ~ /^https:\/\// {print $1; exit}')"
TOKEN=$(sudo docker compose exec -T kirocrew kirocrew token --ttl 2h)
sudo install -m 600 /dev/null /run/kirocrew-dashboard-token
printf '%s\n' "$TOKEN" | sudo tee /run/kirocrew-dashboard-token > /dev/null
echo "Token saved to /run/kirocrew-dashboard-token (mode 600)"
echo "URL pattern: ${SERVE_URL}?token=<token>"

When checking the saved content, display it with the token and part of the hostname masked. This lets you check the token file contents, permissions, and the dashboard connection URL without revealing the actual values.

TOKEN_FROM_FILE="$(sudo cat /run/kirocrew-dashboard-token)"
MASKED_TOKEN="$(printf '%s' "$TOKEN_FROM_FILE" | sed -E 's/^(.{4}).*(.{4})$/\1...\2/')"
SERVE_HOST="${SERVE_URL#https://}"
MASKED_HOST="$(printf '%s' "$SERVE_HOST" | sed -E 's/^(.{4}).*(.{4})$/\1...\2/')"
printf 'Token file content (masked): %s\n' "$MASKED_TOKEN"
printf 'Token file mode: %s\n' "$(sudo stat -c '%a' /run/kirocrew-dashboard-token)"
printf 'Dashboard URL (masked): https://%s?token=%s\n' "$MASKED_HOST" "$MASKED_TOKEN"

Browser Access

Open the following URL in the browser of a device connected to the tailnet. For the token in the URL, use the value temporarily saved in /run/kirocrew-dashboard-token.

https://<HOSTNAME>.<TAILNET_NAME>.ts.net?token=<token>

Once you have finished accessing from the browser, delete the temporary file on the EC2 instance.

sudo rm -f /run/kirocrew-dashboard-token

Persisting Sessions and Settings

Kiro CLI credentials and KiroCrew settings are written under /home/kirocrew. By mounting /home/kirocrew as a named volume, the container's write destination is consolidated into one place.

services:
  kirocrew:
    volumes:
      - kirocrew-home:/home/kirocrew

volumes:
  kirocrew-home:

access.log is also written by KiroCrew to the same directory. For the log-related settings (mounting PYTHONPATH and sitecustomize.py), see the compose.yaml in the appendix. After accessing from the browser, let's look at the permissions and the most recent records.

cd /opt/kirocrew
sudo docker compose exec -T kirocrew stat -c '%a %n' /home/kirocrew/access.log
sudo docker compose exec -T kirocrew sh -c 'tail -n 50 /home/kirocrew/access.log'

Here is an excerpt of the actual output.

600 /home/kirocrew/access.log
2026-08-06T02:34:55+0000 INFO aiohttp.access: http_request method=POST path=/api/chat status=200 duration_ms=3.4
2026-08-06T02:35:15+0000 INFO aiohttp.access: http_request method=GET path=/api/health status=200 duration_ms=0.5

The dashboard token is passed in the query string, but it was not left in access.log. In this verification, a custom access logger (sitecustomize.py in the appendix) was loaded via PYTHONPATH, and as a result the recorded items were the four fields method, path, status, and duration_ms. The file permission is 600.

Summary

By making the Docker container the isolation boundary and connecting into the tailnet with Tailscale Serve, you can access KiroCrew on EC2 through a path that does not depend on an SSH tunnel. If you want to use the same KiroCrew from multiple devices via a tunnel whose exposure is limited to within the tailnet, give this setup a try.


Appendix: Files for Reproduction

This section collects the files for reproducing the setup used in the main text. The template and scripts are the actual files used during verification. Secrets such as authentication URLs, device codes, authkeys, and dashboard tokens are not included.

CloudFormation Template

This is the full text of templates/kirocrew-ec2.yaml.

CloudFormation template (full text)
AWSTemplateFormatVersion: "2010-09-09"
Description: >
  Kiro Crew EC2 (ARM64/t4g.medium/AL2023) in ap-northeast-1.
  Tailscale + Docker + KiroCrew + KiroCLI via UserData.
  SSM-only management. No inbound ports. IMDSv2 required.
  Self-contained: VPC, Subnet, IGW, RouteTable, SG, IAM Role/Profile, EC2.

# ====================================================================
# Parameters
# ====================================================================
Parameters:
  InstanceType:
    Type: String
    Default: t4g.medium
    AllowedValues: [t4g.small, t4g.medium, t4g.large]
    Description: EC2 instance type (ARM64 Graviton2)

  AmiId:
    Type: AWS::SSM::Parameter::Value<AWS::EC2::Image::Id>
    Default: /aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-arm64
    Description: Amazon Linux 2023 ARM64 AMI (SSM Parameter)

  RootVolumeSize:
    Type: Number
    Default: 20
    MinValue: 20
    MaxValue: 100
    Description: Root EBS volume size in GiB

  ProjectName:
    Type: String
    Default: kirocrew-cfn
    Description: Project name used for resource naming and tags

  DeployDate:
    Type: String
    Default: "20260806"
    Description: Deployment date suffix (YYYYMMDD) for resource naming

# ====================================================================
# Resources
# ====================================================================
Resources:

  # ------------------------------------------------------------------
  # VPC & Network
  # ------------------------------------------------------------------
  KiroCrewVPC:
    Type: AWS::EC2::VPC
    Properties:
      CidrBlock: 10.0.0.0/24
      EnableDnsSupport: true
      EnableDnsHostnames: true
      Tags:
        - Key: Name
          Value: !Sub "${ProjectName}-vpc-${DeployDate}"
        - Key: Project
          Value: !Ref ProjectName
        - Key: ManagedBy
          Value: CloudFormation

  KiroCrewInternetGateway:
    Type: AWS::EC2::InternetGateway
    Properties:
      Tags:
        - Key: Name
          Value: !Sub "${ProjectName}-igw-${DeployDate}"
        - Key: Project
          Value: !Ref ProjectName

  KiroCrewVPCGatewayAttachment:
    Type: AWS::EC2::VPCGatewayAttachment
    Properties:
      VpcId: !Ref KiroCrewVPC
      InternetGatewayId: !Ref KiroCrewInternetGateway

  KiroCrewSubnet:
    Type: AWS::EC2::Subnet
    Properties:
      VpcId: !Ref KiroCrewVPC
      CidrBlock: 10.0.0.0/24
      AvailabilityZone: ap-northeast-1a
      MapPublicIpOnLaunch: true
      Tags:
        - Key: Name
          Value: !Sub "${ProjectName}-subnet-${DeployDate}"
        - Key: Project
          Value: !Ref ProjectName

  KiroCrewRouteTable:
    Type: AWS::EC2::RouteTable
    Properties:
      VpcId: !Ref KiroCrewVPC
      Tags:
        - Key: Name
          Value: !Sub "${ProjectName}-rtb-${DeployDate}"
        - Key: Project
          Value: !Ref ProjectName

  KiroCrewDefaultRoute:
    Type: AWS::EC2::Route
    DependsOn: KiroCrewVPCGatewayAttachment
    Properties:
      RouteTableId: !Ref KiroCrewRouteTable
      DestinationCidrBlock: 0.0.0.0/0
      GatewayId: !Ref KiroCrewInternetGateway

  KiroCrewSubnetRouteTableAssociation:
    Type: AWS::EC2::SubnetRouteTableAssociation
    Properties:
      SubnetId: !Ref KiroCrewSubnet
      RouteTableId: !Ref KiroCrewRouteTable

  # ------------------------------------------------------------------
  # Security Group: inbound完全クローズ, outboundはTailscale/Docker/SSM用HTTPS
  # ------------------------------------------------------------------
  KiroCrewSecurityGroup:
    Type: AWS::EC2::SecurityGroup
    Properties:
      GroupName: !Sub "${ProjectName}-sg-${DeployDate}"
      GroupDescription: "Kiro Crew EC2: No inbound. Outbound HTTPS SSM Docker Tailscale"
      VpcId: !Ref KiroCrewVPC
      # Inbound: 完全クローズ (SSMはポート不要)
      SecurityGroupIngress: []
      # Outbound: HTTPS + Tailscale UDP
      SecurityGroupEgress:
        - IpProtocol: tcp
          FromPort: 443
          ToPort: 443
          CidrIp: 0.0.0.0/0
          Description: HTTPS for SSM endpoints, Docker pull, Tailscale control
        - IpProtocol: tcp
          FromPort: 80
          ToPort: 80
          CidrIp: 0.0.0.0/0
          Description: HTTP for package mirrors (dnf)
        - IpProtocol: udp
          FromPort: 41641
          ToPort: 41641
          CidrIp: 0.0.0.0/0
          Description: Tailscale WireGuard UDP
        - IpProtocol: udp
          FromPort: 3478
          ToPort: 3478
          CidrIp: 0.0.0.0/0
          Description: Tailscale DERP/STUN
      Tags:
        - Key: Name
          Value: !Sub "${ProjectName}-sg-${DeployDate}"
        - Key: Project
          Value: !Ref ProjectName
        - Key: ManagedBy
          Value: CloudFormation

  # ------------------------------------------------------------------
  # IAM Role: SSM Core + ECR (KiroCrew image pull)
  # ------------------------------------------------------------------
  KiroCrewEC2Role:
    Type: AWS::IAM::Role
    Properties:
      RoleName: !Sub "${ProjectName}-ec2-role-${DeployDate}"
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              Service: ec2.amazonaws.com
            Action: sts:AssumeRole
      ManagedPolicyArns:
        # SSMによるインスタンス管理
        - arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore
      Tags:
        - Key: Project
          Value: !Ref ProjectName
        - Key: ManagedBy
          Value: CloudFormation

  KiroCrewEC2InstanceProfile:
    Type: AWS::IAM::InstanceProfile
    Properties:
      InstanceProfileName: !Sub "${ProjectName}-ec2-profile-${DeployDate}"
      Roles:
        - !Ref KiroCrewEC2Role

  # ------------------------------------------------------------------
  # EC2 Instance
  # ------------------------------------------------------------------
  KiroCrewEC2Instance:
    Type: AWS::EC2::Instance
    DependsOn:
      - KiroCrewVPCGatewayAttachment
      - KiroCrewDefaultRoute
    Properties:
      InstanceType: !Ref InstanceType
      ImageId: !Ref AmiId
      SubnetId: !Ref KiroCrewSubnet
      IamInstanceProfile: !Ref KiroCrewEC2InstanceProfile
      SecurityGroupIds:
        - !Ref KiroCrewSecurityGroup

      # IMDSv2必須: HopLimit=2 (コンテナ内からメタデータ取得可能)
      MetadataOptions:
        HttpTokens: required
        HttpPutResponseHopLimit: 2
        HttpEndpoint: enabled

      # ルートボリューム: 暗号化gp3
      BlockDeviceMappings:
        - DeviceName: /dev/xvda
          Ebs:
            VolumeType: gp3
            VolumeSize: !Ref RootVolumeSize
            Encrypted: true
            DeleteOnTermination: true

      # UserDataはbootstrap.shをbase64エンコードして埋め込む
      UserData:
        Fn::Base64: !Sub |
          #!/bin/bash
          # Kiro Crew EC2 ARM64 bootstrap: SSM + Docker + Tailscale + KiroCrew
          # CFN Stack: ${AWS::StackName} / Region: ${AWS::Region}
          # Date: ${DeployDate}
          #
          # Human steps (NOT automated here):
          #   1. sudo tailscale up
          #   2. sudo docker compose exec kirocrew kiro-cli login --use-device-flow
          #   3. sudo docker compose exec kirocrew kirocrew setup
          #   4. sudo tailscale serve --bg --yes http://127.0.0.1:5478
          #   -> See runbooks/human-operations-runbook.md for full details
          set -euo pipefail

          LOG=/var/log/kirocrew-bootstrap.log
          exec > >(tee -a "$LOG") 2>&1

          echo "===== Kiro Crew bootstrap started: $(date -Is) ====="
          echo "Stack: ${AWS::StackName}"
          echo "Region: ${AWS::Region}"

          # AL2023のSSM Agentを有効化
          systemctl enable --now amazon-ssm-agent || true

          # ssm-user作成 + sudo権限付与
          useradd -m -s /bin/bash ssm-user 2>/dev/null || true
          echo 'ssm-user ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/ssm-agent-users
          chmod 440 /etc/sudoers.d/ssm-agent-users

          # Docker
          dnf install -y docker
          systemctl enable --now docker
          usermod -aG docker ssm-user || true

          # Docker Compose ARM64プラグイン (pinned v5.4.0)
          COMPOSE_VERSION=v5.4.0
          install -d -m 0755 /usr/local/lib/docker/cli-plugins
          curl --fail --silent --show-error --location \
            "https://github.com/docker/compose/releases/download/${!COMPOSE_VERSION}/docker-compose-linux-aarch64" \
            --output /usr/local/lib/docker/cli-plugins/docker-compose
          chmod 0755 /usr/local/lib/docker/cli-plugins/docker-compose

          # swapfile (メモリ補助 1GiB)
          if ! swapon --show --noheadings | grep -q . && [ ! -e /swapfile ]; then
            fallocate -l 1G /swapfile
            chmod 600 /swapfile
            mkswap /swapfile
            swapon /swapfile
            echo '/swapfile none swap sw 0 0' >> /etc/fstab
          fi

          # Tailscale (認証は人間が実施)
          curl -fsSL https://tailscale.com/install.sh | sh
          systemctl enable --now tailscaled

          # KiroCrew作業ディレクトリ
          install -d -m 0755 /opt/kirocrew

          # HTTP access log: クエリ文字列・認証情報を記録しない専用ロガー
          cat > /opt/kirocrew/kirocrew-safe-access-log-sitecustomize.py <<'PY'
          """Safe query-free aiohttp access logging for Kiro Crew gateway."""
          from __future__ import annotations
          import logging, os
          from logging.handlers import RotatingFileHandler
          try:
              from aiohttp import web_log
              from aiohttp.web_runner import AppRunner
              class SafeAccessLogger(web_log.AbstractAccessLogger):
                  def log(self, request, response, time):
                      path = getattr(request, "path", "<unknown>")
                      if not isinstance(path, str): path = "<unknown>"
                      self.logger.info("http_request method=%s path=%s status=%s duration_ms=%.1f",
                          getattr(request,"method","<unknown>"), path[:512],
                          getattr(response,"status","<unknown>"), time*1000.0)
              _orig = AppRunner.__init__
              def _safe_init(self, app, *, handle_signals=False, access_log_class=SafeAccessLogger, **kw):
                  return _orig(self, app, handle_signals=handle_signals, access_log_class=access_log_class, **kw)
              if not getattr(AppRunner,"_kirocrew_safe_access_logging",False):
                  AppRunner.__init__ = _safe_init
                  AppRunner._kirocrew_safe_access_logging = True
              al = logging.getLogger("aiohttp.access")
              al.setLevel(logging.INFO); al.propagate = True
              lp = os.environ.get("KIROCREW_ACCESS_LOG_FILE","/home/kirocrew/access.log")
              if not any(getattr(h,"_kirocrew_safe_access",False) for h in al.handlers):
                  h = RotatingFileHandler(lp, maxBytes=2*1024*1024, backupCount=3, encoding="utf-8")
                  h.setLevel(logging.INFO)
                  h.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s",datefmt="%Y-%m-%dT%H:%M:%S%z"))
                  h._kirocrew_safe_access = True; al.addHandler(h)
                  try: os.chmod(lp, 0o600)
                  except OSError: pass
          except Exception: pass
          PY
          chmod 0644 /opt/kirocrew/kirocrew-safe-access-log-sitecustomize.py

          # Docker Composeファイル
          cat > /opt/kirocrew/compose.yaml <<'COMPOSE'
          name: kirocrew-ec2

          services:
            kirocrew:
              image: ghcr.io/kirodotdev/kirocrew:stable
              container_name: kirocrew-ec2-gateway
              restart: unless-stopped
              ports:
                - "127.0.0.1:${!KIROCREW_HOST_PORT:?Set KIROCREW_HOST_PORT}:5476"
              volumes:
                - kirocrew-ec2-home:/home/kirocrew
                - ./kirocrew-safe-access-log-sitecustomize.py:/opt/kirocrew/patches/sitecustomize.py:ro
              environment:
                PYTHONPATH: /opt/kirocrew/patches
                KIROCREW_ACCESS_LOG_FILE: /home/kirocrew/access.log
                KIROCREW_ALLOW_UNSANDBOXED: ${!KIROCREW_ALLOW_UNSANDBOXED:?Set KIROCREW_ALLOW_UNSANDBOXED=1 after operator approval}

          volumes:
            kirocrew-ec2-home:
              name: ${!KIROCREW_VOLUME_NAME:?Set KIROCREW_VOLUME_NAME}
          COMPOSE

          # 環境変数ファイル
          VOLUME_SUFFIX=$(date +%Y%m%d)
          cat > /opt/kirocrew/.env <<ENV
          KIROCREW_HOST_PORT=5478
          KIROCREW_VOLUME_NAME=kirocrew-ec2-home-cfn-${!VOLUME_SUFFIX}
          KIROCREW_ALLOW_UNSANDBOXED=1
          ENV
          chmod 600 /opt/kirocrew/.env

          # コンテナ起動
          cd /opt/kirocrew
          docker compose config --quiet
          docker compose pull
          docker compose up -d --force-recreate

          # ヘルスチェック (最大120秒)
          for attempt in $(seq 1 60); do
            if curl --fail --silent http://127.0.0.1:5478/api/health >/dev/null 2>&1; then
              echo "Kiro Crew health: OK (attempt=${!attempt})"
              break
            fi
            if [ "${!attempt}" -eq 60 ]; then
              echo "ERROR: health check failed"
              docker compose logs --tail=100 kirocrew || true
              exit 1
            fi
            sleep 2
          done

          # sandbox設定
          docker compose exec -T kirocrew kirocrew config set \
            agent.sandbox_allow_unsandboxed_exec true || true

          echo "--- versions ---"
          docker --version
          docker compose version
          tailscale version
          echo "--- container status ---"
          docker compose ps
          echo "===== bootstrap completed: $(date -Is) ====="

      Tags:
        - Key: Name
          Value: !Sub "${ProjectName}-ec2-${DeployDate}"
        - Key: Project
          Value: !Ref ProjectName
        - Key: ManagedBy
          Value: CloudFormation
        - Key: SandboxPosture
          Value: container-only
        - Key: BootstrapDate
          Value: !Ref DeployDate

# ====================================================================
# Outputs
# ====================================================================
Outputs:
  InstanceId:
    Description: EC2 Instance ID
    Value: !Ref KiroCrewEC2Instance
    Export:
      Name: !Sub "${AWS::StackName}-InstanceId"

  VpcId:
    Description: VPC ID
    Value: !Ref KiroCrewVPC
    Export:
      Name: !Sub "${AWS::StackName}-VpcId"

  SubnetId:
    Description: Subnet ID
    Value: !Ref KiroCrewSubnet
    Export:
      Name: !Sub "${AWS::StackName}-SubnetId"

  SecurityGroupId:
    Description: Security Group ID
    Value: !Ref KiroCrewSecurityGroup
    Export:
      Name: !Sub "${AWS::StackName}-SecurityGroupId"

  IAMRoleArn:
    Description: IAM Role ARN
    Value: !GetAtt KiroCrewEC2Role.Arn

  SSMConnectCommand:
    Description: SSM Session Manager connect command
    Value: !Sub "aws ssm start-session --target ${KiroCrewEC2Instance} --region ${AWS::Region}"

  BootstrapLogCommand:
    Description: Bootstrap log tail command via SSM
    Value: !Sub "aws ssm send-command --instance-ids ${KiroCrewEC2Instance} --document-name AWS-RunShellScript --parameters commands='tail -100 /var/log/kirocrew-bootstrap.log' --region ${AWS::Region}"

Docker Compose File

This is the Compose definition placed at /opt/kirocrew/compose.yaml via UserData. Compose uses ghcr.io/kirodotdev/kirocrew:stable and limits the host-side publishing destination to loopback.

compose.yaml
name: kirocrew-ec2

services:
  kirocrew:
    image: ghcr.io/kirodotdev/kirocrew:stable
    container_name: kirocrew-ec2-gateway
    restart: unless-stopped
    ports:
      - "127.0.0.1:${KIROCREW_HOST_PORT:?Set KIROCREW_HOST_PORT}:5476"
    volumes:
      - kirocrew-ec2-home:/home/kirocrew
      - ./kirocrew-safe-access-log-sitecustomize.py:/opt/kirocrew/patches/sitecustomize.py:ro
    environment:
      PYTHONPATH: /opt/kirocrew/patches
      KIROCREW_ACCESS_LOG_FILE: /home/kirocrew/access.log
      # Disabling the sandbox is required on the AL2023/Docker runtime. The container is the only isolation boundary.
      KIROCREW_ALLOW_UNSANDBOXED: ${KIROCREW_ALLOW_UNSANDBOXED:?Set KIROCREW_ALLOW_UNSANDBOXED=1 after operator approval}

volumes:
  kirocrew-ec2-home:
    name: ${KIROCREW_VOLUME_NAME:?Set KIROCREW_VOLUME_NAME}

UserData bootstrap

This is the full text of userdata/bootstrap.sh, executed during the initial EC2 setup.

userdata/bootstrap.sh (full text)
#!/bin/bash
# Kiro Crew EC2 ARM64 bootstrap: SSM + Docker + Tailscale + KiroCrew
# 2026-08-06 ap-northeast-1 CloudFormation用 UserData
#
# 人間が実施する手順 (UserDataでは行わない):
#   - sudo tailscale up                           # Tailscale認証
#   - sudo docker compose exec kirocrew kiro-cli login --use-device-flow  # KiroCLI認証
#   - sudo docker compose exec kirocrew kirocrew setup                     # KiroCrew初期設定
#   - sudo tailscale serve --bg --yes http://127.0.0.1:5478               # Tailscale Serve設定
#   - Runbook: runbooks/human-operations-runbook.md 参照
#
# セキュリティポスチャ:
#   - IMDSv2必須 (MetadataOptions: HttpTokens=required)
#   - SSMのみ管理アクセス (inboundポート不要)
#   - DockerはloopbackのみPublish (127.0.0.1:5478)
#   - Tailscale ServeはtailnetのみPublish (funnel不使用)
set -euo pipefail

LOG=/var/log/kirocrew-bootstrap.log
exec > >(tee -a "$LOG") 2>&1

echo "===== Kiro Crew bootstrap started: $(date -Is) ====="

# AL2023にはSSM Agentが含まれている。起動を確認する。
systemctl enable --now amazon-ssm-agent || true

# ssm-userを作成してDockerグループに追加・sudo権限付与
useradd -m -s /bin/bash ssm-user 2>/dev/null || true
echo 'ssm-user ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/ssm-agent-users
chmod 440 /etc/sudoers.d/ssm-agent-users

# Dockerをインストールする。AL2023はdnfを使う。
dnf install -y docker
systemctl enable --now docker
usermod -aG docker ssm-user || true

# Docker Compose ARM64プラグイン (固定バージョン)
COMPOSE_VERSION=v5.4.0
install -d -m 0755 /usr/local/lib/docker/cli-plugins
curl --fail --silent --show-error --location \
  "https://github.com/docker/compose/releases/download/${COMPOSE_VERSION}/docker-compose-linux-aarch64" \
  --output /usr/local/lib/docker/cli-plugins/docker-compose
chmod 0755 /usr/local/lib/docker/cli-plugins/docker-compose

# swapfile (4GiBインスタンスのメモリ補助)
if ! swapon --show --noheadings | grep -q . && [ ! -e /swapfile ]; then
  fallocate -l 1G /swapfile
  chmod 600 /swapfile
  mkswap /swapfile
  swapon /swapfile
  echo '/swapfile none swap sw 0 0' >> /etc/fstab
fi

# Tailscaleをインストールするが認証は人間が実施する
curl -fsSL https://tailscale.com/install.sh | sh
systemctl enable --now tailscaled

# KiroCrew作業ディレクトリ作成
install -d -m 0755 /opt/kirocrew

# HTTP access log: クエリ文字列・認証情報を記録しない専用ロガー
cat > /opt/kirocrew/kirocrew-safe-access-log-sitecustomize.py <<'PY'
"""Safe query-free aiohttp access logging for the Kiro Crew gateway.

PYTHONPATH/sitecustomize.py 経由でロードされる。
記録対象: HTTP method, path(クエリなし), status, duration_ms のみ。
query, header, cookie, authorization, IP, body は記録しない。
"""
from __future__ import annotations
import logging
import os
from logging.handlers import RotatingFileHandler
try:
    from aiohttp import web_log
    from aiohttp.web_runner import AppRunner
    class SafeAccessLogger(web_log.AbstractAccessLogger):
        def log(self, request, response, time):
            path = getattr(request, "path", "<unknown>")
            if not isinstance(path, str):
                path = "<unknown>"
            self.logger.info(
                "http_request method=%s path=%s status=%s duration_ms=%.1f",
                getattr(request, "method", "<unknown>"),
                path[:512],
                getattr(response, "status", "<unknown>"),
                time * 1000.0,
            )
    _original_init = AppRunner.__init__
    def _safe_app_runner_init(self, app, *, handle_signals=False, access_log_class=SafeAccessLogger, **kwargs):
        return _original_init(self, app, handle_signals=handle_signals, access_log_class=access_log_class, **kwargs)
    if not getattr(AppRunner, "_kirocrew_safe_access_logging", False):
        AppRunner.__init__ = _safe_app_runner_init
        AppRunner._kirocrew_safe_access_logging = True
    access_logger = logging.getLogger("aiohttp.access")
    access_logger.setLevel(logging.INFO)
    access_logger.propagate = True
    log_path = os.environ.get("KIROCREW_ACCESS_LOG_FILE", "/home/kirocrew/access.log")
    if not any(getattr(h, "_kirocrew_safe_access", False) for h in access_logger.handlers):
        handler = RotatingFileHandler(log_path, maxBytes=2 * 1024 * 1024, backupCount=3, encoding="utf-8")
        handler.setLevel(logging.INFO)
        handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s", datefmt="%Y-%m-%dT%H:%M:%S%z"))
        handler._kirocrew_safe_access = True
        access_logger.addHandler(handler)
        try:
            os.chmod(log_path, 0o600)
        except OSError:
            pass
except Exception:
    pass
PY
chmod 0644 /opt/kirocrew/kirocrew-safe-access-log-sitecustomize.py

# Docker Composeファイル
cat > /opt/kirocrew/compose.yaml <<'COMPOSE'
name: kirocrew-ec2

services:
  kirocrew:
    image: ghcr.io/kirodotdev/kirocrew:stable
    container_name: kirocrew-ec2-gateway
    restart: unless-stopped
    ports:
      - "127.0.0.1:${KIROCREW_HOST_PORT:?Set KIROCREW_HOST_PORT}:5476"
    volumes:
      - kirocrew-ec2-home:/home/kirocrew
      - ./kirocrew-safe-access-log-sitecustomize.py:/opt/kirocrew/patches/sitecustomize.py:ro
    environment:
      PYTHONPATH: /opt/kirocrew/patches
      KIROCREW_ACCESS_LOG_FILE: /home/kirocrew/access.log
      # AL2023/Docker runtimeではsandbox無効化が必要。コンテナが唯一の隔離境界。
      KIROCREW_ALLOW_UNSANDBOXED: ${KIROCREW_ALLOW_UNSANDBOXED:?Set KIROCREW_ALLOW_UNSANDBOXED=1 after operator approval}

volumes:
  kirocrew-ec2-home:
    name: ${KIROCREW_VOLUME_NAME:?Set KIROCREW_VOLUME_NAME}
COMPOSE

# 環境変数ファイル (mode 600)
VOLUME_SUFFIX=$(date +%Y%m%d)
cat > /opt/kirocrew/.env <<ENV
KIROCREW_HOST_PORT=5478
KIROCREW_VOLUME_NAME=kirocrew-ec2-home-cfn-${VOLUME_SUFFIX}
# AL2023/Docker runtimeでKiro CLI・agentを動かすために必要。
# コンテナが唯一の隔離境界となることをoperatorが明示承認。
KIROCREW_ALLOW_UNSANDBOXED=1
ENV
chmod 600 /opt/kirocrew/.env

# コンテナ起動
cd /opt/kirocrew
docker compose config --quiet
docker compose pull
docker compose up -d --force-recreate

# ヘルスチェック (最大120秒待機)
for attempt in $(seq 1 60); do
  if curl --fail --silent http://127.0.0.1:5478/api/health >/dev/null 2>&1; then
    echo "Kiro Crew health: OK (attempt=${attempt})"
    break
  fi
  if [ "$attempt" -eq 60 ]; then
    echo "ERROR: Kiro Crew health check failed after 120s"
    docker compose logs --tail=100 kirocrew || true
    exit 1
  fi
  sleep 2
done

# sandbox設定
docker compose exec -T kirocrew kirocrew config set \
  agent.sandbox_allow_unsandboxed_exec true || true

# バージョン確認ログ
echo "--- versions ---"
docker --version
docker compose version
tailscale version
echo "--- container status ---"
docker compose ps

printf '%s\n' '====================================='
printf '%s\n' 'Bootstrap completed. Human steps:'
printf '%s\n' '  1. sudo tailscale up'
printf '%s\n' '  2. sudo tailscale status'
printf '%s\n' '  3. cd /opt/kirocrew && sudo docker compose exec kirocrew kiro-cli login --use-device-flow'
printf '%s\n' '  4. sudo docker compose exec kirocrew kirocrew setup'
printf '%s\n' '  5. sudo tailscale serve --bg --yes http://127.0.0.1:5478'
printf '%s\n' '  6. See runbooks/human-operations-runbook.md for full details'
printf '%s\n' '====================================='

echo "===== Kiro Crew bootstrap completed: $(date -Is) ====="

SSM Attended Operations Runbook

These are the steps after starting an SSM session: authentication, initial setup, Tailscale Serve configuration, obtaining the dashboard token, connection verification, and checking access.log. Specific examples of Tailscale ACLs are outside the scope of this verification.

human-operations-runbook.md
# Kiro Crew EC2 - Human Operations Runbook

These are the steps a human performs via an SSM session on the EC2 instance deployed with CloudFormation.

## Target Environment

| Item | Value |
|---|---|
| Region | ap-northeast-1 |
| Stack name | `kirocrew-cfn-20260806` (the one specified at deployment) |
| Docker host port | `127.0.0.1:5478` |
| Compose directory | `/opt/kirocrew` |
| Bootstrap log | `/var/log/kirocrew-bootstrap.log` |

> **Note**: Do not save authentication URLs, device codes, Tailscale tokens, or dashboard tokens in this Runbook, chat, or Git.

---

## Pre-check: Bootstrap Completion and SSM Online

After the CFn deployment, wait 2 to 5 minutes until the EC2 instance becomes SSM Online.

```bash
# Get InstanceId from the CFn stack Outputs
STACK_NAME=kirocrew-cfn-20260806
REGION=ap-northeast-1

INSTANCE_ID=$(aws cloudformation describe-stacks \
  --stack-name "$STACK_NAME" \
  --region "$REGION" \
  --query 'Stacks[0].Outputs[?OutputKey==`InstanceId`].OutputValue' \
  --output text)

echo "InstanceId: $INSTANCE_ID"

# Check SSM Online (repeat until Online)
aws ssm describe-instance-information \
  --region "$REGION" \
  --filters "Key=InstanceIds,Values=$INSTANCE_ID" \
  --query 'InstanceInformationList[0].{Id:InstanceId,PingStatus:PingStatus,PlatformType:PlatformType}' \
  --output table
```

Open an SSM session.

```bash
aws ssm start-session --target "$INSTANCE_ID" --region "$REGION"
```

Confirm that the bootstrap has completed (the last line of UserData).

```bash
sudo tail -30 /var/log/kirocrew-bootstrap.log
```

Expected ending:

```
===== bootstrap completed: 2026-08-06T...
```

Check the container and health.

```bash
cd /opt/kirocrew
sudo docker compose ps
curl --fail --silent http://127.0.0.1:5478/api/health
```

Expected value: `{"ok": true}`

---

## Step 1: Tailscale Authentication

### 1-1. Tailscale up (displays the authentication URL)

Run inside the SSM session.

```bash
sudo tailscale up
```

Open the displayed authentication URL in a browser and complete the login.

> Do not save the authentication URL in this Runbook, chat, or Git.

### 1-2. Check Tailscale status

```bash
sudo tailscale status
sudo tailscale version
```

Confirm that `Connected` is displayed.

---

## Step 2: Kiro CLI License Authentication

### 2-1. device-flow authentication

Run inside the SSM session.

```bash
cd /opt/kirocrew
sudo docker compose exec kirocrew kiro-cli login --use-device-flow
```

Log in with the browser using the displayed URL and device code.

> Do not save the authentication URL or device code in this Runbook, chat, or Git.

### 2-2. Verify authentication

```bash
sudo docker compose exec -T kirocrew kiro-cli whoami 2>/dev/null || \
sudo docker compose exec -T kirocrew kiro-cli status 2>/dev/null || true
```

---

## Step 3: Kiro Crew Initial Setup

### 3-1. kirocrew setup

Run inside the SSM session (interactive operation required).

```bash
sudo docker compose exec kirocrew kirocrew setup
```

Recommended settings:

| Item | Recommended value |
|---|---|
| Workspace | Default (just press Enter) |
| Slack | Skip (no) |
| Slash command | `kirocrew` |
| Timezone | `Asia/Tokyo` |
| Playwright MCP | Install (yes) |
| AWS cloud launch | Skip (no) |

### 3-2. Kiro Crew doctor

```bash
sudo docker compose exec -T kirocrew kirocrew doctor
sudo docker compose ps
```

---

## Step 4: Tailscale Serve Configuration

### 4-1. Start Serve (tailnet only)

```bash
sudo tailscale serve --bg --yes "http://127.0.0.1:5478"
```

### 4-2. Get the Serve URL

```bash
sudo tailscale serve status
```

Example of expected value (the hostname differs in each environment):

```
https://<TAILSCALE_HOSTNAME> (tailnet only)
|-- / proxy http://127.0.0.1:5478
```

Confirm that `tailnet only` is displayed. Do not use `funnel`.

### 4-3. Set the Serve URL in a variable

```bash
SERVE_URL="$(sudo tailscale serve status | awk '$1 ~ /^https:\/\// {print $1; exit}')"
case "$SERVE_URL" in
  https://*) echo "Serve URL: $SERVE_URL" ;;
  *) echo "ERROR: Tailscale Serve URL not found" >&2; exit 1 ;;
esac
```

---

## Step 5: Register the Serve URL in Kiro Crew

```bash
cd /opt/kirocrew

sudo docker compose exec -T kirocrew kirocrew config set \
  dashboard.url "$SERVE_URL"

sudo docker compose restart kirocrew
```

Verify the settings.

```bash
sudo docker compose exec -T kirocrew kirocrew config get dashboard.url
sudo docker compose ps
curl --fail --silent http://127.0.0.1:5478/api/health
```

---

## Step 6: Obtain the Dashboard Token

### 6-1. Issue a short-lived token

```bash
cd /opt/kirocrew
TOKEN=$(sudo docker compose exec -T kirocrew kirocrew token --ttl 2h)
```

### 6-2. Temporarily save the URL for browser connection to a file

> Do not output the token to chat, logs, or Git.

```bash
# Save temporarily on EC2 local only (mode 600)
echo "$TOKEN" | sudo tee /run/kirocrew-dashboard-token > /dev/null
sudo chmod 600 /run/kirocrew-dashboard-token
echo "Token saved to /run/kirocrew-dashboard-token (mode 600)"
echo "URL pattern: ${SERVE_URL}?token=<token>"
```

### 6-3. Read, use, and delete the token

Run inside the SSM session.

```bash
# Read (do not copy the token value into this Runbook)
sudo cat /run/kirocrew-dashboard-token

# Delete immediately after accessing in the browser
sudo rm -f /run/kirocrew-dashboard-token
```

---

## Step 7: Connection Verification

### 7-1. On the EC2 host

```bash
curl --fail --silent "http://127.0.0.1:5478/api/health"
sudo docker compose ps
sudo tailscale serve status
```

### 7-2. From another device connected to Tailscale

Run from a Mac or similar connected to the tailnet (no SSH tunnel needed).

```bash
SERVE_URL="<URL confirmed with tailscale serve status>"
curl --connect-timeout 5 --max-time 10 --fail "${SERVE_URL}/api/health"
```

Expected value: `{"ok": true}`

### 7-3. Browser access

Open the following in the browser of a device connected to the tailnet.

```
https://<TAILSCALE_HOSTNAME>?token=<token>
```

---

## Step 8: Check the Access Log

```bash
cd /opt/kirocrew
# Check file permissions
sudo docker compose exec -T kirocrew stat -c '%a %n' /home/kirocrew/access.log

# Check the last 50 lines (only method, path, status, duration_ms are recorded)
sudo docker compose exec -T kirocrew sh -c 'tail -n 50 /home/kirocrew/access.log'
```

The access log records only the method, the path without the query, the HTTP status, and duration_ms.
It does not record the query string, headers, cookies, authorization, IP, or body.

---

## Troubleshooting

### `Host header not allowed.`

```bash
cd /opt/kirocrew
SERVE_URL="$(sudo tailscale serve status | awk '$1 ~ /^https:\/\// {print $1; exit}')"
sudo docker compose exec -T kirocrew kirocrew config set dashboard.url "$SERVE_URL"
sudo docker compose restart kirocrew
curl --fail --silent "http://127.0.0.1:5478/api/health"
```

### Bootstrap not completed

```bash
sudo tail -50 /var/log/kirocrew-bootstrap.log
sudo systemctl status docker
sudo docker compose -f /opt/kirocrew/compose.yaml ps
```

### Container does not start

```bash
cd /opt/kirocrew
cat .env  # Contains no secret values
sudo docker compose logs --tail=50 kirocrew
sudo docker compose up -d --force-recreate
```

---

## Stop and Rollback

To stop only Tailscale Serve:

```bash
sudo tailscale serve --https=443 off
```

To stop Tailscale Serve and return to localhost only:

```bash
cd /opt/kirocrew
sudo tailscale serve --https=443 off
sudo docker compose exec -T kirocrew kirocrew config set \
  dashboard.url "http://localhost:5478"
sudo docker compose restart kirocrew
```

---

## Security Notes

- Use Tailscale Serve with `tailnet only`, and do not use `tailscale funnel`
- Do not change the Docker port to `0.0.0.0:5478` (loopback only)
- Restrict the users and devices that can access via Tailscale ACLs
- Do not share or save Kiro Crew's short-lived dashboard tokens
- `KIROCREW_ALLOW_UNSANDBOXED=1` means the container is the only isolation boundary. Operate it only after the operator has approved the risk of storing credentials inside the container
- Disconnect the SSM session with `exit` after operations

Share this article

AWSのお困り事はクラスメソッドへ