gondolin-exec

Files (1)

• SKILL.md

SKILL.md (first lines)

# Gondolin Exec Skill

Use Gondolin to run commands in a disposable Linux micro-VM. The VM is isolated from the host network and filesystem by default.

## When to Use

- Running untrusted or agent-generated code safely
- Testing software installations without polluting your system
- Isolated build/test environments
- Any task where you want a clean, temporary Linux environment

## Commands Overview

| Command | Purpose |
|---------|---------|
| `exec` | Run a command in a fresh disposable VM |
| `bash` | Start an interactive shell session |
| `list` | List running VM sessions |
| `attach` | Attach to a running VM session |
| `snapshot` | Snapshot a running VM and stop it |
| `image` | Manage local image refs (ls, pull, tag, inspect) |

## Quick Start

```bash
# Run a simple command
pnpx @earendil-works/gondolin exec -- uname -a

# Start an interactive shell
pnpx @earendil-works/gondolin bash

# Mount project and run commands
pnpx @earendil-works/gondolin exec --mount-hostfs "$PWD:/workspace" -- sh -lc 'cd /workspace && npm test'
```

## Core Concepts

### The VM is Disposable
Each `gondolin exec` creates a fresh VM, runs your command, and tears down. Changes don't persist unless you mount host directories. Use `bash` for persistent interactive sessions.

### Network Access is OPEN by Default

- HTTP/HTTPS traffic is allowed by default (no restriction)
- Use `--allow-host` to restrict to specific hosts
- Internal ranges (localhost, 10.x, 192.168.x) are blocked
- DNS is synthetic by default (no upstream DNS)
- This is a security feature - the host mediates all traffic

### Secrets Never Enter the VM
This is Gondolin's key security feature. Use `--host-secret` to inject credentials that the guest can use but never see.

## Exec Command

Run a command in a fresh disposable VM.

```bash
gondolin exec [options] -- CMD [ARGS...]
```

### Options

**VFS Options:**
- `--mount-hostfs HOST:GUEST[:ro]` - Mount host directory (append `:ro` for read-only)
- `--mount-memfs PATH` - Create memory-backed mount
- `--image IMAGE` - Guest image selector (asset dir, build id, or name:tag)
- `--vmm BACKEND` - VM backend: `qemu` (default) or `krun`

**Network Options:**
- `--allow-host HOST` - Allow HTTP requests to host (repeatable)
- `--host-secret NAME@HOST[,HOST...][=VALUE]` - Add secret for specified hosts
- `--dns MODE` - DNS mode: `synthetic` (default), `trusted`, or `open`
- `--dns-trusted-server IP` - Trusted resolver IPv4 (trusted mode)
- `--tcp-map SPEC` - Map guest HOST[:PORT] to upstream HOST:PORT (`GUEST_HOST[:PORT]=UPSTREAM_HOST:PORT`)
- `--ssh-allow-host HOST[:PORT]` - Allow outbound SSH (default port 22)
- `--ssh-agent [SOCK]` - Use ssh-agent for host-side SSH auth
- `--ssh-known-hosts PATH` - OpenSSH known_hosts file for upstream verification
- `--ssh-credential SPEC` - Host-side SSH key (`HOST[:PORT]=PATH` or `USER@HOST[:PORT]=PATH`)
- `--disable-websockets` - Disable WebSocket upgrades

**Other:**
- `--env KEY=VALUE` - Set environment variable (repeatable, for non-secrets)
- `--cwd PATH` - Set working directory

## Bash Command

Start an interactive shell session in a VM. Press `Ctrl-]` to detach.

```bash
gondolin bash [options] [-- COMMAND [ARGS...]]
```

Supports all `exec` options plus:

- `--resume ID_OR_PATH` - Resume from a snapshot ID or .qcow2 path
- `--listen [HOST:PORT]` - Start host ingress gateway (default: 127.0.0.1:0)
- `--ssh` - Enable SSH access via localhost port forward
- `--ssh-user USER` - SSH username (default: root)
- `--ssh-port PORT` - Local listen port (default: 0 = ephemeral)
- `--ssh-listen HOST` - Local listen host (default: 127.0.0.1)

```bash
# Interactive shell with project mounted
gondolin bash --mount-hostfs "$PWD:/workspace"

# Resume from snapshot
gondolin bash --resume 4a8f2b0c
gondolin bash --resume /tmp/my-snapshot.qcow2

# With ingress gateway
gondolin bash --listen 127.0.0.1:3000
```

## List Command

List active VM sessions.

```bash
gondolin list [--all]
```

From skuridin/agent-stuff, Apache-2.0.

More from skuridin/agent-stuff