{"id":47666488,"url":"https://github.com/hyperlight-dev/hyperagent","last_synced_at":"2026-04-02T12:00:34.755Z","repository":{"id":346207563,"uuid":"1187436631","full_name":"hyperlight-dev/hyperagent","owner":"hyperlight-dev","description":"An AI agent with sandboxed JavaScript execution, powered by Hyperlight micro-VMs and the GitHub Copilot SDK. Ask it to compute things — it writes and runs JS in hardware-isolated VMs with no filesystem, no network, no escape.","archived":false,"fork":false,"pushed_at":"2026-03-22T23:23:03.000Z","size":812,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-23T10:59:15.030Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyperlight-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-20T18:13:13.000Z","updated_at":"2026-03-22T23:07:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hyperlight-dev/hyperagent","commit_stats":null,"previous_names":["hyperlight-dev/hyperagent"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/hyperlight-dev/hyperagent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperlight-dev%2Fhyperagent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperlight-dev%2Fhyperagent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperlight-dev%2Fhyperagent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperlight-dev%2Fhyperagent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperlight-dev","download_url":"https://codeload.github.com/hyperlight-dev/hyperagent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperlight-dev%2Fhyperagent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31305971,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T09:48:21.550Z","status":"ssl_error","status_checked_at":"2026-04-02T09:48:19.196Z","response_time":89,"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":[],"created_at":"2026-04-02T12:00:19.252Z","updated_at":"2026-04-02T12:00:34.715Z","avatar_url":"https://github.com/hyperlight-dev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HyperAgent\n\nAn AI agent with a sandboxed JavaScript executor, powered by [Hyperlight](https://github.com/hyperlight-dev/hyperlight) micro-VMs and the [GitHub Copilot SDK](https://github.com/github/copilot-sdk).\n\nAsk the agent to compute things, and it writes \u0026 runs JavaScript in a hardware-isolated micro-VM — no filesystem, no network, no escape.\n\n\u003e **Warning:** HyperAgent is pre-release software created by AI. Not for production use. Be careful where you run it and what you do with it. Consider running in a container.\n\n## Quick Start\n\n### Prerequisites\n\n- **Linux with KVM**, **Azure Linux with MSHV**, **Windows with WHP**, or **WSL2 with KVM** (hardware virtualization required)\n- **GitHub authentication** (see [below](#github-authentication))\n- **Docker** (for containerized option)\n- **Node.js 22+** (for npm install / source builds only)\n- **Rust + just** (for source builds only — see [Contributing](#contributing))\n\n**NOTE:** HyperAgent does not currently run on macOS [due to this issue](https://github.com/hyperlight-dev/hyperlight/issues/45).\n\n### GitHub Authentication\n\nHyperAgent uses the GitHub Copilot SDK, which requires a GitHub account with Copilot access. Authenticate before running:\n\n```bash\n# Install the GitHub CLI if you don't have it\n# https://cli.github.com/\n\n# Log in to GitHub (select HTTPS, authenticate via browser)\ngh auth login\n\n# Verify it worked\ngh auth status\n```\n\nAlternatively, set `GITHUB_TOKEN` directly:\n```bash\nexport GITHUB_TOKEN=\"ghp_your_token_here\"\n```\n\n### Option 1: Docker (recommended)\n\n```bash\n# Pull the image\ndocker pull ghcr.io/hyperlight-dev/hyperagent:latest\n\n# Run with KVM (Linux / bash)\ndocker run -it --rm \\\n  --device=/dev/kvm \\\n  --group-add $(stat -c '%g' /dev/kvm) \\\n  --user \"$(id -u):$(id -g)\" \\\n  -e HOME=/home/hyperagent \\\n  -e GITHUB_TOKEN=\"$(gh auth token)\" \\\n  -v \"$HOME/.hyperagent:/home/hyperagent/.hyperagent\" \\\n  -v \"$HOME/.hyperagent/tmp:/tmp\" \\\n  -v \"$(pwd)\":/workspace -w /workspace \\\n  ghcr.io/hyperlight-dev/hyperagent:latest\n\n# Run with MSHV (Azure Linux / bash)\ndocker run -it --rm \\\n  --device=/dev/mshv \\\n  --group-add $(stat -c '%g' /dev/mshv) \\\n  --user \"$(id -u):$(id -g)\" \\\n  -e HOME=/home/hyperagent \\\n  -e GITHUB_TOKEN=\"$(gh auth token)\" \\\n  -v \"$HOME/.hyperagent:/home/hyperagent/.hyperagent\" \\\n  -v \"$HOME/.hyperagent/tmp:/tmp\" \\\n  -v \"$(pwd)\":/workspace -w /workspace \\\n  ghcr.io/hyperlight-dev/hyperagent:latest\n```\n\n**Non-interactive mode with environment variables (Linux / bash):**\n\n```bash\n# Set a prompt via env var — the container picks up HYPERAGENT_* and HYPERLIGHT_* automatically\nexport HYPERAGENT_PROMPT=\"Create a summary report of today's top tech news\"\ndocker run -it --rm \\\n  --device=/dev/kvm \\\n  --group-add $(stat -c '%g' /dev/kvm) \\\n  --user \"$(id -u):$(id -g)\" \\\n  -e HOME=/home/hyperagent \\\n  -e GITHUB_TOKEN=\"$(gh auth token)\" \\\n  -e HYPERAGENT_PROMPT \\\n  -v \"$HOME/.hyperagent:/home/hyperagent/.hyperagent\" \\\n  -v \"$HOME/.hyperagent/tmp:/tmp\" \\\n  -v \"$(pwd)\":/workspace -w /workspace \\\n  ghcr.io/hyperlight-dev/hyperagent:latest --auto-approve --profile file-builder\n```\n\n**Non-interactive mode (Windows / PowerShell with WSL2 + KVM):**\n\n```powershell\n$env:HYPERAGENT_PROMPT = \"Create a summary report of today's top tech news\"\ndocker run -it --rm `\n  --device=/dev/kvm `\n  -e HOME=/home/hyperagent `\n  -e GITHUB_TOKEN=\"$(gh auth token)\" `\n  -e HYPERAGENT_PROMPT=\"$env:HYPERAGENT_PROMPT\" `\n  -v \"$HOME/.hyperagent:/home/hyperagent/.hyperagent\" `\n  -v \"$HOME/.hyperagent/tmp:/tmp\" `\n  -v \"${PWD}:/workspace\" -w /workspace `\n  ghcr.io/hyperlight-dev/hyperagent:latest --auto-approve --profile file-builder\n```\n\n\u003e **Environment variables:** `COPILOT_MODEL`, `HYPERAGENT_*`, and `HYPERLIGHT_*` env vars control the model, prompt, and sandbox settings. When using `docker run` directly, pass each with `-e VAR_NAME`. The [wrapper script](scripts/hyperagent-docker) forwards them all automatically.\n\u003e\n\u003e **Tip:** For convenience, the [wrapper script](scripts/hyperagent-docker) auto-detects the hypervisor, handles auth, and forwards all config env vars.\n\n### Option 2: npm package\n\n```bash\n# Install globally\nnpm install -g @hyperlight-dev/hyperagent\n\n# Run (requires KVM/MSHV and GitHub auth)\nhyperagent\n```\n\n### Option 3: Build from source\n\nRequires Node.js 22+, Rust toolchain, and [just](https://github.com/casey/just) task runner.\n\n```bash\n# Clone the repo\ngit clone https://github.com/hyperlight-dev/hyperagent.git\ncd hyperagent\n\n# First-time setup — builds native Rust addons, installs npm packages\njust setup\n\n# Run the agent (tsx transpiles on the fly — no build step needed)\njust start\n\n# Or build a standalone binary\njust binary-release\ndist/bin/hyperagent\n```\n\nKey `just` commands:\n\n| Command | What it does |\n|---------|-------------|\n| `just setup` | First-time setup (build native addons, npm install) |\n| `just build` | Rebuild native addons after Rust changes |\n| `just start` | Run agent with tsx (fast iteration) |\n| `just binary-release` | Build optimised standalone binary to `dist/bin/hyperagent` |\n| `just test` | Run TypeScript test suite |\n| `just check` | Full quality gate (lint + typecheck + test) |\n\nSee [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for the full development guide.\n\n## Usage\n\n```bash\n# Interactive mod\nhyperagent\n\n# With a specific model\nhyperagent --model gpt-4.1\n\n# Non-interactive mode\nhyperagent --prompt \"Calculate the first 100 prime numbers\" --auto-approve\n\n# With skills and profiles\nhyperagent --skill pptx-expert --profile file-builder\n```\n\n### Example Session\n\n```\n  ╔════════════════════════════════════════════════╗\n  ║                                                ║\n  ║    H Y P E R A G E N T                         ║\n  ║       v0.0.0-alpha.362+abc1234                 ║\n  ║                                                ║\n  ║    Hyperlight × Copilot SDK Agent              ║\n  ║    Sandboxed JavaScript Execution              ║\n  ║                                                ║\n  ╚════════════════════════════════════════════════╝\n\n  ⚠  WARNING: Pre-release software created by AI.\n     Not for production use. Be careful where you run it and what you do with it.\n\nYou: Calculate fibonacci(30)\n\n  🔧 Calling execute_javascript...\n  ✅ Result: 832040\n\nThe 30th Fibonacci number is 832040.\n```\n\n### Try These Out\n\n#### Write a Markdown report:\n\n**Linux (bash):**\n```bash\nexport HYPERAGENT_PROMPT=\"Write a report comparing the latest iPhone and Android phones, with a summary table of specs and pros/cons. Write the report as a markdown file and save it to disk.\"\n```\n\n**Windows (PowerShell):**\n```powershell\n$env:HYPERAGENT_PROMPT = \"Write a report comparing the latest iPhone and Android phones, with a summary table of specs and pros/cons. Write the report as a markdown file and save it to disk.\"\n```\n\n```shell\nhyperagent --auto-approve --show-code --verbose\n```\n\n#### Build a PPTX presentation:\n\n**Linux (bash):**\n```bash\nexport HYPERAGENT_PROMPT=\"Research the JWT spec (header, payload, signature). Include:\n- Title slide\n- \"\"What is JWT?\"\" with bullet list of key points\n- Code block showing a decoded JWT structure\n- Flow diagram slide (use arrows and boxes to show auth flow)\n- Security best practices numbered list\n- Common vulnerabilities comparison table\n- Resources/links slide\nUse 'light-clean' theme, minimal transitions.\"\n```\n\n**Windows (PowerShell):**\n```powershell\n$env:HYPERAGENT_PROMPT = @\"\nResearch the JWT spec (header, payload, signature). Include:\n- Title slide\n- \"What is JWT?\" with bullet list of key points\n- Code block showing a decoded JWT structure\n- Flow diagram slide (use arrows and boxes to show auth flow)\n- Security best practices numbered list\n- Common vulnerabilities comparison table\n- Resources/links slide\nUse 'light-clean' theme, minimal transitions.\n\"@\n```\n\n```shell\nhyperagent --auto-approve --show-code --verbose\n```\n\n## CLI Options\n\nRun `hyperagent --help` for full list. See [docs/USAGE.md](docs/USAGE.md) for complete reference.\n\nKey options:\n\n| Flag | Description |\n|------|-------------|\n| `--model \u003cname\u003e` | LLM model (default: `claude-opus-4.6`) |\n| `--prompt \"\u003ctext\u003e\"` | Non-interactive mode: run prompt and exit |\n| `--auto-approve` | Auto-approve all prompts (for scripting) |\n| `--skill \u003cname\u003e` | Load domain expertise (e.g., `pptx-expert`) |\n| `--profile \u003cname\u003e` | Apply resource profile (`file-builder`, `web-research`, etc.) |\n| `--version` | Show version and exit |\n| `--help` | Show all options |\n\n## Slash Commands\n\nType `/help` in the REPL for full list. Key commands:\n\n| Command | Description |\n|---------|-------------|\n| `/model \u003cname\u003e` | Switch models mid-conversation |\n| `/plugin enable \u003cname\u003e` | Enable a plugin (fs-read, fs-write, fetch) |\n| `/config` | Show current configuration |\n| `/new` | Start fresh session |\n| `/exit` | Exit |\n\n## Architecture\n\n```\n┌───────────────────────────────────────────────────────┐\n│                  Interactive REPL                     │\n├───────────────────────────────────────────────────────┤\n│              GitHub Copilot SDK Session               │\n│    streaming | infinite sessions | multi-model        │\n├───────────────────────────────────────────────────────┤\n│                  Tool Gating Layer                    │\n│    (blocks all SDK built-in tools like bash/edit)     │\n├───────────────────────────────────────────────────────┤\n│                   Custom Tools                        │\n│    register_handler, execute_javascript, ask_user     │\n│    manage_plugin, apply_profile, sandbox_help ...     │\n├──────────────────────────┬────────────────────────────┤\n│  Hyperlight Sandbox      │  Plugin System (HOST)      │\n│  ┌────────────────────┐  │                            │\n│  │  QuickJS VM        │  │  - fs-read, fs-write       │\n│  │  - No FS/Net       │\u003c-│  - fetch (SSRF-safe)       │\n│  │  - CPU bounded     │  │  - LLM-audited             │\n│  │  - Memory safe     │  │                            │\n│  └────────────────────┘  │  Runs on Node.js host,     │\n│                          │  not inside the VM.        │\n├──────────────────────────┴────────────────────────────┤\n│              Hyperlight Validation Sandbox            │\n│    (validates generated code before execution)        │\n└───────────────────────────────────────────────────────┘\n```\n\n## Plugins\n\nPlugins extend the sandbox with host capabilities:\n\n| Plugin | Description |\n|--------|-------------|\n| `fs-read` | Read files (path-jailed) |\n| `fs-write` | Write files (path-jailed) |\n| `fetch` | HTTPS fetch (domain allowlist, SSRF protection) |\n\nEnable with `/plugin enable \u003cname\u003e` or via profiles.\n\nSee [docs/PLUGINS.md](docs/PLUGINS.md) for authoring your own plugins.\n\n## Security\n\n- **Hardware isolation**: JavaScript runs in Hyperlight micro-VMs\n- **Tool gating**: SDK tools (bash, edit, etc.) are blocked\n- **Code validation**: LLM-generated code validated before execution\n- **Plugin auditing**: LLM analyzes plugin code before enabling\n- **Path jailing**: File plugins restricted to configured directories\n- **SSRF protection**: Fetch plugin validates DNS and post-connect IPs\n\nSee [SECURITY.md](SECURITY.md) and [docs/SECURITY.md](docs/SECURITY.md) for details.\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [How It Works](docs/HOW-IT-WORKS.md) | User-focused system overview |\n| [Usage Guide](docs/USAGE.md) | Complete CLI and feature reference |\n| [Architecture](docs/ARCHITECTURE.md) | System design and components |\n| [Security Model](docs/SECURITY.md) | Detailed security architecture |\n| [Code Validation](docs/VALIDATION.md) | Pre-execution code validation |\n| [Plugins](docs/PLUGINS.md) | Plugin system and authoring guide |\n| [Skills](docs/SKILLS.md) | Domain expertise system |\n| [Patterns](docs/PATTERNS.md) | Code generation patterns |\n| [Modules](docs/MODULES.md) | ES module system |\n| [Profiles](docs/PROFILES.md) | Resource profiles |\n| [Development](docs/DEVELOPMENT.md) | Development environment setup |\n| [Releasing](docs/RELEASING.md) | Release process |\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.\n\nFor development setup, see [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).\n\n## Releasing\n\nSee [docs/RELEASING.md](docs/RELEASING.md) for release process.\n\n## License\n\nApache 2.0 — see [LICENSE.txt](LICENSE.txt)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperlight-dev%2Fhyperagent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperlight-dev%2Fhyperagent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperlight-dev%2Fhyperagent/lists"}