# Ghostdock CLI Command-line access to your Ghostdock account — built for agents, but usable by humans too. Authenticate once, then call Ghostdock's tools without leaving the terminal. This document is written for an agent (or human) driving the CLI directly. It is also published at `https://ghostdock.ai/cli.md` so an agent can `curl`/fetch it without cloning this repo. ## Install One binary for macOS, Linux and Windows. Pick one way: ```bash brew install brainchimps/tap/ghostdock # Homebrew (macOS, Linux) curl -fsSL https://ghostdock.ai/install.sh | sh # install script: ~/.local/bin npm install -g ghostdock # npm (also pnpm, bun, yarn) ``` Or run it without installing: `npx ghostdock --help`. Every way installs `gdock` too, a short name for the same CLI. Help and hints use whichever name you typed. With `npx`, use `npx ghostdock`: `npx gdock` does not work. Homebrew sets up tab completion; with the others, run `ghostdock completion install` (`ghostdock login` offers it once). ### Update At most once a day the CLI checks for a newer version and, if there is one, prints the command for how you installed it: `brew upgrade ghostdock`, `ghostdock update` (install script) or `npm install -g ghostdock` (or pnpm's, bun's, yarn's). `npx` always runs the latest version. ### Uninstall Leave the private network first, if this machine joined it: that removes the WireGuard tunnel and the split DNS. Remove the CLI's Docker contexts too (`docker context ls`, then `docker context rm ghostdock--`). ```bash ghostdock network disconnect ``` Then remove the CLI the way you installed it: ```bash brew uninstall ghostdock ``` ```bash rm ~/.local/bin/ghostdock ~/.local/bin/gdock ~/.local/bin/.ghostdock-install # install script ``` ```bash npm uninstall -g ghostdock # or: pnpm remove -g, bun remove -g, yarn global remove ``` None of these touch your login and settings. To remove them too, and the CLI's cache: ```bash rm -rf ~/.config/ghostdock ~/Library/Caches/ghostdock # macOS rm -rf ~/.config/ghostdock ~/.cache/ghostdock # Linux ``` If you ran `ghostdock completion install`, delete the line ending in `# ghostdock tab completion` from `~/.zshrc`, `~/.bashrc` or `~/.bash_profile` (left there, it does nothing without the CLI), or for fish the files `ghostdock.fish` and `gdock.fish` in `~/.config/fish/completions`. ## Output: for people, and `--json` for scripts and agents Every command prints for people by default: one line per event, a symbol, then the message. ``` $ ghostdock vm list ⚓ Marketing site quiet-harbor running ◌ teal-jetty stopped $ ghostdock site publish ./dist ↗ https://foggy-teal-bollard.static.ghostdock.app ✓ Published site foggy-teal-bollard. ``` `⚓` ready, `✓` done, `↗` a URL, `◌` stopped or gone, `✗` failed, `▂▄▆` in progress. Every line carries the name and id the next command needs. Commands that wait show a progress line on stderr while they run. `vm up` says the create's step on it (`Downloading the OS image: 312 of 820 MB`, `Starting the system…`); off a terminal each new step is a line of its own, and `--json` prints none. Starting a VM (`vm up`, `vm start`) prints how long each step took, measured on the server, each step with its own time: ``` $ ghostdock vm start quiet-harbor ⚓ quiet-harbor running ⚓ VM started in 125ms ✓ container started in 3.0s ``` The container line is missing when no container was started, or when the host is older and did not report it. `vm status` prints the same lines for the last start. With `--json` they are the `boot` field: `{ trigger, vm: { startedAt, readyAt, ms }, container: { … } | null }`, or `null` when the command started nothing. **Scripts and agents pass `--json`.** It prints the result as one JSON document on stdout, with every field, and nothing else there. It works on every command and anywhere on the line: ```bash ghostdock vm list --json | jq -r '.vms[].name' ``` - **stdout is the result, stderr is everything else**: notices (`Using organization acme …`), hints and errors. Piping stdout never picks up a notice. - **`✦` is a hint**: what you could do next, set apart by a blank line, with the command to run on its own line below. Never with `--json`. - **Errors** print as `✗ ` on stderr and exit non-zero, with or without `--json`. With `--json`, a failed tool call also prints its error as the result on stdout: `{"error":{"code":"vm_not_found","message":"…","retryable":false,"params":{…}}}`. `code` is stable (the catalog in the API's error docs); `retryable: true` means the same command can work later (capacity, a busy VM, an interrupted create), and the CLI then exits `75` instead of `1`. - **Colour** only on a terminal: piped output and `NO_COLOR=1` get the same text without colour codes. `FORCE_COLOR=1` turns it back on. ## Global flags ``` ghostdock --version ghostdock --base-url ghostdock --json ``` - `--version` / `-v` — print CLI version and exit - `--base-url ` — API origin for this invocation (wins over `GHOSTDOCK_BASE_URL`). The stored login goes only to the server that issued it (see [Credentials file](#credentials-file)) - `--json` — print the result as one JSON document on stdout (see Output above) ## Commands Commands are grouped by resource, like `gh` or `kubectl`: `ghostdock `. ``` ghostdock completion Tab completion for commands, flags, VM names, containers and organizations. ghostdock docker Docker over the private network: a VM's Docker engine from this machine. ghostdock domain ghostdock env Manage organization environment variables and secrets. ghostdock login Sign in and store a device access token for this machine and server… ghostdock logout Revoke the device session and remove stored credentials. ghostdock network The private network: reach your VMs by address and name from this machine. ghostdock organization Organizations you belong to. ghostdock project Deployable projects, their deployments and environment. ghostdock provider Providers of an organization. ghostdock registry Log in to the organization container registry. ghostdock site Sites: static files on the CDN. ghostdock skill List and read Agent Skills (same catalog as MCP skill://index.json). ghostdock snapshot VM snapshots. ghostdock ssh-key SSH keys of your account, for logging in to Servers. ghostdock template ghostdock tools List available agent tools. ghostdock update Update this CLI to the latest release. ghostdock vm Create, run and manage VMs. ghostdock volume Volumes: storage that outlives VMs, attached to them as Docker volumes. ghostdock whoami Show the account this CLI is currently authenticated as. ``` Run `ghostdock --help` at any level for its subcommands or flags, e.g. `ghostdock vm --help` or `ghostdock vm url set --help`. Most commands are generated from the tool catalog — see **Invoking a tool** below. Every command is listed in the [command index](#command-index); [`cli-reference.md`](cli-reference.md) has each one's full description and flags. ### Choosing an organization Every organization-scoped command acts on one organization, taken from the first of: 1. `--org ` on the command 2. the `GHOSTDOCK_ORG` environment variable 3. the default set with `ghostdock organization use `, stored in `~/.config/ghostdock/settings.json` With one organization there is nothing to do: `login` makes it the default, and every command, in any directory, uses it. ```bash ghostdock organization use acme # the default (login sets one when it can) ghostdock vm list # stderr: Using organization acme (default from ~/.config/ghostdock/settings.json) ghostdock vm list --org beta # --org always wins ghostdock organization current # which organization, and where it comes from ghostdock organization use --clear ``` When the organization does not come from `--org`, the command says which one it uses on stderr, so a default never acts silently. The default is stored next to the credentials, so it belongs to the same login. **Scripts and CI should pass `--org` or set `GHOSTDOCK_ORG`** rather than depend on (or change) a stored default, and use the organization id: renaming an organization changes its slug, not its id. ### On a Server `ghostdock` is already there on a Server: the image has a launcher that installs the latest release at first use and updates it once a day (`GHOSTDOCK_NO_AUTO_UPDATE=1` keeps the installed version). It connects to the app the VM belongs to (`GHOSTDOCK_BASE_URL`, set by the platform). Log in with `ghostdock login`, and open the link it prints in your own browser (an agent runs `ghostdock login start`, shows you the link, then runs `ghostdock login finish`). Tab completion works in bash, with nothing to set up. ### Scripts and CI: `GHOSTDOCK_TOKEN` An organization API token (Organization settings → API tokens, for owners and admins) runs the CLI without a person's login. Set it as `GHOSTDOCK_TOKEN`, with `GHOSTDOCK_ORG`: ```bash GHOSTDOCK_TOKEN=ext_ot_… GHOSTDOCK_ORG=acme ghostdock vm list ``` It replaces the stored login for every command and is never refreshed. It acts only in its organization and within its scopes: a command its scopes do not cover fails with the scope it needs, and a revoked or expired token fails with `GHOSTDOCK_TOKEN was refused`. The private network and Docker access (`network`, `docker`) need a person's login. ### `ghostdock login` Ghostdock uses a device-authorization flow: no password is ever typed into the terminal. **Default — print the link and wait:** ```bash ghostdock login # or with a custom timeout (seconds, default 300): ghostdock login --timeout 120 ``` This prints a URL to open in a browser, then polls the server every few seconds until the login is approved, denied, or the timeout elapses. Exits `0` on success, non-zero otherwise. **`login start` / `login finish` — for agents:** an agent sees a command's output only once it ends, so a waiting `login` would hide the link from the user until it times out. Agents log in in two steps: ```bash ghostdock login start # prints the URL and exits 0 at once: show it to the user ghostdock login finish # once they approve: completes that same login ``` `login start` stores the started login next to the credentials (`pending-login.json`, readable by you only) while it is valid (about 15 minutes). Run again before finishing, it prints the same URL. `login finish` waits for that login's approval (at once when it is already approved) and never starts a new one: with no login started, or an expired one, it exits `1` and says to run `login start` again. Plain `login` reuses a started login too. `--wait` from earlier versions is still accepted and changes nothing. **`--code` — paste-code fallback:** If the CLI can't poll (e.g. the browser approval happened on a different machine), the browser's "Having trouble? Show code" link reveals a short one-time code. Redeem it directly: ```bash ghostdock login finish --code ``` On success, credentials are written and the command exits `0`. If the code hasn't been approved yet, it exits `1` — approve it in the browser first. Credentials are stored per machine and per server, in `~/.config/ghostdock/servers//credentials.json` (see [Credentials file](#credentials-file)), so one login works in every directory. It is one login for one server: logging in to another server replaces it, and `login` says so. **Default organization after login.** Once logged in, `login` sets the default organization when that is unambiguous: - `--org ` sets that one, e.g. `ghostdock login --org acme`. If you are not a member of it, no default is set and `login` exits `1`. - A default that is still one of your organizations stays as it is. - With exactly one organization, that one becomes the default. - With several, a person at a terminal picks one from a numbered list (Enter skips). Without a terminal (agents, CI) nothing is asked: `login` lists them and points to `ghostdock organization use`. See [Choosing an organization](#choosing-an-organization) for how commands pick it up. ### `ghostdock logout` ```bash ghostdock logout ``` Revokes the device session on the server (best-effort — still clears local credentials even if the server call fails, e.g. when offline) and deletes the credentials file. The default organization stays. With a `--base-url` or `GHOSTDOCK_BASE_URL` other than the server that issued the login, it sends nothing, keeps the file and exits `1`, naming the command that ends that login. ### `ghostdock whoami` ```bash ghostdock whoami ``` Prints who the stored access token belongs to, by name and email, and which server it talks to (`--json`: `{ "userId": ..., "email": ..., "name": ..., "baseUrl": ... }`). Transparently refreshes an expired access token using the stored refresh token before failing. Exits `1` with a message if not logged in or the session can't be refreshed. ### `ghostdock tools` Lists the tool catalog for the authenticated account: ```bash ghostdock tools # name + description, one per line ghostdock tools --json # the full catalog (including each tool's JSON Schema) as JSON ``` Requires login — prints a hint and exits `1` if there's no valid session. ### `ghostdock skill` Lists and reads **Agent Skills** for the authenticated account — the same catalog MCP clients discover at `skill://index.json` (SEP-2640 / Agent Skills discovery 0.2.0). Prefer resources. The MCP tools `skill_list` and `skill_get` are fallbacks for clients that cannot use `resources/list` and `resources/read` — skip them if those work. ```bash ghostdock skill list # name, description, and skill:// URI per skill ghostdock skill list --json # official discovery index ($schema + skills[]) ghostdock skill get skill://github/SKILL.md # print SKILL.md ghostdock skill get github # same, by name ghostdock skill get org_1/release-notes # organization skill ``` `--json` on `get` prints `{ uri, name, description, markdown }`. If the same name exists in more than one organization, pass the `skill://` URI from the index. Requires login — prints a hint and exits `1` if there's no valid session. ### Invoking a tool Every catalog tool is a command at its own path, with one `--flag` per schema property (`autoWake` -> `--auto-wake`). The one thing a command acts on is positional instead: `ghostdock vm stop `, `ghostdock vm url delete [container:]port`, `ghostdock env get `. The organization is always the `--org` flag, by id or slug: a slug is easier to type, an id keeps working after the organization is renamed (renaming changes the slug). The MCP tool name is the same path joined with underscores: `ghostdock vm url set` calls the `vm_url_set` tool. Run `ghostdock --help` to see a command's full description, its flags and which are required; a group's `--help` lists its commands with one line each. Output is a line per item for people; `--json` prints the tool's result as it comes back over MCP. ```bash ghostdock organization list # • Acme org_123 ghostdock organization list --json # {"organizations": [{"id": "org_123", "name": "Acme", "slug": "acme"}]} ``` Number/boolean flags are parsed from their string form; array/object flags take a raw JSON string (e.g. `--tags '["a","b"]'`). Requires login — prints a hint and exits `1` if there's no valid session, or the server's error message (e.g. "Not a member of this organization") on a `4xx`. The tool list embedded in the CLI binary is generated from the server's tool catalog (`bun run sync:cli`), so `--help` and flag parsing work offline; invoking a tool still requires a network call and a valid session. Command descriptions are short on purpose. Concepts and workflows live in the built-in Agent Skills, the same documents MCP agents read: ```bash ghostdock skill get vm # sources, manifests, lifecycle, providers, URLs and TCP ghostdock skill get vm-boot # processes that must come back after idle-stop ghostdock skill get environment # organization entries, bindings, local entries, secrets ghostdock skill get publishing # sites publish vs projects publish, outcomes, redeploys ``` ### VMs Read `ghostdock skill get vm` before your first VM: what it can boot from, manifests, idle-stop and auto-delete, providers, URLs. Every VM has a name, unique within its organization, and every command that takes a VM accepts it with the organization (`--org`, `GHOSTDOCK_ORG` or the default). Choose it with `--name` (`api`, `my-web-app`: 3–30 lowercase letters, digits and single hyphens), or leave it out for a generated one like `quiet-harbor`. The long `vmId` in `--json` output works too, in the same organization. A name never changes while the VM exists, so scripts, `ssh` logins (`api--acme`) and private addresses (`api.acme.ghostdock.internal`) can keep it; a name in use is refused. Once a VM is deleted, a name you chose can be taken again at once; a generated one is held back for 30 days. The display name is a separate free label, shown next to the name in `vm list`; change it any time. For example, create a VM, expose a URL, then relabel it: ```bash ghostdock vm up --org org_123 --name api --display-name "Marketing site" ghostdock vm url set api 8080 --access public --wake ghostdock vm update api --display-name "Marketing site (staging)" ghostdock vm update api --display-name null # clear it ``` #### Containers in a VM On Ghostdock Cloud a VM runs one Docker engine; everything in it is an ordinary container. Containers are reached the way Docker reaches them, on either kind of VM: `vm container exec` as `docker exec`, `vm container cp` as `docker cp`. ```bash ghostdock vm container list quiet-harbor ghostdock vm container exec quiet-harbor web # a shell, with a terminal ghostdock vm container exec quiet-harbor web -- ls /app # one command ghostdock vm container cp quiet-harbor ./dist web:/app # into the container ghostdock vm container cp quiet-harbor web:/app/log.txt . # out of it ghostdock vm container unlock quiet-harbor web ``` `vm container exec` without a command opens bash (else sh) with a terminal; with one after `--` it runs it with this stdin, without a terminal (as `docker exec -i`), and exits with its code. It runs as `docker exec` does: as the container's `ghostdock.login.user`, else the image's `USER`, else root. Both go straight to the container through Ghostdock, no `ssh` needed; with `--json` a command's output comes back as data. `vm container cp` copies files and folders both ways, of any size, in a stopped container too: into an existing folder a copy keeps its name, elsewhere it takes the name given, a source ending in `/.` copies what is in it, and `-` is a tar on stdin or stdout. A container path without a leading `/` is from the container's `/`. What goes in belongs to the container's root, as with `docker cp`. Tab completion offers the VM's containers as `web:` and the paths in them. `vm command` and `vm shell` land on a Server itself unless a container is named. On a Container host they land in a container: the one named after the VM (`vm command run quiet-harbor web`), else the one running container. With several running the CLI asks which one at the keyboard; without a terminal it fails and lists the names. A shell session lives in its container: name the same container on every `shells` and `commands` call on it. #### Files on a VM One filesystem, two places. No container is the Server, as its login user (the same person `ssh` would be). A container name is that container. ```bash ghostdock vm file list quiet-harbor /srv/app ghostdock vm file read quiet-harbor /etc/hostname ghostdock vm file write quiet-harbor /srv/app/note.txt --content hello ghostdock vm cp quiet-harbor ./dist :/srv/app # into the Server ghostdock vm cp quiet-harbor :/var/log/syslog ./ # out of it ghostdock vm cp quiet-harbor web:/app ./out # out of a container ``` `vm file` carries at most 256 KiB per call, because a tool call is JSON. A larger file, or a folder of any size, is `vm cp`. As with `vm container cp`, the VM comes first and one side is this machine; the other is `:path` for the Server or `web:path` for a container. A relative path, or `~/…`, starts where a login does: the login user's home on the Server, the container's start folder (its login user's home) in a container. Answers name a path in the home as `~/…`, and take it back. Into an existing folder a copy keeps its name, elsewhere it takes the name given, a source ending in `/.` copies what is in it (`:.` is what is in the home), and `-` is a tar on stdin or stdout. ```bash ghostdock vm file write quiet-harbor notes/todo.txt --content hi # ~/notes/todo.txt ghostdock vm cp quiet-harbor ./site :site # into ~/site ``` A Server path goes through Ghostdock's guest agent as the login user, so it works while sshd is down. A write keeps an existing file's mode, a move never replaces what is at its destination, and a delete needs `--recursive` for a folder and never removes `/`, the login user's home or a folder above it. A link to a file is written through, as `docker cp` does. A VM on an older base image takes `vm file` over sshd and answers `vm cp` of a Server path with `guest_needs_newer`: stop and start the VM. `vm container cp` stays `docker cp`: a relative path is from the container's `/`, and it works in a stopped container. A secret belongs in `vm env set`, not in a file these commands write. #### Add a container to a VM `vm container up` runs a template, an image, a Compose file or a Dockerfile in a running VM, as its own Compose project next to the VM's. An image or a Dockerfile is one container named after its service (`nginx`, `redis`), or `--name`; a name in use gets the next free number (`nginx-2`). The source's URLs are made after it runs; a port that already has a URL is refused. ```bash ghostdock vm container up quiet-harbor nginx # a template ghostdock vm container up quiet-harbor --image redis:7 # an image ghostdock vm container up quiet-harbor --compose ./compose.yaml --name stack ghostdock vm container up quiet-harbor --dockerfile ./Dockerfile --name worker ``` A Compose project or a Dockerfile that needs other files (a build context) goes through the Docker context ([`ghostdock docker context`](#ghostdock-docker-context)). #### SSH into a Server SSH is for Servers (`vm up`, any system but `container-host`): you log in to the VM's own sshd, as `ghost`, with passwordless `sudo`. `vm ssh` starts the VM when needed and connects: with your SSH key when one on this machine is in your account, otherwise with a temporary login for 60 minutes. It never asks, so agents and scripts run the same command. Arguments after `--` go to `ssh`: a port forward, or a command to run instead of a shell. ```bash ghostdock vm ssh quiet-harbor # a shell on the Server ghostdock vm ssh quiet-harbor -- -L 5432:localhost:5432 # forward a private port ghostdock vm ssh quiet-harbor -- uname -a # run one command ghostdock vm ssh quiet-harbor --print # show the ssh command ghostdock vm ssh quiet-harbor --config # the ~/.ssh/config block, for VS Code ghostdock vm ssh quiet-harbor --temp # a temporary login, even with a key ghostdock vm ssh quiet-harbor --revoke # end the temporary login ``` With `--json`, `vm ssh` prints the access as data and does not connect. A Container host has no SSH: `vm ssh` says so, and `vm container exec` reaches its containers. With an SSH key in your account, plain `ssh` logs in to the Servers of every organization you belong to, without `vm ssh` and without a token: the username is `--`, or `----` for another Linux user (never `root`). `vm ssh --print` shows that command once you have a key, and `--config` the block that lets VS Code Remote-SSH and `scp` use the VM's name. Without a file, `ssh-key add` asks which key on this machine to add, or generates a new one. ```bash ghostdock ssh-key add # choose a key, or generate a new one ghostdock ssh-key add ~/.ssh/id_ed25519.pub --name laptop # ed25519, ecdsa, RSA ≥ 3072 ghostdock ssh-key list ssh quiet-harbor--acme@ # the host vm ssh --print shows ghostdock ssh-key delete ``` #### VMs that create VMs, sites and volumes A VM can get its own identity (ADR 0058): `GHOSTDOCK_TOKEN` and `GHOSTDOCK_ORG` in its environment, so this CLI works inside it unchanged. The identity sees and manages only what it creates, and may create only the kinds you allow, within their budget: - `--vms-budget cpu=8,memory=32,disk=200` lets it create VMs. `cpu` and `memory` cap the VMs it runs at once: stopped VMs do not count, and every start is checked (ADR 0066). `disk` caps all of them (memory and disk in GiB); `count=4` caps their number too. - `--sites-budget count=20` lets it publish up to 20 sites; `--can-create sites` alone sets no limit. - `--volumes-budget size=500` lets it create volumes whose sizes add up to at most that, attached or not (GiB, or `500G`, `2T`, as `volume create --size`); `count=10` caps their number too. - `--can-create vms,sites,volumes` names the kinds (vms still needs `--vms-budget`, volumes `--volumes-budget`). - `--on-auto-delete delete|release` is required with an identity: what happens to what it created when the VM is removed without anyone deciding (an ephemeral VM's end, auto-delete, its host gone). `release` keeps them as ordinary VMs and sites of the organization. - `--no-identity` gives the VM none, even when its template gives one. `--identity` takes the whole identity as JSON instead of the flags. `vm up` and `vm update` take the same flags; on `vm update` they replace the VM's whole identity. `vm budget ` shows what it may create, what it uses, and what is left (inside the VM, `vm budget` alone shows its own). ```bash ghostdock vm up runner-manager --vms-budget cpu=8,memory=32,disk=200 --on-auto-delete delete ghostdock vm up agent --can-create vms,sites --vms-budget cpu=4,memory=16,disk=80,count=2 --sites-budget count=20 --on-auto-delete release ghostdock vm up db-agent --volumes-budget size=200G,count=4 --on-auto-delete release ghostdock vm budget agent ghostdock vm release runner-1 # an ordinary VM of the organization from now on ghostdock site release bright-otter # the same for a site it published ghostdock vm delete agent --owned-resources release # or delete: what happens to what it owns ghostdock vm update agent --no-identity --owned-resources delete ``` Deleting a VM whose identity still owns VMs or sites, or taking its identity away, needs `--owned-resources delete` (they go too, down the whole tree) or `--owned-resources release`. #### Environment in a VM A VM exports **nothing** by default (unless you boot from an organization snapshot or a source whose labels supply defaults). `environment` has three parts: `organization` (plain same-name opt-ins from the catalogue, see [`ghostdock env`](#ghostdock-env)), `bindings` (slot ← org entry remaps), and `local` (VM-only variables/secrets). A local entry overrides an organization export of the same name. Prefer the CLI when setting secret values so they are not pasted into the agent conversation. ```bash # At create time, in one call: ghostdock vm up --org org_123 \ --environment '{"organization":["VITE_API_URL","BUILD_TOKEN"],"bindings":[{"name":"DATABASE_URL","organization":"PROD_DATABASE_URL"}],"local":[{"name":"API_KEY","value":"sk_live","kind":"secret"}]}' # Afterwards: ghostdock vm env get quiet-harbor ghostdock vm env select quiet-harbor --environment '["VITE_API_URL"]' \ --bindings '[{"name":"DATABASE_URL","organization":"PROD_DATABASE_URL"}]' ghostdock vm env select quiet-harbor --environment '[]' # clears plain + remaps (omit bindings) ghostdock vm env set API_KEY --vm quiet-harbor --value sk_live --kind secret ghostdock vm env delete API_KEY --vm quiet-harbor ``` Values arrive as real environment variables, so read them with `process.env` / `$VAR` inside the VM. **Do not pass secrets in `vm command run` strings** — the command text is retained and readable through `vm command logs`. `vm env get` reports every organization entry (selected + overriddenByLocal) and the VM's own local entries; `vm status` reports just the resolved names. New shell commands and SSH sessions see a change immediately. Processes already running keep the values they booted with until restarted (pass `--restart` to `vm env select` / `vm env set` / `vm env delete` to restart a running VM instead). #### Volumes A volume is the organization's storage that outlives VMs (ADR 0061). A **disk** (the default) is a block device one VM has at a time, for databases and anything with locks; a **shared folder** (`--shared`) is mounted by many VMs at once. In the VM a volume is mounted at its path (default `/mnt/volumes/`) and is a Docker volume of its name, so `docker run -v pgdata:/x` and Compose's `external: true` use it. Deleting a VM never deletes its volumes. ```bash ghostdock volume create pgdata # a disk, 10 GiB ghostdock volume create assets --shared --size 50 # --size in GiB, or 50G, 1T ghostdock volume list ghostdock volume show assets ghostdock volume resize pgdata --size 40 # grow only ghostdock volume delete scratch # refused while attached, naming the VMs ``` ``` NAME KIND SIZE USED ATTACHED TO pgdata disk 20 GiB 3.1 GiB shop-db (rw) assets shared 50 GiB 12 GiB web-1 (rw), web-2 (rw), worker (ro) scratch disk 10 GiB – – ``` Both kinds attach and detach live in a VM that runs; a stopped VM takes the change at its next start. A running VM on an older base image, one started before disks attached live, or one on a Docker host takes a disk at its next start too: the answer says why, the list shows `(rw, next start)` or `(rw, detaches at next start)`, and `ghostdock vm restart ` makes it so now. A detach whose path a process in the VM still uses waits for it, and says who: ``` assets is in use by node (pid 812) in web-1: it detaches when they stop using it, or at the VM's next start ``` Shared folders are slower than a disk for many small files and are not for databases: a read-write one at a database's directory, `/var/lib/docker` or a `node_modules` folder comes with a warning. On Ghostdock Cloud an organization's shared folders are served by its file service on the host, a small VM of its own that starts with the first VM that needs it and stops 10 minutes after the last one; `volume show` says whether it runs. A **host folder** (`--host-folder `, only on a Docker or Incus host) is a folder of the machine itself that its owner listed when the host was set up (`--host-paths`), such as `/srv/media`. `provider list` shows each host's folders. It attaches like a shared folder, to any number of VMs; one listed read-only only attaches read-only. It has no size, one volume per host folder, and Ghostdock never deletes its files: `volume delete` only forgets it. Files of the machine's uid 1000 (usually its first user) belong to `ghost` in the VM. ```bash ghostdock provider list # host folders: media (/srv/media, read-only) ghostdock volume create media --host-folder media ghostdock vm volume attach web-1 media:/srv/media:ro ``` Attach them as Docker does: `-v`/`--volume` is the short form (`volume[:/path][:ro]`), `--mount` the long one (`source=`, `name=` for its name in the VM, `target=`, bare `readonly` and `shared`, `size=`). Both repeat. A volume that does not exist is created on first use, a 10 GiB disk unless `shared` or `size` say otherwise; those two only matter then. A `--mount` with a template's volume `name` replaces the template's, so `--mount source=shop-db-pgdata,name=pgdata` gives a new VM an existing database. ```bash ghostdock vm up --volume pgdata # /mnt/volumes/pgdata, read-write ghostdock vm up --volume assets:/srv/assets:ro ghostdock vm up --mount source=assets,shared,size=50,target=/srv/assets ghostdock vm up postgres --name shop-db-2 --mount source=shop-db-pgdata,name=pgdata ghostdock vm volume attach web-3 assets:/srv/assets:ro ghostdock vm volume detach web-3 assets ``` A volume's files can be looked into without a VM of yours, as on the Volumes page (ADR 0065): list a folder, read a file, copy one out, and write one into a shared folder. A disk is read-only here: its one writer is its VM. Paths are inside the volume, `/` its root. ```bash ghostdock volume file list assets /config ghostdock volume file read assets /config/app.yml ghostdock volume file write assets /config/flag.txt --content on # a shared folder only ghostdock volume cp assets ./app.yml :/config/ # into /config/app.yml ghostdock volume cp pgdata :/PG_VERSION - # to stdout ``` On Ghostdock Cloud a shared folder is read through its file service (started for the call when it is stopped) and a disk through the running VM it is attached to: a disk whose VM is stopped, or attached to none, is refused with `volume_files_vm_stopped` or `volume_files_needs_vm`. On a Docker or Incus host the host reads both itself. One call carries a file of up to 384 KiB out and 256 KiB in; a larger one goes through a VM that has the volume attached (`vm cp`). `volume cp` copies one file: a volume path ending in `/` is a folder it goes into under its own name, and the folder must exist. Every attach says whether it created the volume or attached an existing one; check it, since a typo makes a new, empty volume: ``` ✓ Attached existing volume assets (shared, 50 GiB) to web-3 at /srv/assets, read-only. Live now. ✓ Created volume pgdata (disk, 10 GiB) and attached it to web-1 at /mnt/volumes/pgdata. Live now. ✓ Attached existing volume cache (disk, 10 GiB) to old-1 at /mnt/volumes/cache. old-1 runs an older base image that changes disks only at a start. Attaches at old-1's next start: ghostdock vm restart old-1 Warning: size=80 ignored: assets has 50 GiB. Grow it with ghostdock volume resize assets --size 80 ``` ### Systems, workloads and templates `vm up` takes two independent choices: the **workload** (what runs, optional) and the **system** (what boots). Name one of our systems where a template goes (`vm up desktop`), or any system with `--system`. | System | What boots | |---|---| | `headless` | Server · Headless: the VM's own system, based on Ubuntu 26.04, with sshd, Docker and systemd; `vm ssh` lands on it. **The default with nothing to run** | | `desktop` | Server · Desktop: the same Server with an XFCE desktop in the browser, on its private Desktop URL (2 CPU / 4 GiB by default) | | `container-host` | The platform's lean read-only base that only runs the workload's containers; no SSH. Needs a workload. **The default with something to run**, and on a provider that runs no Servers | | an image ref (`--system`) | Any image labelled `ghostdock.os=true` is a system (a Server); one without the label is refused | The defaults follow one rule: nothing to run is a Server, something to run is a Container host. A template may name its own system, and `--system` wins over both. `headless`, `desktop` and `container-host` are systems, never templates: no template may be called so. `headless` and `desktop` follow their images' stable tags (`ghostdockhq/headless:ubuntu-26.04`, `ghostdockhq/desktop:ubuntu-26.04`), as `nginx` follows `nginx:latest`. To pin one build, give the image's ref instead: `--system ghostdockhq/headless:ubuntu-26.04---`. The workload is at most one of a template (`vm up nginx`), `--image`, `--compose`, `--dockerfile` or `--source`. On a Server it runs as its own Compose project in `/srv/ghostdock/`, exactly as `vm container up` adds one (its URLs, MCPs and forwards with the create's `--urls`, `--mcps`, `--forwards`). On a Container host it is the VM's own project. An image labelled `ghostdock.os=true` is a system, never a workload: `vm up --image ` says to use `--system`. ```bash ghostdock vm up # an empty Server (headless) ghostdock vm up desktop # the same with a desktop ghostdock vm up nginx # nginx on a Container host ghostdock vm up --compose ./compose.yaml # the project on a Container host ghostdock vm up nginx --system headless # nginx inside a full Server ghostdock vm up desktop --image redis # redis on a desktop Server ``` `--snapshot` is a whole VM and brings its own system (not with `--system`). A template brings its source (and maybe its system): the other flags change everything else — `--system`, size, lifecycle, idle time, environment, `--env`, `--urls`, `--forwards`, `--mcps`, `--restart`, `--provider` — but a template together with `--image`, `--compose`, `--dockerfile` or `--source` is refused. A system's name with one of those is fine: `vm up desktop --image redis`. `vm up --source` takes an OCI ref (`{"type":"image","ref":"..."}`, any image, its `ghostdock.*` labels read from its registry), Dockerfile text, inline Compose files, a Compose reference (`oci://…`), a snapshot, or a template by name. What an organization wants to keep — a system, an image, a Dockerfile, a Compose project — is a template (`ghostdock template create`, or the Templates page in the app), and `ghostdock vm up