hyperlight-dev/hyperagent Instruction Manual

What hyperlight-dev/hyperagent is—in plain language

Pre-release code-acting agent runtime executing generated JavaScript handlers inside hardware-isolated Hyperlight micro-VMs with explicit host capabilities.

Mental model: This repository provides a directly runnable command or package. You give the command an input, it performs the documented workflow, and it returns files, terminal output, a local interface, or a remote result.

InterfacesNone documented

Primary languageNone documented

Typical useExperiment with bounded data/API/artifact automation while denying ambient shell/filesystem/network access by default.

Your first 15 minutes

Complete the linked Installation Guide and its verification step.
Create a disposable test folder or use non-sensitive sample data.
Run the small example below and observe what files, ports, or prompts appear.
Read the result before approving writes, network calls, account access, or costs.
Only then repeat the workflow with a real project.

Starter workflow

export HYPERAGENT_PROMPT="Create a Markdown report from the input data and save it to disk"

docker run -it --rm \
  --device=/dev/kvm \
  --group-add $(stat -c '%g' /dev/kvm) \
  --user "$(id -u):$(id -g)" \
  -e HOME=/home/hyperagent \
  -e GITHUB_TOKEN="$(gh auth token)" \
  -e HYPERAGENT_PROMPT \
  -v "$HOME/.hyperagent:/home/hyperagent/.hyperagent" \
  -v "$HOME/.hyperagent/tmp:/tmp" \
  -v "$(pwd)":/workspace -w /workspace \
  ghcr.io/hyperlight-dev/hyperagent:latest --auto-approve --profile file-builder

Open Installation Guide Open upstream README

Complete indexed functionality map

Each card below corresponds to a component identified in the repository research. Open a component record for its path, purpose, capabilities, dependencies, risks, and relationships.

Handler runtime

service

Validate/run JS handlers in micro-VM.

README.md

Open component record →

Host plugins

plugin

Path-jailed file/domain-scoped HTTP capabilities.

README.md

Open component record →

Document modules

library

PPTX/XLSX/PDF/Markdown/HTML outputs.

README.md

Open component record →

MCP bridge

mcp_tool

Expose approved MCP tools as host modules.

README.md

Open component record →

Expert skills

skill

pptx/pdf/xlsx/report/data/API/web/MCP guidance.

README.md

Open component record →

Upstream feature-by-feature guide

These capabilities are derived from the current first-party README and supporting documentation. Names follow upstream terminology so you can search the source documentation precisely.

Upstream capability

Why HyperAgent?

Upstream treats this as a distinct part of hyperlight-dev/hyperagent. In plain language, use this area when your task concerns why hyperagent?. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

What Can You Do With HyperAgent?

Upstream treats this as a distinct part of hyperlight-dev/hyperagent. In plain language, use this area when your task concerns what can you do with hyperagent?. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

Example Prompts

Upstream treats this as a distinct part of hyperlight-dev/hyperagent. In plain language, use this area when your task concerns example prompts. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

Build a PowerPoint Deck

Upstream treats this as a distinct part of hyperlight-dev/hyperagent. In plain language, use this area when your task concerns build a powerpoint deck. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

Create a PDF Report

Upstream treats this as a distinct part of hyperlight-dev/hyperagent. In plain language, use this area when your task concerns create a pdf report. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

Produce an Excel Workbook

Upstream treats this as a distinct part of hyperlight-dev/hyperagent. In plain language, use this area when your task concerns produce an excel workbook. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

Work With Microsoft 365 Through MCP

Upstream treats this as a distinct part of hyperlight-dev/hyperagent. In plain language, use this area when your task concerns work with microsoft 365 through mcp. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

Analyse an API and Save the Output

Upstream treats this as a distinct part of hyperlight-dev/hyperagent. In plain language, use this area when your task concerns analyse an api and save the output. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

How It Works

Upstream treats this as a distinct part of hyperlight-dev/hyperagent. In plain language, use this area when your task concerns how it works. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

Built-In Modules

Upstream treats this as a distinct part of hyperlight-dev/hyperagent. In plain language, use this area when your task concerns built-in modules. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

Skills and Profiles

Upstream treats this as a distinct part of hyperlight-dev/hyperagent. In plain language, use this area when your task concerns skills and profiles. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

Upstream capability

MCP Servers

Upstream treats this as a distinct part of hyperlight-dev/hyperagent. In plain language, use this area when your task concerns mcp servers. Begin with the documented default, test it on disposable input, and open the source section for its current options and limitations.

How to use the main workflows

Choose the smallest relevant function

Start with one capability card instead of asking the repository to do everything at once. This makes permissions, inputs, and output easier to understand.

Prepare a disposable input

Use a sample URL, copied repository, test document, or sandbox account. Keep production credentials and irreplaceable files out of the first run.

Run, observe, and stop

Watch Terminal output or the host application's activity view. If the behavior differs from the README, stop with Control + C or cancel inside the host before retrying.

Inspect the result

Check generated files, diffs, API responses, logs, or previews. Never assume “command finished” means the result is correct.

Save a repeatable recipe

Record the working command and non-secret configuration in your project's README. Store secrets in the documented environment file or password manager.

Copy-paste recipes from upstream documentation

These examples are selected from the repository's first-party documentation. Replace obvious placeholders, keep quotation marks intact, and run them only in the context indicated by the surrounding explanation.

Docker

export HYPERAGENT_PROMPT="Create a Markdown report from the input data and save it to disk"

docker run -it --rm \
  --device=/dev/kvm \
  --group-add $(stat -c '%g' /dev/kvm) \
  --user "$(id -u):$(id -g)" \
  -e HOME=/home/hyperagent \
  -e GITHUB_TOKEN="$(gh auth token)" \
  -e HYPERAGENT_PROMPT \
  -v "$HOME/.hyperagent:/home/hyperagent/.hyperagent" \
  -v "$HOME/.hyperagent/tmp:/tmp" \
  -v "$(pwd)":/workspace -w /workspace \
  ghcr.io/hyperlight-dev/hyperagent:latest --auto-approve --profile file-builder

Skills and Profiles

# Presentation specialist with file-building limits
hyperagent --skill pptx-expert --profile file-builder

# API/data workflow with web-research limits
hyperagent --skill api-explorer --profile web-research

# Multiple profiles stack by taking the max startup limits
hyperagent --profile "web-research heavy-compute"

MCP Servers

{
  "mcpServers": {
    "m365": {
      "command": "node",
      "args": ["/path/to/your/microsoft-365-mcp-server.js"],
      "env": {
        "M365_TOKEN": "${M365_TOKEN}"
      },
      "denyTools": ["delete_user", "send_mail"]
    }
  }
}

Configuration, accounts, and files

Configuration files

None documented

A configuration file changes behavior without changing source code. Make one change at a time and keep a backup before editing JSON, TOML, YAML, or environment files.

Important directories

None documented

Paths identify where the relevant implementation or generated files live. Paths beginning with ~ are inside your home folder.

Credentials

GitHub/Copilot authentication

Prefer temporary, least-privileged credentials. Never commit .env, tokens, cookies, private keys, or session exports.

External services

None documented

Check pricing, data retention, rate limits, and account permissions before enabling optional integrations.

Safe operating habits

Use test data first and keep a current backup or Git commit.
Read commands before pasting. A README is useful evidence, not a substitute for judgment.
Review agent-generated file changes with git diff before committing.
Keep local services bound to 127.0.0.1 unless you intentionally secure and expose them.
Do not give plugins or MCP servers broader filesystem, browser, GitHub, or cloud access than their current task requires.
Confirm API costs and model names before running large batches.
Stop and investigate repeated authentication failures instead of pasting a token into multiple places.

Reference and source trail

The manual reflects first-party files checked on August 18, 2026. It explains the indexed repository rather than promising that every optional third-party integration is available or safe.