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_PORTfrom untrusted networks. - Requests with
X-Forwarded-Forare rejected. - Metadata requests require IMDSv2-style tokens; token TTL is
1..21600seconds.