> For the complete documentation index, see [llms.txt](https://metalbear.com/mirrord/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://metalbear.com/mirrord/docs/config/readme.md). # Getting Started mirrord allows for a high degree of customization when it comes to which features you want to enable, and how they should function. All of the configuration fields have a default value, so a minimal configuration would be no configuration at all. The configuration supports [templating](#root-templating), so values can be derived at runtime instead of hardcoded. To use a configuration file in the CLI, use the `-f ` flag. Or if using VSCode Extension or JetBrains plugin, simply create a `.mirrord/mirrord.json` file or use the UI. ## Templating Config files are rendered with the [Tera](https://keats.github.io/tera/) template engine before they are parsed, so Tera's built-in functions and filters all work. On top of those, mirrord provides these variables: * `key` - the [session key](#root-key), either the one you provided or the one mirrord generated for this session. * `git_branch` - the branch checked out in the working directory mirrord was started from. Set `MIRRORD_BRANCH_NAME` to override it; the JetBrains plugin does exactly that, with the branch of the project you have open. mirrord generates a session key for you, and you can reference it as `{{ key }}` in your HTTP filter like so: ```json { "feature": { "network": { "incoming": { "mode": "steal", "http_filter": { "header_filter": "^baggage: .*mirrord-session={{ key }}.*$" } } } } } ``` It also supports setting your git branch as the key, so that each branch gets its own session: ```json { "key": "{{ git_branch }}", "feature": { "network": { "incoming": { "mode": "steal", "http_filter": { "header_filter": "^baggage: .*mirrord-session={{ key }}.*$" } } } } } ``` ### Templating the `key` field The [`key`](#root-key) field is read out of the config file *before* any templating happens, to break the cycle where the key is needed to render templates but is itself defined in the file being rendered. Two consequences: 1. The file has to stay valid JSON/TOML/YAML as written. A double-quoted string inside a `key` template ends the surrounding JSON string early, so the `key` field is silently ignored and mirrord falls back to a generated key, leaving a session that looks healthy but filters on the wrong value. Tera accepts single-quoted string literals, so use those in `key`: `default(value='shared')` rather than `default(value="shared")`. Every other field is rendered before parsing and accepts either quote style. 2. Only variables that don't depend on the key are available there, which today means `git_branch`. ### When a variable is undefined `git_branch` is left out of the context entirely when the branch can't be determined - the directory isn't a git repository, `git` isn't installed, or `HEAD` is detached, which is the usual state in CI. Referencing it then fails the render with ``Variable `git_branch` not found in context``, rather than quietly resolving to an empty string and producing a filter that matches nothing. Give configs that also have to work in those environments a fallback: ```json { "key": "{{ git_branch | default(value='shared') }}" } ``` If you want us to provide any other value, please let us know. ## Examples To help you get started, here are examples of a basic configuration file, and a complete configuration file containing all fields. ### Basic `config.json` ```json { "target": "pod/bear-pod", "feature": { "env": true, "fs": "read", "network": true } } ``` ### Basic `config.json` with templating ```json { "target": "{{ get_env(name="TARGET", default="pod/fallback") }}", "feature": { "env": true, "fs": "read", "network": true } } ``` ### Complete `config.json` Don't use this example as a starting point, it's just here to show you all the available options. ```json { "accept_invalid_certificates": false, "skip_processes": "ide-debugger", "target": { "path": "pod/bear-pod", "namespace": "default" }, "connect_tcp": null, "agent": { "log_level": "info", "json_log": false, "labels": { "user": "meow" }, "annotations": { "cats.io/inject": "enabled" }, "namespace": "default", "image": "ghcr.io/metalbear-co/mirrord:latest", "image_pull_policy": "IfNotPresent", "image_pull_secrets": [ { "name": "secret" } ], "ttl": 30, "ephemeral": false, "communication_timeout": 30, "startup_timeout": 360, "flush_connections": true, "metrics": "0.0.0.0:9000", }, "feature": { "env": { "include": "DATABASE_USER;PUBLIC_ENV", "exclude": "DATABASE_PASSWORD;SECRET_ENV", "override": { "DATABASE_CONNECTION": "db://localhost:7777/my-db", "LOCAL_BEAR": "panda" }, "mapping": { ".+_TIMEOUT": "1000" } }, "fs": { "mode": "write", "read_write": ".+\\.json" , "read_only": [ ".+\\.yaml", ".+important-file\\.txt" ], "local": [ ".+\\.js", ".+\\.mjs" ] }, "network": { "incoming": { "mode": "steal", "http_filter": { "header_filter": "^baggage: .*mirrord-session={{ key }}.*$" }, "port_mapping": [[ 7777, 8888 ]], "ignore_localhost": false, "ignore_ports": [9999, 10000] }, "outgoing": { "tcp": true, "udp": true, "filter": { "local": ["tcp://1.1.1.0/24:1337", "1.1.5.0/24", "google.com", ":53"] }, "ignore_localhost": false, "unix_streams": "bear.+" }, "dns": { "enabled": true, "filter": { "local": ["1.1.1.0/24:1337", "1.1.5.0/24", "google.com"] } } }, "copy_target": { "scale_down": false } }, "operator": true, "kubeconfig": "~/.kube/config", "sip_binaries": "bash", "telemetry": true, "kube_context": "my-cluster" } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://metalbear.com/mirrord/docs/config/readme.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.