# Dory complete agent reference

Version: Dory 0.3.2
Host contract: Apple Silicon Mac, macOS 14 or later
License: GPL-3.0
Local socket: ~/.dory/dory.sock
Docker context: dory
Telemetry: none

## Product model

Dory has three distinct execution surfaces:

1. The shared container engine is one persistent Linux VM that serves the Docker API. Docker containers, images, volumes, networks, Compose, BuildKit, and k3s use this engine.
2. Dory Linux machines are separate persistent arm64 VMs. Managed Debian 13, Ubuntu 24.04 LTS, and Kali rolling Xfce desktops have configurable users and Retina-sharp resizable displays; lightweight Alpine headless machines retain root /bin/sh. Each has its own disk, address, resources, scoped mounts, and snapshots.
3. Agent sandboxes are supported, dedicated Dory Linux VMs created for bounded non-root commands. They have no ambient host files, network, or credentials and are deleted by default.

Do not describe a Dory Linux machine as a container. Inspect its display mode and identity: desktop machines use the selected managed Debian, Ubuntu, or Kali profile with systemd, Xfce, Bash, and a configurable user; headless machines are Alpine-based, root, and /bin/sh.

## Installation and host tools

Recommended install:

    brew install --cask Augani/dory/dory

The Homebrew cask and standard download install Docker Core: Dory.app, the Docker engine and CLI, Compose, Buildx, networking, storage, migration, diagnostics, and recovery. A signed catalog provides removable Kubernetes, Linux Machines, Linux Desktop Runtime, Debian, Ubuntu, and Kali components on the selected `.dorydrive`.

Use Settings > Updates for the normal in-place upgrade. Dory verifies candidate signing, free space,
the selected drive, component compatibility and readable schema path; records the exact prior
app/config/component generation plus a verified snapshot reference; and runs Docker API,
volume-marker, pre-existing container/port, and optional Kubernetes smoke tests on next launch.
Safe replaceable state rolls back automatically on failure. Dory never guesses at a durable-data
downgrade; an unsafe schema rollback produces a guided owner-only recovery export.

    dory upgrade status --json
    dory upgrade recovery --json

Homebrew installations can use `brew upgrade --cask Augani/dory/dory`. Uninstall/reinstall remains
a recovery option and preserves workload data, but it is not the normal upgrade story.

Open Dory once. While doryd is running it reconciles bundled `docker`, `docker compose`, and `dory` tools in ~/.dory/bin and creates the dory Docker context. Installing the Kubernetes component also reconciles `kubectl`. A separate Docker Desktop or Docker CLI install is not required.

`dory install` exists as manual recovery. Do not make it the normal first step.

## Focused components

    dory component list
    dory component install kubernetes
    dory component install linux-machines
    dory component install desktop-debian
    dory component install desktop-ubuntu
    dory component install desktop-kali
    dory component update COMPONENT
    dory component verify COMPONENT
    dory component remove COMPONENT --confirm COMPONENT

Docker Core is required. Desktop distributions add the shared Linux Desktop Runtime automatically. Component catalogs and assets are signature, digest, version, and architecture checked before atomic activation. Removing an optional component deletes only its installed payload. Containers, volumes, cluster state, machine disks, snapshots, and exports remain on the selected data drive.

## Safe operating policy

1. Inspect before writing.
2. Prefer `--json` when a command supports it.
3. Run a dry run before `--apply`.
4. Use the narrowest doctor group or repair target.
5. Treat engine restarts, deletes, volume pruning, network authorization, LAN exposure, and data-drive selection as state changes.
6. `dory repair all --apply` does not restart the engine. A disruptive restart requires an engine or dockerd target and `--restart-engine`.
7. `dory cleanup` is a dry run by default. Volume pruning also requires `--include-volumes`.
8. Collect `dory support bundle --json --active` for a shareable, redacted evidence pack.

Exit codes: 0 success or healthy; 1 unhealthy or incomplete; 2 usage or validation error; 64 unsupported operation.

## Recommended recovery loop

1. Run `dory doctor --json` before modifying runtime state.
2. If the result suggests an action, run the matching `dory repair TARGET --json` dry run.
3. Add `--apply` only when a write is authorized.
4. Re-run the smallest relevant doctor group.
5. Run `dory support bundle --json --active` when evidence must be shared.

## Docker

`dory <docker args...>` passes arguments to Docker against Dory's socket. The standard Docker CLI works too.

    dory ps
    dory build -t app .
    docker context use dory
    docker compose up -d

Stable capabilities include containers, images, Buildx, BuildKit, Compose v2, registries, bind mounts, named volumes, bridge networks, custom IPAM, aliases, and common linux/amd64 images on Apple Silicon through FEX.

The app's Build Activity surface keeps durable history, status, logs, cache use, and cancellation
for builds launched by Dory. It does not claim control of builds launched by unrelated clients.

## Health and evidence

    dory readiness --json
    dory doctor --json
    dory doctor --json --active
    dory doctor --json --only socket,api,docker,context
    dory doctor --json --only network,ports,domains
    dory doctor --json --only mounts,watch,filelock
    dory doctor --json --only disk,memory,helpers
    dory doctor --json --diff

`dory readiness` returns the versioned nine-stage app → doryd → VM → guest agent → data mount →
network → dockerd → host socket/context → Kubernetes contract. Every stage includes reason, timing,
deadline, and the exact non-destructive repair owner and mutation.

Passive health includes per-process physical footprint/FD/thread attribution, guest
used/cache/reclaimable memory, sparse/guest disk and conservative reclaim estimates, dynamically
narrow file-watcher roots and queue pressure, Dory-owned resolver/routes/forwards/PF/UTUN state,
and three-sample early trend warnings.
    dory support bundle --json --active

Doctor groups: socket, api, docker, context, registry, proxy, exposure, network, ports, domains, mounts, filelock, watch, clock, disk, memory, helpers.

Corporate connectivity: `dory network corporate sample|plan|apply|status|disable`. Schema
`dev.dory.corporate-connectivity` v1 separates macOS system/PAC observation, dockerd pull proxy,
the Docker client BuildKit/container proxy, registries, scoped CAs, split DNS and bridge collision
checks. Status includes exact DNS, route, proxy and CA probe provenance; apply is ownership-safe and
reconciles on DHCP/interface/VPN/exit-node changes and wake.

Active probes create a small temporary workload. Support bundles are redacted and use `dev.dory.support.bundle v1`.

## Repair

    dory repair all --json
    dory repair socket --json
    dory repair context --json
    dory repair dns --json
    dory repair routes --json
    dory repair domains --json
    dory repair ports --json
    dory repair dockerd --json
    dory repair engine --json
    dory repair guest-agent --json

Add `--apply` only after reviewing the dry run. Engine and dockerd actions that stop running containers require explicit restart intent.

## Network and routes

Published ports are localhost-only by default. Dory never widens explicit loopback bindings.

    dory routes --json
    dory network --json --active
    dory network --json --probe example.com:443
    dory network authorization-plan --json
    dory network authorize --json --dry-run
    dory network authorize --json --apply
    dory network deauthorize --json --dry-run
    dory network --lan-visible on
    dory network custom-domains
    dory network set-custom-domain admin.myproject.local --published-port 80
    dory network remove-custom-domain admin.myproject.local

Optional authorization manages the selected local-domain resolver, local TLS, ports 80 and 443, and published low TCP ports. Exact and leftmost-wildcard custom domains can route to a published HTTP port after the hostname resolves to 127.0.0.1. `/etc/hosts` needs each exact name; wildcard resolution requires local DNS. LAN and Tailscale access are explicit opt-ins. Containers reach Mac services at `host.dory.internal`.

## Mounts, disk, and cleanup

    dory mount --json
    dory disk --json
    dory cleanup --json
    dory cleanup --json --apply
    dory cleanup --json --apply --include-volumes

Home-directory and /Volumes paths are shared at native Mac paths. Mount diagnostics cover read, write, truncate, path spaces, file locks, host edits, and watcher behavior.

## Data drive

Default: `~/Library/Application Support/Dory/Dory.dorydrive`

    dory data path
    dory data capacity --json
    dory data grow 256 --json
    dory data backup /path/archive.dorybackup
    dory data verify /path/archive.dorybackup
    dory data restore /path/archive.dorybackup /path/new.dorydrive
    dory data use /path/new.dorydrive

The drive contains images, containers, named volumes, networks, machine disks, and snapshots. Growth is supported from 128 GiB to 2 TiB. Shrinking and replacement of an existing destination are refused. Normal uninstall preserves the selected drive.

## Runtime availability

    dory mode show
    dory mode always-on
    dory mode auto-idle
    dory mode battery-saver
    dory mode manual
    dory idle status --json
    dory idle history --json --limit 50
    dory engine status
    dory engine wake
    dory engine sleep

Auto-Idle can be blocked by published ports, pinned projects, or Kubernetes according to user settings.

## Migration

Settings > Migrate & Compare imports from detected Docker-compatible sockets. Users may select all
objects or an exact set of images, volumes, networks, and containers; Dory includes required
dependencies automatically. Selected-scope capacity, collision, and portability checks run before
writes. The transaction rolls back target mutations on failure, re-inventories selected and omitted
source objects before success, and reports requested, automatically selected, imported, verified,
and deliberately omitted objects. Dory never deletes source data.

## Machines

    dory machine ls
    dory machine create NAME
    dory machine start NAME
    dory machine stop NAME
    dory machine delete NAME --confirm NAME
    dory machine shell NAME
    dory machine exec NAME --json -- COMMAND ARG...
    dory machine snapshot NAME --note NOTE
    dory machine restore NAME SNAPSHOT --confirm NAME
    dory machine backup schedule NAME --frequency daily --keep 7 --verify-every 7
    dory machine backup status [NAME]
    dory machine backup run NAME
    dory machine backup remove NAME

The app has separate Linux Desktops and Linux Servers areas. Desktop creation selects Debian 13, Ubuntu 24.04 LTS, or Kali rolling, a login user, CPU, memory, optional development recipe, Mac home sharing, and scoped mounts. Desktop windows render at a true 2x guest framebuffer, follow window resizing, and configure matching Xfce scaling. A new graphical machine requires its matching `desktop-*` component; a headless machine requires `linux-machines`.

The machine command also supports clone, import, export, and snapshot deletion. Destructive Dory
commands repeat the exact target with `--confirm`; restore first creates and reports a retained
pre-restore safety snapshot. Structured execution uses `dev.dory.machine.exec v1`. New machines do
not inherit arbitrary host secrets or files. The app controls a named environment allow-list and
scoped mounts.

Scheduled machine backups are local verified `.dorymachine` recovery bundles. Every run verifies
the archive through the production import path; the first and configured periodic runs boot a
disposable verifier. Consistent snapshot creation briefly stops a running source machine and
restores its prior state. Retention affects only scheduler-owned snapshots and archives, never
manual snapshots. Dory does not provide a managed offsite or S3 backup service.

## Kubernetes

    dory k8s get pods -A
    kubectl get pods -A

Install the Kubernetes component before enabling a cluster. Supported k3s presets are v1.34, v1.35, and v1.36. Switching versions recreates the cluster. The selected k3s image downloads on first cluster creation and remains in Docker storage on the selected data drive.

## Compatibility

    dory compat --json
    dory compat --only vscode,testcontainers
    dory compat --recipe TOOL

Dory targets standard Docker API clients. Product-specific private paths and extensions may not be portable.

## Wait and events

    dory wait engine --until running --timeout 60 --json
    dory wait container NAME --until running --timeout 60 --json
    dory wait machine NAME --until running --timeout 120 --json
    dory events --json --limit 50
    dory events --follow --json

Wait uses `dev.dory.wait v1`. Events use `dev.dory.event v1` and `dev.dory.events v1`.

## MCP

    dory mcp serve
    dory mcp serve --read-only

Transport: stdio. Protocol version: 2025-11-25.

Tools: dory.agent_guide, dory.doctor, dory.compat, dory.engine_status, dory.machine_list, dory.machine_exec, dory.sandbox_run, dory.wait, dory.events.

Use `--read-only` when inspection is sufficient. It blocks machine execution and sandbox writes.
Dory's MCP is a Dory control surface, not a catalog, marketplace, or gateway for third-party MCP
servers.

## Supported sandbox

    dory sandbox run --json --network none --rollback -- COMMAND
    dory sandbox run --json --mount HOST:GUEST:ro -- COMMAND
    dory sandbox run --json --keep --ttl-seconds 3600 -- COMMAND
    dory sandbox run --json --network outbound --allow-network HOST:443 -- COMMAND

A sandbox is a dedicated Dory Linux VM and is deleted by default. Commands run non-root. No host files are visible unless a mount is provided, and mounts default read-only. Network defaults to `none`; `outbound` permits Dory DNS plus explicit destinations; `full` is an explicit unrestricted grant. Secrets and SSH agent access are opt-in and omitted from manifests. CPU, memory, disk, process, FD, wall, rollback, kill, named reuse, and daemon TTL controls are inspectable. Results use `dev.dory.sandbox.run v2`; manifests use `dev.dory.sandbox.manifest v1`.

## Other commands

    dory shell CONTAINER
    dory usb ls

USB host discovery is supported. Attach, detach, and replay are unavailable and fail closed until
the guest USB/IP RPC and dedicated physical qualification exist.
    dory expose PORT --print-command
    dory version

`dory debug` is reserved and unavailable. `dory vm` is an in-process framework engine surface and is not the normal daemon workflow.

## Status boundaries

Supported: Docker, Compose, BuildKit, Build Activity for Dory-launched builds, data-drive backup and
restore, exact-selection transactional migration, verified scheduled local machine backups,
transactional upgrades, Kubernetes presets, managed Debian, Ubuntu, and Kali desktops, Alpine
headless servers, health, repair, corporate network planning, Auto-Idle, agent guide, sandbox VMs,
wait, events, and the local Dory control MCP server.

Preview: in-guest Venus and Vulkan GPU acceleration; use host AI services through
`host.dory.internal` for the supported path.

Unavailable: Intel host release, arbitrary desktop distributions, USB attach/detach/replay, audio
passthrough, managed remote/offsite machine backup, remote workspace UI, image-update automation,
mDNS/multicast relay or general L2 bridging, and a general third-party MCP gateway.

## Canonical links

- Website: https://augani.github.io/dory/
- Source: https://github.com/Augani/dory
- Release: https://github.com/Augani/dory/releases/latest
- Issues: https://github.com/Augani/dory/issues
- Agent JSON: https://augani.github.io/dory/agent-guide.json
- Agent guide: https://augani.github.io/dory/docs/agents.md
- Operations: https://augani.github.io/dory/docs/operations.md
- Compatibility: https://augani.github.io/dory/docs/compatibility.md