EC2 boxes¶

Local files¶

The default config is ${XDG_CONFIG_HOME:-~/.config}/boxman/ec2.toml. It has [machines.red], [machines.blue], or [machines.green] tables with profile, region, and optional tags. Set [ec2].default_machine to choose the default. Use --machine NAME to override it, and --config PATH to select another machine collection. Global options such as --config, --machine, --profile, and --region go before the action.

init --machine red creates ${XDG_CONFIG_HOME:-~/.config}/boxman/stacks/red.yaml and uses the derived stack name boxman-red. It refuses to overwrite the file. The generated template includes all six required instance values as CloudFormation parameter defaults. To change a box, edit those defaults or the resource definitions, then run deploy. deploy reads the defaults from the YAML and passes them as stack parameters. Keep the Parameters entries in the generated form so Boxman can read them.

The template creates an Ubuntu EC2 instance, SSM role, security groups, and Instance Connect Endpoint. The AMI value can be a Systems Manager parameter path. Tags in [machines.red.tags] become stack tags; boxman ec2 deploy --tag KEY=VALUE adds or overrides a tag for that invocation.

Day-to-day operations¶

boxman ec2 status                         # default machine
boxman ec2 --machine blue status
boxman ec2 start
boxman ec2 stop
boxman ec2 connect
boxman ec2 connect -u myuser
boxman ec2 run 'uname -a'
boxman ec2 run -u myuser 'id'
boxman ec2 setup --user alice

status reports EC2 state and SSM registration. start and stop wait for the instance state change. connect -u starts a session as ssm-user and uses sudo -iu to enter the chosen account. run executes through SSM Run Command as root unless -u is supplied; it prints status and output and exits with an error when the remote command fails.

setup --user USER is the laptop-side host bootstrap. It uses the Ubuntu image's ubuntu account by default only for bootstrap; pass --bootstrap-user ACCOUNT for a custom image. USER must be a different account. Boxman writes temporary SSH entries, uses EC2 Instance Connect to send a short-lived key for the bootstrap account, copies the local Boxman package to a temporary directory on the host, installs system packages, creates USER if needed, configures its subordinate IDs and lingering, then reconnects as USER for boxman user, installs the published boxman[ec2] command permanently, and runs boxman verify. The bootstrap account must have passwordless sudo. The temporary package directory is removed afterward.

SSH and editor access¶

boxman ec2 ssh -u myuser
boxman ec2 ssh -u myuser -c my-container
boxman ec2 ssh-config -u myuser
boxman ec2 --machine red ssh-config -u myuser --herdr
ssh mybox

Both SSH commands generate a dedicated local key pair when needed. Their ProxyCommand calls EC2 Instance Connect to send the public key for the selected Unix user immediately before opening the tunnel; no persistent authorized_keys change is required. ssh-config writes a marked host block to ~/.ssh/config, so OpenSSH tools and VS Code Remote SSH can use the alias. The alias defaults to the selected machine name; pass --alias when you want a different local name. --herdr then runs herdr machine add for that same alias, which prepares the remote Herdr server and saves the machine locally. You can pass --key-path PATH to choose the key pair. Re-run ssh-config after an instance replacement.

Sending secrets¶

Create a JSON file of string values on your laptop and restrict its access:

{"GH_TOKEN":"github-token"}

chmod 600 secrets.json
boxman ec2 --machine red secrets send ./secrets.json -u alice

Boxman sends the document over SSH to boxman secrets receive running as Alice. The host loads it into the default tempkeys keyset. Inside that Unix account, boxman secrets read NAME prints one value, and tempkeys clear removes the keyset. Names must be environment variable names and values must be nonempty strings. Every process running as Alice can potentially read these values. The laptop file remains the source of truth: resend it after a host reboot, which clears kernel keyrings. An upload replaces the whole keyset atomically. For HTTPS GitHub remotes, boxman user configures Git to fetch GH_TOKEN from tempkeys when needed. SSH Git remotes use SSH keys instead. Secrets stored by the earlier Boxman format need to be resent after upgrading.

More than one box¶

Add another [machines.blue] or [machines.green] table and run commands with boxman ec2 --machine blue .... Each machine gets its own YAML file and derived stack in the boxman config directory. An alias passed to ssh-config is local to your SSH config; choose distinct aliases for boxes you want to keep available together.