Creating an Environment

End-to-end guide: user accounts, SSH keys, VPCs, AMIs, and launching instances.

Overview
Instructions
Troubleshooting

Overview

This guide walks through the complete workflow for creating a production-ready Spinifex environment.

Steps:

Create a user account
Import or create SSH keys
Create a VPC and subnet
Select and import an AMI
Launch EC2 instances
Connect via SSH
Monitor instance health

Instructions

1. Import SSH Key

aws ec2 import-key-pair --key-name "spinifex-key" --public-key-material fileb://~/.ssh/id_rsa.pub

2. Create VPC

aws ec2 create-vpc --cidr-block 10.200.0.0/16
export SPINIFEX_VPC="vpc-XXX"

aws ec2 create-subnet --vpc-id $SPINIFEX_VPC --cidr-block 10.200.1.0/24
export SPINIFEX_SUBNET="subnet-XXX"

3. Import AMI

./bin/spx admin images list
./bin/spx admin images import --name debian-12-x86_64
export SPINIFEX_AMI="ami-XXX"

4. Launch Instance

aws ec2 run-instances \
  --image-id $SPINIFEX_AMI \
  --instance-type t3.small \
  --key-name spinifex-key \
  --subnet-id $SPINIFEX_SUBNET \
  --count 1

5. Connect via SSH

ps auxw | grep $INSTANCE_ID
# Look for: hostfwd=tcp:127.0.0.1:<port>-:22

ssh -i ~/.ssh/spinifex-key ec2-user@127.0.0.1 -p <port>

Troubleshooting

Instance stuck in pending

Check the Spinifex daemon and QEMU logs for boot errors:

ls ~/spinifex/logs/
cat ~/spinifex/logs/spinifex.log

Verify the AMI exists and architecture matches your host:

aws ec2 describe-images --image-ids $SPINIFEX_AMI

SSH connection refused

cloud-init takes 30-60 seconds to configure networking and SSH after boot. Wait and retry.

Verify the SSH port forwarding is active:

ps auxw | grep hostfwd

Ensure you're using the correct key and port:

ssh -i ~/.ssh/spinifex-key ec2-user@127.0.0.1 -p <port>

README.md