[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-75015":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":25,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":27,"readmeContent":28,"aiSummary":29,"trendingCount":16,"starSnapshotCount":16,"syncStatus":30,"lastSyncTime":31,"discoverSource":32},75015,"gondolin","earendil-works\u002Fgondolin","earendil-works","Experimental Linux microvm setup with a TypeScript Control Plane as Agent Sandbox","https:\u002F\u002Fearendil-works.github.io\u002Fgondolin",null,"TypeScript",1377,92,10,18,0,31,72,216,93,18.91,"Apache License 2.0",false,"main",true,[],"2026-06-12 02:03:31","# Gondolin Agent Sandbox\n\n**Local Linux micro-VMs with programmable network and filesystem control.**\n\nAI agents increasingly run generated code without human review.  That code often\nneeds network access and credentials, which creates exfiltration risk.\n\nGondolin runs that code inside a fast local Linux micro-VM (QEMU by default,\nwith an optional experimental `krun` backend) while keeping network and\nfilesystem access under host-side policy control.  That policy layer can be\ncustomized via JavaScript.\n\n## Quick Example\n\n```ts\nimport { VM, createHttpHooks } from \"@earendil-works\u002Fgondolin\";\n\nconst { httpHooks, env } = createHttpHooks({\n  allowedHosts: [\"api.github.com\"],\n  secrets: {\n    GITHUB_TOKEN: {\n      hosts: [\"api.github.com\"],\n      value: process.env.GITHUB_TOKEN,\n    },\n  },\n});\n\nconst vm = await VM.create({ httpHooks, env });\n\n\u002F\u002F String form runs in \u002Fbin\u002Fsh -lc \"...\"\nconst result = await vm.exec(`\n  curl -sS -f \\\n    -H \"Accept: application\u002Fvnd.github+json\" \\\n    -H \"Authorization: Bearer $GITHUB_TOKEN\" \\\n    https:\u002F\u002Fapi.github.com\u002Fuser\n`);\n\nconsole.log(\"exitCode:\", result.exitCode);\nconsole.log(\"stdout:\\n\", result.stdout);\nconsole.log(\"stderr:\\n\", result.stderr);\n\nawait vm.close();\n```\n\nThe guest only sees a placeholder token. The real secret is injected by the\nhost only for allowed destinations (including `Authorization: Basic ...` flows).\n\n## CLI Quick Start\n\n```bash\nnpx @earendil-works\u002Fgondolin bash\n```\n\nUseful session commands:\n\n```bash\n# List running sessions\nnpx @earendil-works\u002Fgondolin list\n\n# Attach to an existing session\nnpx @earendil-works\u002Fgondolin attach \u003Csession-id>\n\n# Snapshot a running session (stops it)\nnpx @earendil-works\u002Fgondolin snapshot \u003Csession-id>\n\n# Resume from snapshot id\u002Fpath\nnpx @earendil-works\u002Fgondolin bash --resume \u003Csnapshot-id-or-path>\n```\n\nGuest assets (kernel\u002Finitramfs\u002Frootfs plus optional krun boot artifacts,\n~200MB+) are resolved automatically on first use via\n`builtin-image-registry.json` and cached locally. When no image is specified,\nGondolin uses `GONDOLIN_DEFAULT_IMAGE` (default: `alpine-base:latest`).\n\nRequirements:\n\n| macOS                    | Linux (Debian\u002FUbuntu)                         |\n| ------------------------ | --------------------------------------------- |\n| `brew install qemu node` | `sudo apt install qemu-system-arm nodejs npm` |\n\nOptional experimental libkrun backend setup:\n\n```bash\nmake krun-runner\n```\n\nPublished installs of `@earendil-works\u002Fgondolin` also include platform-specific\noptional runner packages for supported targets.\n\nThis stages `libkrun` under `.cache\u002F` (no global install) and builds the local\nrunner helper at `host\u002Fkrun-runner\u002Fzig-out\u002Fbin\u002Fgondolin-krun-runner`.\nOn macOS, the build ad-hoc signs the runner with the\n`com.apple.security.hypervisor` entitlement so Hypervisor.framework access is allowed.\nWhen present, Gondolin auto-detects this runner for `--vmm krun`.\n\nLinux prerequisites for `make krun-runner` (Ubuntu\u002FDebian):\n\n```bash\nsudo apt install \\\n  build-essential curl git make pkg-config clang lld xz-utils \\\n  libclang-dev llvm-dev libcap-ng-dev\n\n# libkrun requires a modern Rust toolchain (edition2024)\ncurl https:\u002F\u002Fsh.rustup.rs -sSf | sh -s -- -y --profile minimal\n. \"$HOME\u002F.cargo\u002Fenv\"\n\n# install Zig 0.16.0 for your Linux architecture\n```\n\nWhen `vmm=krun` is selected, Gondolin requires krun boot assets from the selected\nimage manifest (`assets.krunKernel` and optional `assets.krunInitrd`).\nFor custom kernels\u002Finitrds, provide an explicit `sandbox.imagePath` asset object.\n\n> Linux and macOS are supported. ARM64 is the most tested runtime path today.\n> Linux x86_64 `make krun-runner` is covered by CI smoke builds.\n\n## Feature Highlights\n\n- **Local disposable micro-VMs** for agent turns\u002Ftasks\n- **Programmable HTTP\u002FTLS egress policy** (allowlists + request\u002Fresponse hooks)\n- **Secret injection without guest exposure** via placeholders\n- **Programmable VFS mounts** that allow you to write custom file system behavior in JavaScript.\n- **Ingress gateway** to expose guest HTTP services on host (`--listen`, `vm.enableIngress()`)\n- **Attaching** allows you to attach a shell to an already running VM\n- **SSH support**\n  - host -> guest access (`vm.enableSsh()`)\n  - optional guest -> upstream allowlisted SSH egress (proxied, exec-oriented)\n- **Disk checkpoints (snapshots)** with resume support\n- **Custom image builds** (Alpine-based build pipeline, optional OCI rootfs source)\n- **Configurable DNS behavior** (`synthetic`, `trusted`, `open`), rootfs modes (`readonly`, `memory`, `cow`), and runtime rootfs sizing\n\n## Documentation\n\n- [Introduction](https:\u002F\u002Fearendil-works.github.io\u002Fgondolin\u002F)\n- [CLI](https:\u002F\u002Fearendil-works.github.io\u002Fgondolin\u002Fcli\u002F)\n- [SDK](https:\u002F\u002Fearendil-works.github.io\u002Fgondolin\u002Fsdk\u002F)\n- [Secrets Handling](https:\u002F\u002Fearendil-works.github.io\u002Fgondolin\u002Fsecrets\u002F)\n- [SSH](https:\u002F\u002Fearendil-works.github.io\u002Fgondolin\u002Fssh\u002F)\n- [Custom Images](https:\u002F\u002Fearendil-works.github.io\u002Fgondolin\u002Fcustom-images\u002F)\n- [Architecture Overview](https:\u002F\u002Fearendil-works.github.io\u002Fgondolin\u002Farchitecture\u002F)\n- [VM Backends (QEMU vs krun)](docs\u002Fbackends.md)\n- [Security Design](https:\u002F\u002Fearendil-works.github.io\u002Fgondolin\u002Fsecurity\u002F)\n- [Limitations](https:\u002F\u002Fearendil-works.github.io\u002Fgondolin\u002Flimitations\u002F)\n\n## Repository Guides\n\n- [Host package](host\u002FREADME.md): installation, CLI usage, and SDK examples\n- [Guest sandbox](guest\u002FREADME.md): Zig build and image\u002Finitramfs pipeline\n- [`images\u002F`](images): canonical image release build configs (used by image-release workflow)\n- [Examples](host\u002Fexamples): end-to-end integration examples\n\n\n## Pi Extension\n\nThere is a [Pi + Gondolin extension](host\u002Fexamples\u002Fpi-gondolin.ts) that runs\npi tools inside a micro-VM and mounts your project at `\u002Fworkspace`.\n\n## AI Use Disclaimer\n\nThis codebase has been built with the support of coding agents.\n\n## License and Links\n\n- [Documentation](https:\u002F\u002Fearendil-works.github.io\u002Fgondolin\u002F)\n- [Issue Tracker](https:\u002F\u002Fgithub.com\u002Fearendil-works\u002Fgondolin\u002Fissues)\n- License: [Apache-2.0](https:\u002F\u002Fgithub.com\u002Fearendil-works\u002Fgondolin\u002Fblob\u002Fmain\u002FLICENSE)\n","Gondolin是一个用于在本地Linux微型虚拟机中运行代码的实验性项目，通过TypeScript控制平面实现代理沙箱。它使用QEMU（默认）或可选的`krun`后端来创建快速的本地Linux微虚拟机，并允许对网络和文件系统访问进行主机侧策略控制，这些策略可以通过JavaScript自定义。适用于需要在网络访问和凭据管理方面减少泄露风险的人工智能代理执行场景，确保只有授权的目标才能访问敏感信息。此外，该项目提供了便捷的命令行工具来管理和操作虚拟机实例，支持会话的创建、列出、附加、快照以及恢复等功能。",2,"2026-06-11 03:51:57","high_star"]