- Feature Name: mirrord Magic
- Start Date: 2026-02-13
- Last Updated: 2026-02-13
- RFC PR: metalbear-co/rfcs#11
Summary
Add new configuration field under the root config, called “magic”. “magic” would cover features that are enabled by default that help 99% of the users, but might annoy the other 1%. They are magic because they’re not specific use of a feature, but a combination of mirrord features to make a use case easier.
Motivation
Take the use case of using AWS CLI within mirrord. To work properly, it requires:
- unset AWS_PROFILE (and other related env)
- make ~/.aws not found - that specifically was broken in last AWS cli version it seems, so new implementation would be “make tmpdir, use mapping to send aws there”
I anticipate as mirrord gets more edge use cases, we’d have more “magic” logic that we can’t explain into a specific feature, so we can bundle it as a “magic”
Another example would be the Santa cheats I implemented.
Guide-level explanation
User wants to run mirrord exec -t deployment/lala -- bash then aws sts get-caller-identity. We’d like that to work out of the box.
Then, for another user that does something very specific, they’d like to actually use local AWS credentials, so they’d do
{
"magic": {
"aws": "true"
}
}
Would lead to
{
"feature": {
"fs": {
"mapping": {"/Users/aaa/.aws": "/tmp/aws/$0"}
},
"env": {
"unset": ["AWS_PROFILE"]
}
}
}
As we add more features, we’ll enable also "magic": false to turn off all magic.
Reference-level explanation
Add new field under root config called magic. Start with aws magic feature. Have a very full explanation of what the magic does and how it works.
“magic” bundles might change existing configurations that user edits, and one of the motivations behind having those as magic bundles is that
we can alter the configuration in runtime, i.e if user uses feature.env.unset the feature would just magically append it’s value to it, instead of conflicting.
“magic” shouldn’t handle all unknowns or scenarios, and by nature is very specific, so conflicts should be seldom. We’d like to be in a situation where magic works 100% for 90% of our user base, where the other 10% can workaround it with disabling it.
Drawbacks
- Can be hard for users to find themselves
- Testing the magic implementations would be hard
Rationale and alternatives
What other designs have been considered and what is the rationale for not choosing them?
- Just implement the magic with defaults for existing features. Can be complex, and overriding the logic would be hard.