Files
2026-05-02 02:30:12 -07:00

10 KiB

Machine Env Service

IMDSv2-compatible local metadata daemon for homelab machines. Each machine runs one daemon, and local processes or containers can fetch machine-scoped metadata and allowlisted Infisical secrets through HTTP without holding Infisical credentials.

What It Exposes

Token endpoint:

PUT /latest/api/token

Metadata endpoints require X-aws-ec2-metadata-token:

/latest/meta-data/
/latest/meta-data/hostname
/latest/meta-data/local-hostname
/latest/meta-data/local-ipv4
/latest/meta-data/mac
/latest/meta-data/machine-id
/latest/meta-data/environment
/latest/meta-data/role
/latest/meta-data/tags/
/latest/meta-data/tags/<KEY>
/latest/meta-data/tags/instance/
/latest/meta-data/tags/instance/<KEY>
/latest/meta-data/secrets/
/latest/meta-data/secrets/<KEY>
/latest/dynamic/instance-identity/document
/latest/user-data

/latest/meta-data/secrets-bundle is available only when ALLOW_SECRETS_BUNDLE=true.

Configuration

The daemon reads its own dotenv-style config file.

Default paths:

Linux: /etc/machine-env-service/env
macOS: /usr/local/etc/machine-env-service/env

Override with:

MACHINE_ENV_CONFIG=/path/to/env

Minimum config:

INFISICAL_ACCESS_TOKEN=
INFISICAL_PROJECT_ID=
INFISICAL_ENVIRONMENT=prod

KNOWN_SECRET_KEYS=FOO,BAR
METADATA_PORT=8675
REFRESH_INTERVAL_SEC=60

Optional machine metadata:

MACHINE_ID=
MACHINE_HOSTNAME=
MACHINE_LOCAL_HOSTNAME=
MACHINE_LOCAL_IPV4=
MACHINE_MAC=
MACHINE_ROLE=homelab-node
MACHINE_TAGS=site=home,tier=prod
USER_DATA=
USER_DATA_FILE=

If machine fields are empty, the daemon derives hostname, IPv4, MAC, and machine-id from the OS where possible.

Secret allowlist variables are checked in this order:

KNOWN_SECRET_KEYS
EXPOSED_SECRET_KEYS
SECRET_ALLOWLIST
SECRET_WHITELIST

Values can be comma-separated or whitespace-separated.

Local Development

Build:

npm ci
npm run build

Run locally without binding 169.254.169.254:80:

NODE_ENV=dev LINK_LOCAL_LISTENER_ENABLED=false npm start

Request a token:

TOKEN=$(
  curl -fsS -X PUT \
    -H "X-aws-ec2-metadata-token-ttl-seconds: 60" \
    http://127.0.0.1:8675/latest/api/token
)

Fetch metadata:

curl -fsS \
  -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://127.0.0.1:8675/latest/meta-data/hostname

Fetch a secret:

curl -fsS \
  -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://127.0.0.1:8675/latest/meta-data/secrets/FOO

Or use:

METADATA_BASE_URL=http://127.0.0.1:8675 ./examples/fetch-secret.sh FOO

Ubuntu Install

The included systemd units assume the app lives at /opt/machine-env-service.

Install files:

sudo mkdir -p /opt/machine-env-service
sudo chown -R "$USER:$USER" /opt/machine-env-service

rsync -a \
  --exclude .git \
  --exclude node_modules \
  --exclude dist \
  --exclude env-vars \
  ./ /opt/machine-env-service/

cd /opt/machine-env-service
npm ci
npm run build

Create service user:

sudo useradd --system --home /nonexistent --shell /usr/sbin/nologin machine-env || true

Create config:

sudo install -d -o machine-env -g machine-env -m 0700 /etc/machine-env-service
sudo cp deploy/systemd/machine-env-service.env.example /etc/machine-env-service/env
sudo nano /etc/machine-env-service/env
sudo chown machine-env:machine-env /etc/machine-env-service/env
sudo chmod 0600 /etc/machine-env-service/env

Install and start systemd units:

sudo cp deploy/systemd/machine-env-setup-link-local.service /etc/systemd/system/
sudo cp deploy/systemd/machine-env-service.service /etc/systemd/system/

sudo systemctl daemon-reload
sudo systemctl enable --now machine-env-setup-link-local.service
sudo systemctl enable --now machine-env-service.service

Check logs:

systemctl status machine-env-service.service
journalctl -u machine-env-service.service -f

Test the link-local endpoint:

TOKEN=$(
  curl -fsS -X PUT \
    -H "X-aws-ec2-metadata-token-ttl-seconds: 60" \
    http://169.254.169.254/latest/api/token
)

curl -fsS \
  -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/latest/meta-data/

macOS Install

The included launchd plists assume:

App path: /opt/machine-env-service
Node path: /usr/local/bin/node
Config path: /usr/local/etc/machine-env-service/env

Check your Node path first:

command -v node

If it is not /usr/local/bin/node, either update deploy/launchd/us.dahyeon.machine-env-service.plist before installing or create a system-visible symlink:

sudo mkdir -p /usr/local/bin
sudo ln -sf "$(command -v node)" /usr/local/bin/node

When Node comes from nvm, the symlink is the quickest local setup. A Homebrew Node installed at a stable path is usually better for a long-lived daemon.

Install files:

sudo mkdir -p /opt/machine-env-service
sudo chown -R "$(id -un):admin" /opt/machine-env-service

rsync -a \
  --exclude .git \
  --exclude node_modules \
  --exclude dist \
  --exclude env-vars \
  ./ /opt/machine-env-service/

cd /opt/machine-env-service
npm ci
npm run build

Create config:

sudo install -d -m 0700 /usr/local/etc/machine-env-service
sudo cp deploy/launchd/machine-env-service.env.example /usr/local/etc/machine-env-service/env
sudo nano /usr/local/etc/machine-env-service/env
sudo chown root:wheel /usr/local/etc/machine-env-service/env
sudo chmod 0600 /usr/local/etc/machine-env-service/env

Install and start launchd daemons:

sudo cp deploy/launchd/us.dahyeon.machine-env-setup-link-local.plist /Library/LaunchDaemons/
sudo cp deploy/launchd/us.dahyeon.machine-env-service.plist /Library/LaunchDaemons/

sudo chown root:wheel /Library/LaunchDaemons/us.dahyeon.machine-env-*.plist
sudo chmod 0644 /Library/LaunchDaemons/us.dahyeon.machine-env-*.plist

sudo launchctl bootstrap system /Library/LaunchDaemons/us.dahyeon.machine-env-setup-link-local.plist
sudo launchctl bootstrap system /Library/LaunchDaemons/us.dahyeon.machine-env-service.plist

Check logs:

sudo launchctl print system/us.dahyeon.machine-env-service
tail -f /var/log/machine-env-service.log
tail -f /var/log/machine-env-service.err.log

Test:

TOKEN=$(
  curl -fsS -X PUT \
    -H "X-aws-ec2-metadata-token-ttl-seconds: 60" \
    http://169.254.169.254/latest/api/token
)

curl -fsS \
  -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/latest/meta-data/hostname

Docker Desktop on macOS usually cannot route container traffic to host 169.254.169.254. Use the LAN listener instead:

http://host.docker.internal:8675/latest/meta-data/...

Update

Restarting the daemon invalidates issued IMDSv2 tokens. Clients should request a new token after an update.

If /opt/machine-env-service is a git checkout:

cd /opt/machine-env-service
git pull
npm ci
npm run build

If you deploy from another checkout:

rsync -a --delete \
  --exclude .git \
  --exclude node_modules \
  --exclude dist \
  --exclude env-vars \
  ./ /opt/machine-env-service/

cd /opt/machine-env-service
npm ci
npm run build

Do not overwrite the machine config file:

Linux: /etc/machine-env-service/env
macOS: /usr/local/etc/machine-env-service/env

Restart after code-only updates:

sudo systemctl restart machine-env-service.service
sudo launchctl kickstart -k system/us.dahyeon.machine-env-service

If systemd unit files changed:

sudo cp deploy/systemd/machine-env-setup-link-local.service /etc/systemd/system/
sudo cp deploy/systemd/machine-env-service.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl restart machine-env-setup-link-local.service
sudo systemctl restart machine-env-service.service

If launchd plist files changed:

sudo cp deploy/launchd/us.dahyeon.machine-env-setup-link-local.plist /Library/LaunchDaemons/
sudo cp deploy/launchd/us.dahyeon.machine-env-service.plist /Library/LaunchDaemons/
sudo chown root:wheel /Library/LaunchDaemons/us.dahyeon.machine-env-*.plist
sudo chmod 0644 /Library/LaunchDaemons/us.dahyeon.machine-env-*.plist

sudo launchctl bootout system /Library/LaunchDaemons/us.dahyeon.machine-env-service.plist 2>/dev/null || true
sudo launchctl bootout system /Library/LaunchDaemons/us.dahyeon.machine-env-setup-link-local.plist 2>/dev/null || true
sudo launchctl bootstrap system /Library/LaunchDaemons/us.dahyeon.machine-env-setup-link-local.plist
sudo launchctl bootstrap system /Library/LaunchDaemons/us.dahyeon.machine-env-service.plist

Check after updating:

systemctl status machine-env-service.service
journalctl -u machine-env-service.service -n 100
sudo launchctl print system/us.dahyeon.machine-env-service
tail -n 100 /var/log/machine-env-service.err.log

Operations

Restart:

sudo systemctl restart machine-env-service.service
sudo launchctl kickstart -k system/us.dahyeon.machine-env-service

Stop:

sudo systemctl stop machine-env-service.service
sudo launchctl bootout system /Library/LaunchDaemons/us.dahyeon.machine-env-service.plist

Troubleshooting

If curl http://169.254.169.254/latest/api/token fails with Couldn't connect to server, check the link-local alias and daemon separately:

ifconfig lo0 | grep 169.254.169.254
sudo launchctl print system/us.dahyeon.machine-env-service

If launchd shows last exit code = 78: EX_CONFIG and the plist points to /usr/local/bin/node, verify that Node exists there:

ls -l /usr/local/bin/node
command -v node

Fix a missing /usr/local/bin/node with:

sudo mkdir -p /usr/local/bin
sudo ln -sf "$(command -v node)" /usr/local/bin/node
sudo launchctl kickstart -k system/us.dahyeon.machine-env-service

Then retry token issuance.

Security Notes

  • Keep the config file mode at 0600.
  • Do not commit env-vars/*.env, production config files, or access tokens.
  • Only allowlist secrets that should be readable by local machine workloads.
  • Block METADATA_PORT from untrusted networks.
  • Requests with X-Forwarded-For are rejected.
  • Metadata requests require IMDSv2-style tokens; token TTL is 1..21600 seconds.