@desplega.ai/agent-env 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Desplega Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,365 @@
-# Temporary Holding Version
+<img src="assets/icon.svg" width="64" height="64" alt="agent-env Workspace logo">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# agent-env
+
+Run a development stack locally, over SSH, or on an on-demand Hetzner machine. Open each instance through localhost.
+
+Part of [Desplega Labs](https://desplega.sh), alongside [Agent Swarm](https://github.com/desplega-ai/agent-swarm) and [agent-fs](https://github.com/desplega-ai/agent-fs).
+Released under the [MIT license](LICENSE).
+
+The CLI runs on macOS or Linux with Node 22+, Docker, and a local routing daemon. It has no npm dependencies.
+[Tesser](https://tesser.sh/) inspired the workflow. [Portless](https://github.com/vercel-labs/portless) informed the shared HTTPS proxy and local certificate authority.
+
+## Start
+
+Install the published package:
+
+```sh
+npm install -g @desplega.ai/agent-env
+```
+
+For a source checkout, run `npm link --ignore-scripts --no-audit --no-fund` in this repository instead.
+
+Read the bundled [agent skill](https://github.com/desplega-ai/agent-env/blob/master/skills/agent-env/SKILL.md) or install it into a project:
+
+```sh
+agent-env skill
+agent-env skill install
+agent-env skill install --agent codex --yes
+```
+
+`skill` prints the complete guide offline. Add `--json` for structured output.
+`skill install` runs the skills installer with files bundled in your CLI version.
+To install the latest guide directly from GitHub instead:
+
+```sh
+npx skills add desplega-ai/agent-env --skill agent-env
+```
+
+The skills installer requires Node.js 22.20 or later and lets you choose your coding agents.
+Add `--agent codex` or `--agent claude-code` to select one explicitly.
+Add `-g` for installation across projects. The skill teaches CLI usage and does not install the CLI or Docker.
+It covers local services, Compose, dotenv, SSH, HTTPS, persistent data, and troubleshooting.
+
+```sh
+cd /path/to/project
+agent-env init
+agent-env up --name app --https
+agent-env ui
+```
+
+`init` detects Compose files, package scripts, package managers, and common framework ports.
+It never replaces an existing configuration or edits package scripts.
+For a first dependency installation, use `agent-env up --timeout 900` or set `startupTimeoutSeconds` in `agent-env.json`.
+Compose builds and image downloads finish before its shared readiness timeout begins.
+For an unknown project, supply a command:
+
+```sh
+agent-env init --port 3000 --image node:22-bookworm-slim -- node server.js
+```
+
+For the included example:
+
+```sh
+cd examples/hello
+agent-env up --name demo
+```
+
+Open `http://demo.localhost:3300`. The example also provides Postgres on `localhost:55432` with development-only credentials.
+
+For a full application, use the [Agent Swarm development example](docs/agent-swarm.md).
+
+## Local and remote
+
+```sh
+agent-env up --name local --local
+agent-env up --name remote --ssh user@server
+agent-env use remote
+```
+
+Both instances retain named addresses, such as `local.localhost:3000` and `remote.localhost:3000`.
+`use` selects the instance behind bare `localhost:3000` and raw TCP ports.
+A selection change closes existing connections that used bare localhost. Named HTTP connections remain separate.
+
+SSH targets need Docker, rsync, Bash, and `timeout`. The local machine needs SSH and rsync.
+Use an SSH alias or `--ssh-config FILE` for keys and ports. Existing SSH hosts require verified host keys.
+
+Remote source synchronization starts automatically and follows file edits. Use `--no-watch` for manual synchronization.
+`agent-env sync remote` synchronizes immediately. The daemon reconnects failed SSH tunnels with bounded retry intervals.
+Synchronization excludes Git metadata, dependencies, common build directories, `.agent-env`, and `.env*` files.
+Generated directories such as `build` and `dist` are excluded at the checkout root. Nested source paths such as `src/build` remain available.
+Remote Compose validates bind mounts, build contexts, and Dockerfiles against the same rules.
+Keep other credentials outside the source tree. Explicit Compose secret files use a separate private transfer.
+
+## Compose
+
+Existing `compose.yaml`, `compose.yml`, and `docker-compose.*` files work directly, without `init`.
+
+```sh
+agent-env up --name app --profile tools
+agent-env up --name remote --compose-file compose.yaml --compose-file compose.dev.yaml --ssh my-host
+```
+
+The provider preserves builds, dependencies, health checks, profiles, networks, and named volumes.
+Each instance receives isolated names and loopback backend ports. Original Compose files remain unchanged.
+Internal services remain internal. External volumes and networks survive removal and purge.
+
+Multiple published ports on one service require explicit aliases in `compose.routes`.
+UDP, replicas, host namespaces, custom network allocation, and some deployment features return explicit unsupported-feature errors.
+Remote bind and build paths must remain inside the checkout.
+See the [Compose example and contract](examples/compose/README.md).
+
+## Environments and secrets
+
+`agent-env up` reads `.env` and `.env.local` automatically when those files exist.
+`agent-env up --env review` also reads `.env.review` and `.env.review.local`, in that order.
+A named dotenv file can define an environment without a JSON overlay.
+Files with names such as `.env.example` never load automatically.
+
+```sh
+agent-env up                         # Uses the project's dotenv files
+agent-env up --env review            # Adds the review dotenv files
+agent-env up --env-file .env.custom  # Replaces automatic file selection
+agent-env up --no-env-file           # Disables global dotenv files
+```
+
+For native Docker services, later files override earlier files.
+Private stored values override files, configuration values override the private store, and service values override the project configuration.
+Native Docker treats file values literally. It never executes shell commands or expands `${VARIABLE}` expressions.
+The parent shell enters native containers only through explicit `{ "env": "NAME" }` references.
+
+Compose keeps its own interpolation rules and shell precedence.
+Private stored values and explicit project configuration override the Compose interpolation environment.
+Each Compose service still declares its container variables with `environment` or `env_file`.
+`--no-env-file` disables global dotenv files. It does not disable service `env_file` declarations.
+
+Environment files stay outside remote source synchronization.
+The CLI resolves values locally and sends the required container configuration over SSH.
+Saved instances retain their resolved values. Use `up --name NAME` to load edited files, or `up NAME` to resume saved values.
+For Docker and Compose, environment-only changes recreate containers and retain their named volumes.
+Use `up NAME --timeout 900` to increase the startup timeout of a saved instance.
+
+```sh
+agent-env env set POSTGRES_PASSWORD --from-env MY_DATABASE_PASSWORD
+# Or: agent-env env set POSTGRES_PASSWORD < /path/to/private/password-file
+agent-env env list
+agent-env env unset POSTGRES_PASSWORD
+```
+
+Secret commands accept `--env NAME`. Values stay in a private store outside the checkout.
+The CLI prints secret names only.
+Logs and execution output redact private store values, secret references, and explicit environment references.
+Credential names such as `PASSWORD`, `TOKEN`, and `API_KEY` also trigger redaction, including values loaded from dotenv files.
+Credential URLs and common token formats also trigger redaction. Ordinary ports, hosts, modes, and database names remain readable.
+Store secrets with unusual variable names in the private store, or use an explicit secret reference.
+
+```json
+{
+  "provider": "compose",
+  "compose": { "files": ["compose.yaml"] },
+  "environments": {
+    "review": {
+      "envFiles": [".env.review"],
+      "env": { "POSTGRES_PASSWORD": { "secret": "POSTGRES_PASSWORD" } },
+      "compose": { "profiles": ["tools"] }
+    }
+  }
+}
+```
+
+```sh
+agent-env env set POSTGRES_PASSWORD --env review --from-env MY_DATABASE_PASSWORD
+agent-env up --env review --name review
+```
+
+Values can be strings, `{ "secret": "KEY" }`, or `{ "env": "SHELL_VARIABLE" }`.
+Repeated `--env-file FILE` options select explicit environment files.
+Set `envFiles: []` in `agent-env.json` to disable automatic dotenv files for that configuration.
+
+## Services and caching
+
+```sh
+agent-env add postgres
+agent-env add redis
+agent-env up
+```
+
+Postgres defaults to public port 55432. Redis defaults to 56379. Use `--port` to select another port.
+Both services retain data in named volumes. Postgres receives a generated password in the private environment store.
+Compose projects receive a separate `agent-env.addons.json` override.
+Use `add postgres --env review` to add the service and its secret only to the `review` environment.
+Compose uses a separate override file for each selected environment.
+
+Native Docker projects use this format:
+
+```json
+{
+  "services": {
+    "web": {
+      "image": "node:22-bookworm-slim",
+      "port": 3000,
+      "command": "npm ci && npm run dev -- --host 0.0.0.0",
+      "volumes": { "dependencies": "/workspace/node_modules", "cache": "/root/.npm" }
+    }
+  }
+}
+```
+
+The checkout appears at `/workspace`. `containerPort` defaults to `port`.
+Processes must listen on `0.0.0.0`. The runtime sets `HOST` and `PORT` for native Docker services.
+Services reach each other by service name on the instance network.
+Named volumes retain dependencies and package caches. Docker retains build and image caches.
+
+## Hetzner
+
+Authenticate the installed `hcloud` CLI, then run:
+
+```sh
+agent-env up --name cloud --cloud hetzner --location hel1
+agent-env down cloud
+agent-env up cloud
+agent-env rm cloud --purge
+```
+
+The CLI provisions Docker and Compose, generates dedicated SSH credentials, and pins the host identity before connecting.
+Ownership records and labels protect unrelated machines, keys, and IP addresses.
+Each record also binds to the active hcloud context, API endpoint, and a fingerprint of its credential.
+Changed settings stop cloud operations before resource access. Local keys and ownership records remain available for recovery.
+Older records without this binding require manual recovery in Hetzner. The CLI preserves their local keys.
+`down` stops containers and powers off an otherwise unused owned machine. Its disk remains available for resume.
+Powered-off Hetzner machines still incur charges. `rm --purge` deletes the last instance's owned machine, IP, key, and data.
+A plain `rm` retains the cloud record so `list`, resume, and later purge remain available.
+Forks share their source machine. Removing one fork preserves other instances on that machine.
+
+The default idle timeout is 30 minutes. Use `--idle-minutes 0` to disable it.
+Machine and lifecycle flags require `--cloud hetzner` or a configured cloud provider.
+An explicit `--ssh` or `--local` target overrides a configured cloud target.
+HTTP requests, WebSocket traffic, TCP traffic, source synchronization, and explicit service commands record activity.
+Use `--ttl-hours N` for an explicit destructive expiry.
+Expiry deletes the shared machine and every instance on it, including sleeping forks. It does not wake the machine.
+Failed idle and expiry actions use bounded retry delays.
+**Idle shutdown and expiry require the local daemon to remain running and connected.** They are not cloud-side schedules.
+Keep the same `hcloud` context and credential for a machine's lifecycle.
+The CLI reads effective settings through [hcloud config](https://github.com/hetznercloud/cli/blob/main/docs/reference/manual/hcloud_config_get.md).
+
+## Forks and snapshots
+
+Stop the source before copying database volumes:
+
+```sh
+agent-env down app
+agent-env fork app experiment --worktree ../experiment --branch experiment
+```
+
+This creates a Git worktree, copies current source changes, copies volumes, and starts the fork.
+Credentials and generated files are excluded from copied changes. The source remains unchanged.
+Without `--worktree`, `--branch`, or `--ref`, `fork` copies data and uses the existing source checkout.
+Forks require a new destination name and run on the source Docker host.
+
+Resume a saved fork from any directory:
+
+```sh
+agent-env down experiment
+agent-env up experiment
+```
+
+`up NAME` uses the saved configuration, including resolved secrets and the source path.
+`up --name NAME` loads the current project's configuration and checks it against the saved instance.
+
+```sh
+agent-env snapshot app /existing/backups/checkpoint
+agent-env restore /existing/backups/checkpoint --name restored
+
+agent-env snapshot app s3://my-bucket/checkpoint
+agent-env restore s3://my-bucket/checkpoint --name restored --ssh my-host
+```
+
+Restore uses the current project's configuration and creates fresh volumes before starting services.
+It verifies archive hashes and extraction paths. It refuses existing destination volumes.
+Snapshots contain named volume data. Source files require Git or another backup procedure.
+Compose anonymous volumes require a separate backup or explicit omission. Snapshot export rejects them before archive creation.
+Unsupported or shared mounts cause an error. `--omit-mounts` explicitly excludes them and reports each omission.
+
+S3 uses the installed AWS CLI and its normal credentials. `--endpoint URL` selects compatible storage.
+Each snapshot needs a new prefix. Conditional writes prevent overwrites, and the manifest uploads last.
+A failed upload can leave partial objects for manual inspection. Export uses single-object uploads, limited to 5 GB per volume on AWS S3.
+Archives require temporary local disk space. S3 stores backups, while running databases use Docker volumes.
+See [snapshot format and worktree ownership](docs/snapshots-and-worktrees.md).
+
+## HTTPS and status UI
+
+```sh
+agent-env https --https-port 8443
+agent-env trust
+agent-env ui --port 4780
+```
+
+HTTPS uses a private local CA and one loopback proxy. HTTP/2, HTTP/1.1, and WebSocket upgrades are supported.
+The primary HTTP service uses `https://app.localhost:8443`.
+Other HTTP services use `https://app--SERVICE.localhost:8443`.
+`up --https` enables the proxy during startup.
+
+`trust` explicitly installs the CA in the macOS user keychain or a Debian-based Linux trust store.
+Certificate generation uses a process lock. New certificate authorities restrict signing to localhost names and loopback addresses.
+Linux trust installation requires sudo permission. Some browsers and runtimes maintain separate trust stores.
+For curl without OS trust installation:
+
+```sh
+curl --cacert ~/.local/state/agent-env/tls/ca.pem \
+  --resolve app.localhost:8443:127.0.0.1 https://app.localhost:8443/
+```
+
+The dashboard displays instances, service health, addresses, synchronization state, and redacted logs.
+Automatic refresh is optional and persists in browser storage. The dashboard accepts local read-only requests.
+Application pages contain no injected browser controls.
+
+## Lifecycle and provider boundaries
+
+```sh
+agent-env list
+agent-env logs app --service web
+agent-env exec app --service postgres -- psql -U postgres -d app -c 'select 1'
+agent-env down app
+agent-env rm app --purge
+agent-env daemon stop
+```
+
+`down` retains containers and data. `rm` removes containers and retains volumes and built images.
+`rm --purge` also removes managed volumes and the instance's owned Compose image tags.
+Shared base images and Docker build caches remain available.
+For a removed local instance, recreate it with `up` before purging its retained volumes.
+Changes to ports, images, commands, mounts, or providers require `rm`, then `up`.
+Environment-only changes use `up --name NAME` and preserve volumes.
+`daemon stop` stops routing, synchronization, and lifecycle timers. Containers remain running.
+The next command restores saved routing and enabled UI/HTTPS listeners.
+
+Worktrees remain after instance removal by default.
+`rm NAME --remove-worktree` removes an owned clean worktree.
+Add `--discard-worktree` only when you intend to discard its changed and ignored files.
+
+State defaults to `~/.local/state/agent-env`. `AGENT_ENV_HOME` selects an isolated private state directory.
+State can contain environment values. Back up cloud ownership records and credentials before moving it.
+All application ports bind loopback. Remote traffic travels through SSH.
+
+The [sandbox adapter contract](src/providers/CLOUD_SANDBOX.md) accepts trusted local ESM adapters with explicit capabilities.
+Use `--provider sandbox --adapter docker` for the included bridge.
+No hosted sandbox vendor or Firecracker runtime is bundled. Those require separate adapters.
+Firecracker requires a Linux host with KVM access, a guest kernel, root filesystem, and guest networking.
+See [Firecracker's host requirements](https://github.com/firecracker-microvm/firecracker/blob/main/docs/getting-started.md).
+
+## Verification
+
+```sh
+npm run check
+npm test
+npm run test:e2e
+npm run test:runtime
+npm run test:features
+AGENT_ENV_TEST_SSH=my-host AGENT_ENV_TEST_SSH_CONFIG=/path/to/config npm run test:features
+# Creates and deletes one billed Hetzner machine:
+AGENT_ENV_TEST_CLOUD=1 npm run test:cloud
+```
+
+Tests create isolated resources and remove them afterward. SSH tests use an existing host without provisioning or deleting it.
+The explicit cloud test provisions a temporary machine and verifies credential protection, source sync, fork recreation, sleeping expiry, and resource deletion.
+See [verification evidence](VERIFICATION.md) for completed local, remote, S3, cloud, and UI checks.

package/assets/icon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <path d="M32 4 57 18.5v27L32 60 7 45.5v-27Z" fill="#f59e0b"/>
+  <path d="m32 12 18 10.5-18 10.4-18-10.4Z" fill="#fcd34d"/>
+  <path d="M14 29v12.5l15 8.7V37.7Zm21 8.7v12.5l15-8.7V29Z" fill="#17130c"/>
+</svg>

package/bin/agent-env.mjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import http from 'node:http';
+import { mkdir, open, unlink, rm, stat, readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { join, resolve } from 'node:path';
+import { trustTls } from '../src/tls.mjs';
+import { parseArgs } from 'node:util';
+import { home, socketPath } from '../src/paths.mjs';
+import { loadSpec } from '../src/config.mjs';
+import { initialize } from '../src/init.mjs';
+import { addService } from '../src/goodies.mjs';
+import { setEnvironmentSecret, listEnvironmentSecrets, unsetEnvironmentSecret } from '../src/environments.mjs';
+import { delay } from '../src/system.mjs';
+import { skillCommand } from '../src/skill.mjs';
+
+const help = `agent-env: development services with stable localhost addresses
+
+  agent-env init                       Create agent-env.json
+  agent-env skill [install]            Read or install the bundled agent skill
+  agent-env add postgres | redis       Add a persistent service
+  agent-env up [--ssh user@host]        Start the configured stack
+  agent-env up NAME                    Resume the saved instance from any directory
+  agent-env up --name demo --port 3000 -- node server.js
+  agent-env list                       Show services and addresses
+  agent-env ui                         Open the local status dashboard
+  agent-env https [--https-port 8443]   Enable local HTTPS
+  agent-env trust                      Trust the local certificate authority
+  agent-env use NAME                   Select NAME for bare localhost
+  agent-env logs NAME [--service web]  Read recent service logs
+  agent-env exec NAME [--service db] -- COMMAND [ARGS...]
+  agent-env sync NAME                  Copy local changes to an SSH host
+  agent-env env set KEY [--from-env VAR] Store a secret from stdin or a variable
+  agent-env env list | unset KEY       Manage secret names for --env NAME
+  agent-env snapshot NAME LOCATION     Save stopped volumes locally or to S3
+  agent-env restore LOCATION --name NAME  Restore into a new instance
+  agent-env down NAME | --all          Stop containers and retain data
+  agent-env fork SOURCE DEST [--worktree PATH]  Fork stopped data and optional source files
+  agent-env rm NAME [--purge]          Remove containers, optionally data
+  agent-env daemon stop               Stop routing and retain containers
+
+Options:
+  --name NAME, --port PORT, --image IMAGE, --config FILE, --service NAME, --json
+  --ssh HOST, --ssh-config FILE, --local, --provider NAME, --adapter FILE
+  --cloud hetzner, --cloud-type TYPE, --location LOCATION
+  --idle-minutes MINUTES, --ttl-hours HOURS (require a cloud target)
+  --env NAME, --env-file FILE, --no-env-file, --from-env VARIABLE
+  --version                         Show the installed package version
+  --compose-file FILE, --profile NAME (repeat for multiple files or profiles)
+  --https, --https-port PORT, --no-watch, --timeout SECONDS (startup, default 60)
+  --worktree PATH, --branch BRANCH, --ref REF
+  --endpoint URL, --omit-mounts, --all, --purge
+  --remove-worktree, --discard-worktree (requires --remove-worktree)
+
+Requires Node 22+ and Docker. SSH targets require Docker, rsync, and Bash.
+HTTP supports named hosts and WebSockets. TCP uses the selected instance.
+`;
+function request(message, timeout = message.type === 'resume' ? (message.startupTimeoutSeconds ?? 3600) * 1000 + 120000 : Math.max(600000, (message.spec?.startupTimeoutSeconds ?? 0) * 1000 + 120000)) {
+  return new Promise((resolve, reject) => {
+    const req = http.request({ socketPath, path: '/', method: 'POST', headers: { 'content-type': 'application/json' } }, async response => {
+      try {
+        let body = '';
+        for await (const part of response) body += part;
+        const result = JSON.parse(body);
+        if (result.error) throw Object.assign(new Error(result.error), { exitCode: result.exitCode });
+        resolve(result);
+      } catch (error) { reject(error); }
+    });
+    req.setTimeout(timeout, () => req.destroy(new Error('The daemon request timed out. Check agent-env list before retrying.')));
+    req.on('error', reject);
+    req.end(JSON.stringify(message));
+  });
+}
+async function ensureDaemon() {
+  try { await request({ type: 'ping' }, 1000); return; } catch {}
+  await mkdir(home, { recursive: true, mode: 0o700 });
+  const lock = join(home, 'start.lock');
+  let acquired = false;
+  const deadline = Date.now() + 15000;
+  while (!acquired) {
+    try { await mkdir(lock); acquired = true; }
+    catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      try { await request({ type: 'ping' }, 500); return; } catch {}
+      const info = await stat(lock).catch(() => null);
+      if (info && Date.now() - info.mtimeMs > 20000) { await rm(lock, { recursive: true, force: true }); continue; }
+      if (Date.now() > deadline) throw new Error('The daemon startup lock did not clear. Retry after 20 seconds.');
+      await delay(100);
+    }
+  }
+  try {
+    try { await request({ type: 'ping' }, 500); return; } catch {}
+    await unlink(socketPath).catch(error => { if (error.code !== 'ENOENT') throw error; });
+    const log = await open(join(home, 'daemon.log'), 'a', 0o600);
+    const child = spawn(process.execPath, [fileURLToPath(new URL('../src/daemon.mjs', import.meta.url))], { detached: true, stdio: ['ignore', log.fd, log.fd] });
+    child.unref();
+    await log.close();
+    while (Date.now() < deadline) {
+      try { await request({ type: 'ping' }, 500); return; } catch {}
+      if (child.exitCode !== null) break;
+      await delay(100);
+    }
+    throw new Error(`The daemon did not start. Read ${join(home, 'daemon.log')}.`);
+  } finally { await rm(lock, { recursive: true, force: true }); }
+}
+function display(result, json) {
+  if (json) { console.log(JSON.stringify(result, null, 2)); return; }
+  if (Array.isArray(result)) {
+    if (!result.length) console.log('No instances. Run agent-env up.');
+    for (const item of result) typeof item === 'string' ? console.log(item) : display(item, false);
+  } else if (result.url) console.log(result.url);
+  else if ('output' in result) console.log(result.output);
+  else if (result.message) console.log(result.message);
+  else if (result.name) {
+    console.log(`${result.name} (${result.host}, ${result.connected ? 'connected' : result.running ? 'disconnected' : 'stopped'})`);
+    for (const [name, service] of Object.entries(result.services)) {
+      console.log(`  ${name.padEnd(12)} ${service.httpsUrl ?? service.url ?? 'internal'}${service.selected ? '  [localhost selected]' : ''}${result.status ? `  ${result.status[name]}` : ''}`);
+    }
+    if (result.worktree) console.log(`  Source: ${result.worktree}`);
+    if (result.error) console.log(`  ${result.error}`);
+  }
+  for (const mount of result.omittedMounts ?? []) console.log(`  Omitted ${mount.service}:${mount.target}: ${mount.reason}`);
+  for (const path of result.omittedPaths ?? []) console.log(`  Omitted source file: ${path}`);
+}
+async function main() {
+  const args = process.argv.slice(2);
+  const separator = args.indexOf('--');
+  const command = separator < 0 ? [] : args.splice(separator).slice(1);
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: {
+    agent: { type: 'string', multiple: true }, global: { type: 'boolean', short: 'g' }, yes: { type: 'boolean', short: 'y' },
+    'env-file': { type: 'string', multiple: true }, 'no-env-file': { type: 'boolean' }, 'from-env': { type: 'string' },
+    version: { type: 'boolean', short: 'v' },
+    timeout: { type: 'string' },
+    'remove-worktree': { type: 'boolean' }, 'discard-worktree': { type: 'boolean' }, 'omit-mounts': { type: 'boolean' },
+    cloud: { type: 'string' }, 'cloud-type': { type: 'string' }, location: { type: 'string' }, 'idle-minutes': { type: 'string' }, 'ttl-hours': { type: 'string' },
+    provider: { type: 'string' }, adapter: { type: 'string' }, env: { type: 'string' }, profile: { type: 'string', multiple: true }, 'compose-file': { type: 'string', multiple: true },
+    https: { type: 'boolean' }, 'https-port': { type: 'string' }, 'no-watch': { type: 'boolean' },
+    worktree: { type: 'string' }, branch: { type: 'string' }, ref: { type: 'string' }, endpoint: { type: 'string' },
+    name: { type: 'string' }, port: { type: 'string' }, image: { type: 'string' }, ssh: { type: 'string' },
+    'ssh-config': { type: 'string' }, local: { type: 'boolean' }, config: { type: 'string' }, service: { type: 'string' },
+    json: { type: 'boolean' }, all: { type: 'boolean' }, purge: { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
+  } });
+  const [type, name, destination] = positionals;
+  if (values.version) {
+    const { version } = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+    console.log(values.json ? JSON.stringify({ version }) : version);
+    return;
+  }
+  if (type === 'skill') { await skillCommand(positionals.slice(1), values, command); return; }
+  if (!type || values.help || type === 'help') { console.log(help); return; }
+  if (type === 'trust') { display(await trustTls(), values.json); return; }
+  if (type === 'add') { display(await addService(name, { config: values.config, port: values.port, environment: values.env }), values.json); return; }
+  if (type === 'init') {
+    const result = await initialize({ config: values.config, command, port: values.port, image: values.image });
+    display({ message: `Created ${result.filename}. Run agent-env up.` }, values.json);
+    return;
+  }
+  if (type === 'env') {
+    const options = { cwd: process.cwd(), environment: values.env ?? 'default', key: destination };
+    if (name === 'list') display(await listEnvironmentSecrets(options), values.json);
+    else if (name === 'unset') display({ message: await unsetEnvironmentSecret(options) ? 'Secret removed.' : 'Secret was not set.' }, values.json);
+    else if (name === 'set') {
+      if (!values['from-env'] && process.stdin.isTTY) throw new Error('Provide the secret through stdin or --from-env VARIABLE.');
+      await setEnvironmentSecret({ ...options, ...(values['from-env'] ? { fromEnv: values['from-env'] } : { stdin: process.stdin }) });
+      display({ message: `Stored ${destination} for environment ${options.environment}.` }, values.json);
+    } else throw new Error('Use env set KEY, env list, or env unset KEY.');
+    return;
+  }
+  if (type === 'daemon' && name === 'stop') {
+    const result = await request({ type: 'shutdown' });
+    const deadline = Date.now() + 15000;
+    while (Date.now() < deadline) {
+      try { await request({ type: 'ping' }, 1000); }
+      catch (error) {
+        if (['ENOENT', 'ECONNREFUSED', 'ECONNRESET', 'EPIPE'].includes(error.code)) { display(result, values.json); return; }
+        throw error;
+      }
+      await delay(100);
+    }
+    throw new Error('The daemon is still stopping. Wait for the current operation to finish.');
+  }
+  if (!['up', 'list', 'use', 'logs', 'exec', 'sync', 'down', 'rm', 'fork', 'ui', 'https', 'snapshot', 'restore'].includes(type)) throw new Error(`Unknown command: ${type}. Run agent-env --help.`);
+  if (!['up', 'list', 'ui', 'https', 'restore'].includes(type) && !name && !(values.all && ['down', 'rm'].includes(type))) throw new Error(`Specify an instance name for ${type}.`);
+  if (['fork', 'snapshot'].includes(type) && !destination) throw new Error('Specify a destination name.');
+  if (type === 'exec' && !command.length) throw new Error('Specify a command after --.');
+  if (type === 'restore' && !name) throw new Error('Specify a snapshot directory or S3 URL.');
+  if (values['discard-worktree'] && !values['remove-worktree']) throw new Error('Use --discard-worktree with --remove-worktree.');
+  const message = { type, name, destination, service: values.service, command, all: values.all, purge: values.purge, worktree: values.worktree ? resolve(values.worktree) : undefined, branch: values.branch, ref: values.ref, endpoint: values.endpoint, removeWorktree: values['remove-worktree'], discardWorktree: values['discard-worktree'], omitMounts: values['omit-mounts'] };
+  if (type === 'snapshot' || type === 'restore') {
+    const location = type === 'snapshot' ? destination : name;
+    message.location = location.startsWith('s3://') ? location : resolve(location);
+    message.awsEnv = Object.fromEntries(Object.entries(process.env).filter(([key]) => ['AWS_ACCESS_KEY_ID', 'AWS_SECRET_ACCESS_KEY', 'AWS_SESSION_TOKEN', 'AWS_PROFILE', 'AWS_REGION', 'AWS_DEFAULT_REGION', 'AWS_ENDPOINT_URL_S3', 'AWS_SHARED_CREDENTIALS_FILE', 'AWS_CONFIG_FILE', 'AWS_CA_BUNDLE'].includes(key)));
+  }
+  if (type === 'https') message.port = Number(values['https-port'] ?? 8443);
+  if (type === 'ui') message.port = Number(values.port ?? 4780);
+  if (type === 'up' && name) {
+    if (destination || command.length || Object.keys(values).some(key => !['https', 'https-port', 'json', 'timeout'].includes(key))) throw new Error('Use up NAME without configuration options to resume a saved instance.');
+    message.type = 'resume';
+    if (values.timeout !== undefined) message.startupTimeoutSeconds = Number(values.timeout);
+  } else if (type === 'up' || type === 'restore') {
+    message.spec = await loadSpec(values, command);
+    if (values.provider) message.spec.provider = values.provider;
+    if (values.adapter) message.spec.sandbox = { ...message.spec.sandbox, adapter: values.adapter };
+    if (values['no-watch']) message.spec.watch = false;
+  }
+  await ensureDaemon();
+  if (type === 'up' && !values.json) console.error('Starting services. The first image download can take longer.');
+  const result = await request(message);
+  if (type === 'up' && values.https) {
+    await request({ type: 'https', port: Number(values['https-port'] ?? 8443) });
+    display((await request({ type: 'list' })).find(item => item.name === result.name), values.json);
+  } else display(result, values.json);
+}
+main().catch(error => { console.error(`agent-env: ${error.message}`); process.exitCode = error.exitCode ?? 1; });