@desplega.ai/agent-env 0.3.0 → 0.4.0

package/README.md

@@ -20,6 +20,27 @@ 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

package/bin/agent-env.mjs

@@ -12,10 +12,12 @@ 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
@@ -125,6 +127,7 @@ async function main() {
   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' },
@@ -143,6 +146,7 @@ async function main() {
     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; }

package/docs/releases.md

@@ -19,12 +19,15 @@ The `CI` job requires all these jobs to succeed:
 
 | Job | Runtime | Real dependencies |
 | --- | --- | --- |
-| Core | Linux and macOS, Node 22 and latest LTS | Git, public CLI |
+| Core | Linux and macOS, Node 22 and latest LTS | Git, npm, public skills installer, public CLI |
 | Docker | Linux, latest Node LTS | Docker, HTTP, TCP, TLS, sandbox bridge |
 | Compose | Linux, latest Node LTS | Docker Compose |
 | SSH | Linux, latest Node LTS | Dedicated localhost sshd, Docker, Compose, rsync |
 | S3 | Linux, latest Node LTS | Docker Compose, AWS CLI, disposable SeaweedFS |
 
+Core tests install the bundled skill with the real skills installer into a temporary project.
+They verify Codex and Claude Code files and remove the isolated npm cache afterward.
+
 The SSH fixture generates new client and host keys for every job.
 The client pins the generated host key and requires strict host verification.
 The fixture starts its own sshd with password authentication disabled.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-env",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Run development services behind stable localhost addresses.",
   "type": "module",
   "bin": {
@@ -29,6 +29,7 @@
   "files": [
     "bin",
     "src",
+    "skills",
     "README.md",
     "LICENSE",
     "examples",

package/skills/agent-env/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: agent-env
+description: Run and troubleshoot development environments with agent-env, including Docker, Compose, dotenv, SSH, local routing, and persistent data.
+license: MIT
+---
+
+# agent-env
+
+Use the `agent-env` CLI to run development services behind stable localhost addresses.
+These instructions describe CLI version 0.4.0.
+Check `agent-env --help` when the installed version differs from these instructions.
+Run `agent-env skill` to read this guide and its reference offline.
+Run `agent-env skill install` to install the bundled skill for your coding agent.
+
+## Prepare the project
+
+1. Inspect `agent-env.json`, Compose files, and package scripts before changing configuration.
+2. Check `agent-env --version`. If absent, install the CLI with `npm install -g @desplega.ai/agent-env`.
+3. Check `docker info`. Compose projects also require `docker compose version`.
+4. Inspect `agent-env --json list` before choosing an instance name or reusing ports.
+
+The CLI requires macOS or Linux and Node.js 22 or later.
+Installing this skill does not install the CLI or Docker.
+Preserve existing project configuration and the user's selected compute target.
+Use local Docker when no remote target is requested.
+
+## Start and verify
+
+Existing Compose files work directly with `up`.
+For another project without `agent-env.json`, run `agent-env init` to detect its development command.
+Do not overwrite an existing configuration.
+If detection fails, supply the actual project command, image, and port. For example:
+
+```sh
+agent-env init --image node:22-bookworm-slim --port 3000 -- node server.js
+```
+
+Replace `node server.js` with the project's command.
+Native services run in `/workspace`, which contains the checkout.
+Include dependency installation in the command when needed.
+The server must listen on `0.0.0.0` inside its container.
+
+```sh
+agent-env up --name app --local
+agent-env --json list
+agent-env logs app --service web
+agent-env exec app --service web -- node --version
+agent-env ui
+```
+
+Replace `app` and `web` with the chosen instance and service names.
+Choose an exec command supported by the service's image.
+Use returned addresses instead of assuming port 3000.
+Verify a real application response through the returned HTTP URL.
+For PostgreSQL or another TCP service, verify a connection with its native client.
+Report the instance, target, service URLs, verification result, and any remaining failure.
+
+`app.localhost:PORT` addresses one HTTP instance.
+`agent-env use app` selects the instance behind bare `localhost:PORT` and raw TCP ports.
+Changing selection closes existing connections through bare localhost.
+The local daemon must remain running for routing and SSH tunnels.
+
+## Compose and configuration
+
+```sh
+agent-env up --name app --local --compose-file compose.yaml --profile tools
+```
+
+Use only files and profiles that the project defines.
+Repeat `--compose-file` or `--profile` for multiple entries.
+Compose retains builds, health checks, dependencies, named volumes, and internal services.
+Keep secrets in declared `environment`, `env_file`, or Compose secret sources.
+Use `compose.routes` when one service needs aliases for multiple published ports.
+See the [Compose configuration examples](https://github.com/desplega-ai/agent-env/blob/master/examples/compose/README.md).
+
+For a Vite project using native Docker, define `services` in `agent-env.json`:
+
+```json
+{
+  "services": {
+    "web": {
+      "image": "node:22-bookworm-slim",
+      "port": 3000,
+      "containerPort": 3000,
+      "command": "npm ci && npm run dev -- --host 0.0.0.0 --port 3000",
+      "volumes": { "dependencies": "/workspace/node_modules" }
+    }
+  }
+}
+```
+
+Adapt the command to the project. Named volumes retain dependencies and application data.
+Use `agent-env add postgres` or `agent-env add redis` to generate a persistent service configuration.
+For a named environment, include `--env review` when adding its service.
+
+## Dotenv and private values
+
+Automatic file order is `.env`, `.env.local`, `.env.<name>`, then `.env.<name>.local`.
+The last two files apply when `--env NAME` selects a named environment.
+Example files do not load automatically.
+
+```sh
+agent-env up --name review --local --env review
+agent-env up --name app --local --env-file .env.development
+agent-env up --name app --local --no-env-file
+agent-env env set API_TOKEN --from-env MY_API_TOKEN
+agent-env env list
+```
+
+Choose one dotenv selection method. `--env-file` replaces automatic selection and conflicts with `--no-env-file`.
+Do not print dotenv contents or secret values.
+Private values can also enter through stdin: `agent-env env set API_TOKEN < /path/to/private/token-file`.
+Use `--env NAME` consistently for the secret store and startup.
+Stores belong to the current project and selected environment.
+
+Native Docker treats dotenv values literally. It does not expand shell expressions.
+The parent shell enters native containers only through explicit `{ "env": "NAME" }` references.
+Compose retains shell interpolation precedence. Its services must declare container variables through `environment` or `env_file`.
+`--no-env-file` does not disable Compose service `env_file` declarations.
+See [environment precedence and secret references](https://github.com/desplega-ai/agent-env/blob/master/README.md#environments-and-secrets) for detailed configuration.
+
+Saved instances retain resolved values:
+
+- `agent-env up app` resumes saved configuration from any directory.
+- `agent-env up --name app` reads the current project's configuration and reloads edited dotenv files.
+- Environment-only changes recreate Docker or Compose containers and preserve named volumes.
+- Structural changes, such as ports or commands, require `rm app`, then `up --name app` with the intended target.
+
+Do not use `rm --purge` to resolve a configuration mismatch. It deletes managed data.
+
+## Stop and troubleshoot
+
+Use `agent-env down app` to stop services and retain data.
+`agent-env rm app` removes containers but retains volumes and built images.
+`agent-env rm app --purge` also removes managed data and owned Compose image tags.
+Delete data only when that deletion is part of the user's request.
+`agent-env daemon stop` stops routing and synchronization, but leaves containers running.
+Avoid `--all` when working on one project.
+
+| Symptom | Next action |
+| --- | --- |
+| Startup timeout | Inspect `logs`. Check the bind address, port, and health check. Increase `--timeout` for slow initialization. |
+| Old environment values | Run `up --name NAME` from the correct checkout with the intended environment and dotenv options. |
+| Configuration changed | Inspect the change. Use `rm NAME`, then recreate without `--purge` to retain data. |
+| Port conflict | Inspect `list` and the port owner. Change configuration instead of terminating unrelated processes. |
+| Stale remote files | Run `sync NAME`. Check exclusions before expecting credentials or generated directories to transfer. |
+| CLI request timed out | Check `list` and `logs` before retrying. The daemon may still be starting services. |
+
+For a slow saved instance, use `agent-env up app --timeout 900`.
+Startup timeouts accept 1 to 3600 seconds. Compose image builds precede the readiness timeout.
+
+## Additional workflows
+
+Read [remote services and data operations](references/remote-and-data.md) for SSH, Hetzner, HTTPS, snapshots, and worktree forks.
+For Agent Swarm itself, follow the [tested example](https://github.com/desplega-ai/agent-env/blob/master/docs/agent-swarm.md).
+That example uses an explicit private env file, isolated Linux dependencies, and a 900-second startup timeout.

package/skills/agent-env/references/remote-and-data.md

@@ -0,0 +1,140 @@
+# Remote services and data operations
+
+Read only the section needed for the requested operation.
+Keep existing authorization for the selected host and data operation.
+This skill does not authorize paid infrastructure, trust changes, or data deletion by itself.
+
+## Existing SSH hosts
+
+The local machine needs SSH and rsync.
+The remote host needs Docker, rsync, Bash, and `timeout`. Compose projects also need Docker Compose.
+Use an SSH alias or `--ssh-config FILE` for credentials and ports.
+Establish and verify the host key through the normal SSH workflow. Do not disable host verification.
+
+```sh
+agent-env up --name remote --ssh dev-host
+agent-env --json list
+agent-env sync remote
+agent-env logs remote --service web
+agent-env down remote
+agent-env up remote
+```
+
+Replace `dev-host` with the authorized SSH alias or `user@host`.
+Remote source synchronization follows local edits unless startup includes `--no-watch`.
+The daemon reconnects failed SSH tunnels automatically.
+Verify the returned localhost address after startup and after a representative source edit.
+
+Sync excludes `.git`, `node_modules`, `.agent-env`, `.env*`, and common generated directories.
+Root `build` and `dist` directories are excluded. Nested source paths such as `src/build` still transfer.
+Keep other credentials outside the checkout.
+Remote Compose bind mounts, build contexts, and Dockerfiles must remain inside the checkout and pass the sync exclusions.
+Compose secret files use a separate private transfer.
+
+## Owned Hetzner machines
+
+Use this workflow only when the user requests paid infrastructure.
+Check the authenticated `hcloud` context before provisioning.
+
+```sh
+agent-env up --name cloud --cloud hetzner --location hel1
+agent-env down cloud
+agent-env up cloud
+```
+
+`down` powers off the owned machine when no other running instance needs it.
+Powered-off machines still incur charges.
+`agent-env rm cloud --purge` deletes the last instance's owned machine, IP, key, and data.
+Forks share the source machine. Removing one instance preserves its peers.
+Keep the original hcloud context and credential for lifecycle operations.
+If either changes, the CLI refuses access and preserves recovery records.
+Do not delete those records to bypass an error.
+
+The default idle timeout is 30 minutes. `--idle-minutes 0` disables it.
+`--ttl-hours N` sets a destructive expiry for the shared machine and all its instances, including sleeping forks.
+Idle shutdown and expiry require the local daemon to remain running and connected.
+These are not cloud-side schedules. Do not promise cost control after the daemon stops.
+
+## HTTPS and the dashboard
+
+```sh
+agent-env up --name app --local --https --https-port 8443
+agent-env ui --port 4780
+```
+
+Read the actual HTTPS URLs from `agent-env list`.
+The primary HTTP service uses `https://app.localhost:8443`.
+Other HTTP services use `https://app--SERVICE.localhost:8443`.
+The dashboard shows status and recent redacted logs. It accepts local read-only requests.
+
+`agent-env trust` installs the local certificate authority into the OS trust store.
+Run it only when trust installation is authorized. Linux installation requires sudo.
+Certificate creation during `up --https` does not install OS trust.
+For verification without a trust change, use the generated CA:
+
+```sh
+curl --cacert ~/.local/state/agent-env/tls/ca.pem \
+  --resolve app.localhost:8443:127.0.0.1 https://app.localhost:8443/
+```
+
+Use `$AGENT_ENV_HOME/tls/ca.pem` instead when the state directory was overridden.
+Some browsers and runtimes use separate certificate stores.
+
+## Forks
+
+Stop the source before copying database volumes:
+
+```sh
+agent-env down app
+agent-env fork app experiment --worktree ../experiment --branch experiment
+agent-env --json list
+```
+
+This creates a Git worktree, copies source changes and volumes, and starts an independent fork.
+Credentials and generated files are excluded from copied source changes.
+Without worktree options, `fork app experiment` copies data and reuses the source checkout.
+Forks require a new destination name and use the source Docker host.
+Verify that a database write in the fork does not change the source data.
+Resume a saved fork with `agent-env up experiment`, even from another directory.
+
+Instance removal retains worktrees by default.
+`rm NAME --remove-worktree` removes an owned clean worktree.
+`--discard-worktree` also permits removal of changed and ignored files. Use it only for an authorized discard.
+
+## Snapshots and restore
+
+```sh
+agent-env down app
+agent-env snapshot app /existing/backups/checkpoint
+agent-env restore /existing/backups/checkpoint --name restored
+```
+
+Run restore from the intended project checkout with the intended environment options.
+Restore uses current project configuration and creates fresh volumes before startup.
+It verifies archive checksums and refuses existing destination volumes.
+Snapshots contain volume data, not source files or a complete deployable project.
+Unsupported or shared mounts cause an error. Do not add `--omit-mounts` unless the user accepts the missing data.
+
+S3 uses the installed AWS CLI and its configured credentials:
+
+```sh
+agent-env snapshot app s3://my-bucket/checkpoint
+agent-env restore s3://my-bucket/checkpoint --name restored --ssh dev-host
+```
+
+Use a new snapshot prefix. `--endpoint URL` selects compatible object storage.
+S3 stores backups. Running databases still use Docker volumes.
+Snapshots need temporary local disk space. AWS S3 exports are limited to 5 GB per volume.
+For format and ownership details, read the [snapshot documentation](https://github.com/desplega-ai/agent-env/blob/master/docs/snapshots-and-worktrees.md).
+
+## Provider and state boundaries
+
+State defaults to `~/.local/state/agent-env`. `AGENT_ENV_HOME` selects another private directory.
+State can contain environment values and cloud ownership credentials. Do not publish it or treat it as disposable cache.
+For isolated tests, set `AGENT_ENV_HOME` before the first CLI command.
+Remove only the test's resources, then stop its daemon before deleting its state.
+
+The sandbox bridge is available through `--provider sandbox --adapter docker`.
+Custom sandbox adapters are trusted local ESM modules.
+Firecracker and hosted sandbox vendor integrations are not bundled.
+See the [adapter contract](https://github.com/desplega-ai/agent-env/blob/master/src/providers/CLOUD_SANDBOX.md) before proposing a new provider.

package/src/skill.mjs

@@ -0,0 +1,51 @@
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+
+const directory = new URL('../skills/agent-env/', import.meta.url);
+const help = `agent-env skill: instructions for coding agents
+
+  agent-env skill                      Print the bundled guide and reference
+  agent-env skill --json               Print the guide as JSON
+  agent-env skill install              Install the bundled skill into this project
+  agent-env skill install --agent codex --yes
+  agent-env skill install --agent claude-code --global
+
+Install options:
+  --agent NAME                        Select an agent (repeat for multiple agents)
+  -g, --global                        Install across projects
+  -y, --yes                           Accept the skills installer's prompts
+
+Reading needs no network, Docker, or daemon.
+Installation runs npx skills@1.7.6 and requires Node 22.20+ and npm.
+The installer uses the skill files bundled with this CLI version.
+`;
+
+export async function skillCommand(positionals, values, command) {
+  if (values.help) { console.log(help); return; }
+  const [action] = positionals;
+  if (positionals.length > 1 || command.length || action && action !== 'install') {
+    throw new Error('Use agent-env skill or agent-env skill install.');
+  }
+  const allowed = action ? ['agent', 'global', 'yes'] : ['json'];
+  for (const key of Object.keys(values)) {
+    if (!allowed.includes(key)) throw new Error(`Option --${key} is not supported here. Run agent-env skill --help.`);
+  }
+  if (!action) {
+    const guide = await readFile(new URL('SKILL.md', directory), 'utf8');
+    const reference = await readFile(new URL('references/remote-and-data.md', directory), 'utf8');
+    const content = `${guide.replace('(references/remote-and-data.md)', '(#remote-services-and-data-operations)')}\n${reference}`;
+    if (values.json) console.log(JSON.stringify({ name: 'agent-env', content }, null, 2));
+    else process.stdout.write(content);
+    return;
+  }
+  const args = ['--yes', 'skills@1.7.6', 'add', fileURLToPath(directory), '--skill', 'agent-env'];
+  for (const agent of values.agent ?? []) args.push('--agent', agent);
+  if (values.global) args.push('--global');
+  if (values.yes) args.push('--yes');
+  process.exitCode = await new Promise((resolve, reject) => {
+    const child = spawn('npx', args, { stdio: 'inherit' });
+    child.once('error', error => reject(new Error(`Cannot start npx: ${error.message}. Install npm, then retry.`)));
+    child.once('close', code => resolve(code ?? 1));
+  });
+}