{"id":17762300,"url":"https://github.com/xbc5/aegis","last_synced_at":"2026-02-11T04:05:14.223Z","repository":{"id":238191969,"uuid":"796061830","full_name":"xbc5/aegis","owner":"xbc5","description":"Wireguard for Qubes: with fuzzy and random pickers","archived":false,"fork":false,"pushed_at":"2024-05-07T20:50:01.000Z","size":42,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-11T22:39:53.230Z","etag":null,"topics":["qubes","qubes-os","qubesos","vpn","wireguard","wireguard-tunnel","wireguard-vpn","wireguard-vpn-setup"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xbc5.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-04T20:24:58.000Z","updated_at":"2024-05-07T20:49:27.000Z","dependencies_parsed_at":"2024-05-04T21:27:33.823Z","dependency_job_id":"03f79cda-72ec-4c99-9200-7520f3b1ac85","html_url":"https://github.com/xbc5/aegis","commit_stats":null,"previous_names":["xbc5/aegis"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/xbc5/aegis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xbc5%2Faegis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xbc5%2Faegis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xbc5%2Faegis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xbc5%2Faegis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xbc5","download_url":"https://codeload.github.com/xbc5/aegis/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xbc5%2Faegis/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29326910,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-11T03:52:29.695Z","status":"ssl_error","status_checked_at":"2026-02-11T03:52:23.094Z","response_time":97,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["qubes","qubes-os","qubesos","vpn","wireguard","wireguard-tunnel","wireguard-vpn","wireguard-vpn-setup"],"created_at":"2024-10-26T19:58:43.299Z","updated_at":"2026-02-11T04:05:14.209Z","avatar_url":"https://github.com/xbc5.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Aegis\n\nBecause I've been waiting aegis for [Qubes-vpn-support](https://github.com/tasket/Qubes-vpn-support/issues/72) for Qubes 4.2; or perhaps because this script took aegis to write.\n\n## Warning\n\nThis is alpha.\n\n- [x] I hereby consent that this script has permission to brick my machine.\n\n(heads up: it's also in the [LICENSE](LICENSE) agreement)\n\n## Installation\n\nYou **must** set up `dom0` first.\n\n### Using the Installation Script\n\nIf you trust the script enough to run in `dom0`, and you don't mind sending files to `dom0`, then you can use this `build` script there. If you *do* mind, then there are manual steps later in this guide.\n\n```sh\n# start a DispVM\nqvm-run --dispvm=[your-dispvm] xterm\n\n# in the DispVM\nwget https://github.com/xbc5/aegis/archive/refs/tags/v0.1-alpha.tar.gz -O /tmp/aegis.tar.gz\n\n# install into dom0\n# in the dom0 terminal (keep DispVM terminal open)\ncd /tmp\nmkdir aegis # important\nqvm-run --pass-io [the-dispvm-name] 'cat /tmp/aegis.tar.gz' | tar -xvz -C aegis --strip-components=1\nsudo ./aegis/build install\n\n# copy the installer to VMs\nqvm-copy-to-vm [your TemplateVM] ./aegis  # primary TemplateVM\nqvm-copy-to-vm [tun template] ./aegis  # the created DispVM template, or the tun qube if you didn't create one\n\n# run the installer on VMs\nqvm-run --pass-io [your TemplateVM] 'sudo ~/QubesIncoming/dom0/aegis/build install'\nqvm-run --pass-io [tun template] 'sudo ~/QubesIncoming/dom0/aegis/build install'\n\n# at this point, inside the DispVM, you will want to put your Wireguard\n# configs into /usr/local/etc/aegis/confs/; give them names that allow\n# you to fuzzy find over them (e.g. create a semantic directory hierarchy).\n# The file extensions must be .conf.\n\n# run the tun\nqvm-shutdown [my TemplateVM] [tun template] # \u003c-- you MUST do this..\nqvm-start [tun qube] # \u003c-- ..before this\n```\n\nNow you can run `aegis -h` in `dom0` \n\n### What This Script Does\n\nIt will `install` the appropriate files and dependencies into that domain:\n- `TemplateVM`: system deps, and service;\n- `tun-t`: the script, firewall rules, and it will create the config directory;\n- `dom0`: create the qubes (if you agree), install the script, and environment variables.\n\n### Info\n\n#### profile.d\n\nIn `dom0`, the installer creates the `/etc/profile.d/aegis.sh` file, which contains two variables:\n- `TUN_NAME`: the name of the qube that connects the tunnel -- the dom0 script (`aegis`) uses this to target the correct qube;\n- `TERM_EXEC`: a command **prefix** to launch the fuzzy finder in a terminal -- e.g. `TERM_EXEC='xterm -e'` (default) or `TERM_EXEC='kitty bash -c'`. The runtime script injects the command like so: `xterm -e '\u003c\u003ccommand\u003e\u003e'`; so you only need to specify the **prefix**.\n\n**If you do not use the installer**, you must create this file manually:\n```sh\nTUN_NAME='tun'\nTERM_EXEC='xterm -e'\n```\n\n#### Wireguard config files\n\nThe config directory (in the `tun` qube) is `/usr/local/etc/aegis`, and the Wireguard configs live under the `confs` subdirectory: you can install your own configs into there. For now, there's no enforced directory structure, but that may change in the future: one idea that I have is for Wireguard confs to live under `wg`, and eventually (when I get around to supporting it), OpenVPN configs will live under `ovpn`:\n- `/usr/local/etc/aegis/confs/wg/...`\n- `/usr/local/etc/aegis/confs/ovpn/...`\n\n One piece of advice: use a directory structure to distinguish the different classes of your configs -- this will make fuzzy finding (`-c`) over them much easier.. For example:\n- `/usr/local/etc/aegis/confs/wg/proton/secure-core/**/*.conf`\n- `/usr/local/etc/aegis/confs/wg/proton/servers/**/*.conf`\n- `/usr/local/etc/aegis/confs/wg/ivpn/servers/**/*.conf`\n\n### Manual Dom0 Installation (alternative)\n\nYou may not trust the script in `dom0`, so follow these instructions instead.\n\nFirst, create the `profile.d` file (see the `Info` section).\n\nThen create the necessary qubes. Note that you do not *need* to create a `DispVM`, but it's recommended, and it works well:\n```sh\n# DispVM template (calling it tun-t)\nqvm-create tun-t \\\n  --label purple \\\n  --property template_for_dispvms=True\n\nqvm-prefs --set tun-t default_dispvm tun-t\n\n# The usable tunnel VM (calling it tun)\nqvm-create tun \\\n  --label black \\\n  --class DispVM \\\n  --property template=tun-t \\\n  --property default_dispvm=tun-t \\\n  --property provides_network=True\n```\n\nFrom there you will use `tun` as your `netvm`, or perhaps you will connect a firewall to it and use the firewall as the netvm.\n\nYou need to run this against `tun` and/or `tun-t`:\n\n```sh\n# enable the service: this starts the tunnel at boot\nqvm-service -e tun aegis\n\n# allow the aegis script to run (not setting this means that it won't)\nqvm-features tun vm-config.aegis--vmtype 'tunvm'\nqvm-features tun-t vm-config.aegis--vmtype 'tunvm'\n\n# [OPTIONAL] When the service boots, it selects a random config.\n# Use this RegExp pattern to limit selection. This \"filter\" also\n# applies to the -r flag, which selects a config at random.\n#\n# Leave it UNSET if unsure; when unset, it does not limit choices.\n# You can set it (in dom0) at any time via `aegis -p`.\nqvm-features tun vm-config.aegis--conf-pattern '.*'  # .* is the default\n```\n\nUnfortunately, you will need to edit the [dom0--aegis](artifacts/dom0--aegis) script by hand (3 lines):\n```sh\nREMOTE_SCRIPT=\"\u003c\u003cREMOTE_SCRIPT\u003e\u003e\"      # /usr/local/bin\nPROFILE_D=\"\u003c\u003cPROFILE_D_PATH\u003e\u003e\"         # /usr/profile.d/aegis.sh\nFEAT_SEARCH_PAT=\"\u003c\u003cFEAT_SEARCH_PAT\u003e\u003e\"  # vm-config.aegis--conf-pattern\n```\n\nBecomes:\n```sh\nREMOTE_SCRIPT=\"/usr/local/bin\"\nPROFILE_D=\"/etc/profile.d/aegis.sh\"\nFEAT_SEARCH_PAT=\"vm-config.aegis--conf-pattern\"\n```\n\nThen copy it into `/usr/local/bin/aegis` (`aegis` is the file name, not a directory).\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxbc5%2Faegis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxbc5%2Faegis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxbc5%2Faegis/lists"}