@pirol/nido 0.2.0 → 0.2.1

package/README.md

@@ -1,50 +1,52 @@
 # nido
 
-CLI für Agenten-Sandboxes, wie im Konzept
-[Agenten-Sandboxes auf OpenShell](../docs/concepts/agent-sandboxes.md)
-beschrieben. Man gibt nido einen Ordner, nido lässt darin einen Agenten
-arbeiten und holt die Ergebnisse zurück. Jede Sandbox läuft in einer eigenen
-Kata-VM.
+Run coding agents and commands in isolated sandboxes. Give nido a folder, it lets an agent work
+on it in a sandbox and brings the results back.
 
-Stand: geschlossene Beta (#686–#688). nido spricht mit `pirol-agents-api`
-unter `https://nido.pirol.ai`. Die API prüft den Pirol-Schlüssel, trennt die
-Kunden und reicht die Aufrufe an das OpenShell-Gateway weiter. Die Doku für
-Kunden steht unter [pirol.ai/docs/sandboxes](https://pirol.ai/docs/sandboxes).
+Every sandbox is its own small virtual machine (Kata Containers) in Frankfurt, run by
+[Pirol](https://pirol.ai).
 
-## Einrichten
+> **Closed beta.** Free during the beta, for invited accounts only, up to 5 sandboxes per account.
+> Ask for access at [hello@pirol.ai](mailto:hello@pirol.ai).
 
-Voraussetzung: Node 20 oder neuer und ein Pirol-Konto, das für die Beta
-freigeschaltet ist (`BETA_ALLOWLIST` in
-[deploy-agents-api.sh](../infra/agent-sandbox/deploy-agents-api.sh)).
+Full documentation: [pirol.ai/docs/sandboxes](https://pirol.ai/docs/sandboxes)
+
+## Install
+
+Requires Node 20 or newer.
 
 ```bash
 npm install -g @pirol/nido
 nido login
 ```
 
-`nido login` läuft wie `kyte login`: Der Browser öffnet pirol.ai, man
-bestätigt, und nido legt den Schlüssel in `~/.nido/config.json` ab (nur für
-den Nutzer lesbar). Ohne Browser hilft `nido login --manual`. In CI reicht
-die Umgebungsvariable `PIROL_API_KEY`. `NIDO_API_URL` zeigt nido auf eine
-andere API, etwa eine lokale.
+`nido login` opens your browser. You confirm with your Pirol account, and nido stores a key in
+`~/.nido/config.json` (readable only by you). Without a browser, use `nido login --manual`. In CI,
+set `PIROL_API_KEY` instead.
 
-Aus dem Repo statt von npm:
+## Run an agent on a folder
 
 ```bash
-cd nido && npm install && npm run build && npm link
+cd my-project
+nido init                   # writes nido.json
+nido secret set anthropic   # once; asks for the key without echo
+nido run
 ```
 
-## Ordner mit `nido.json`
+`nido run`:
 
-```bash
-mkdir survey && cd survey
-cp ~/Downloads/results.csv .
-nido init                       # writes nido.json for Claude Code
-nido secret set anthropic       # once, asks for the key without echo
-nido run
-```
+1. Creates the sandbox if it does not exist yet. The name comes from `name` or the folder name.
+   A new sandbox is ready in about 20 seconds.
+2. Uploads changed files. Unchanged files are not uploaded again; files you deleted locally are
+   deleted in the sandbox too.
+3. Runs the agent and shows each step on one line.
+4. Brings `output/` back. A file you changed locally is not overwritten; the sandbox version is
+   saved next to it, for example as `report.remote.md`.
 
-`nido.json`:
+The sandbox keeps running afterwards. The next `nido run` reuses it, `nido run --fresh` starts
+over. `nido pull` fetches `output/` again.
+
+### nido.json
 
 ```json
 {
@@ -57,40 +59,23 @@ nido run
 }
 ```
 
-Was `nido run` macht:
-
-1. Sandbox anlegen, falls es sie noch nicht gibt. Der Name kommt aus
-   `name` oder dem Ordnernamen. Ein neuer Start dauert etwa 20 Sekunden.
-2. Geänderte Dateien hochladen. nido merkt sich die Hashes in
-   `.nido/state.json`. Unveränderte Dateien gehen nicht noch einmal hoch,
-   lokal gelöschte verschwinden auch in der Sandbox.
-3. Den Agenten starten. Bei Claude zeigt nido jeden Schritt in einer Zeile.
-4. `output/` zurückholen. Neue Dateien landen im Ordner. Eine Datei, die
-   man lokal geändert hat, überschreibt nido nicht. Die Fassung aus der
-   Sandbox heißt dann zum Beispiel `report.remote.md`.
-
-Die Sandbox bleibt danach stehen. Der nächste `nido run` nutzt sie weiter,
-`nido run --fresh` fängt neu an.
-
-Statt eines Agenten geht auch ein Befehl, das braucht keinen Schlüssel:
+Instead of an agent, run any command. It needs no key:
 
 ```json
 { "command": "python analyze.py", "output": "output/" }
 ```
 
-Felder:
-
-| Feld | Bedeutung |
-|---|---|
-| `agent` | `claude`, weitere folgen |
-| `task` | Auftrag an den Agenten |
-| `command` | statt `agent`: Befehl als Text (läuft in bash) oder Liste |
-| `name` | Name der Sandbox, sonst der Ordnername |
-| `image` | eigenes Image, sonst das OpenShell-Community-Image mit Claude Code, Codex und OpenCode |
-| `files.exclude` | Muster wie in `.gitignore`. `.git` und `.nido` bleiben immer draußen |
-| `secrets` | Namen von Secrets, nie die Werte |
-| `network` | Hosts, die die Sandbox auf Port 443 erreichen darf. Sonst ist das Netz zu |
-| `output` | Ordner, den nido zurückholt, Standard `output/` |
+| Field | Meaning |
+| --- | --- |
+| `agent` | `claude`; more will follow |
+| `task` | What the agent should do |
+| `command` | Instead of `agent`: a command as a string (runs in bash) or a list |
+| `name` | Sandbox name; defaults to the folder name |
+| `image` | Your own container image; defaults to an image with Claude Code, Codex and OpenCode |
+| `files.exclude` | Patterns like in `.gitignore`; `.git` and `.nido` are always excluded |
+| `secrets` | Names of stored secrets, never values |
+| `network` | Hosts the sandbox may reach on port 443; everything else is blocked |
+| `output` | Folder that comes back after the run; default `output/` |
 
 ## Secrets
 
@@ -102,14 +87,10 @@ nido secret ls
 nido secret rm github
 ```
 
-Der Wert geht per HTTPS an die API und von dort über eine
-Umgebungsvariable an das Gateway, nie als Argument. Lesen kann ihn danach
-niemand mehr, auch der Kunde nicht.
-In der Sandbox steht nur ein Platzhalter. Der Proxy von OpenShell setzt den
-echten Wert erst beim Aufruf ein, und nur für die Hosts des Dienstes, etwa
-`api.anthropic.com`. Andere Namen kennt nido noch nicht.
+A secret is stored once and can never be read again, not even by you. Inside the sandbox the agent
+only sees a placeholder; the real value is added on the way to the provider's API.
 
-## Weitere Befehle
+## More commands
 
 ```bash
 nido create shop --secret anthropic --network pypi.org
@@ -120,26 +101,27 @@ nido cp shop:/sandbox/work/output ./out
 nido logs shop
 nido stop shop && nido start shop
 nido rm shop
+nido whoami
+nido logout
 ```
 
-## Entwicklung
+Paths inside a sandbox must be below `/sandbox`.
 
-```bash
-npm test           # unit tests
-npm run build      # dist/
-```
+## Limits in the beta
 
-Die Regeln für Hoch- und Herunterladen stecken in `src/sync.ts` und sind
-reine Funktionen. Die Aufrufe an die API liegen in `src/api.ts`, die Anmeldung
-in `src/login.ts`. Mit OpenShell spricht nur noch
-[agents-api](../agents-api).
+- Up to 5 sandboxes per account.
+- No interactive shell yet; use `nido exec`.
+- The agent runs in the foreground. If the connection drops, `nido pull` fetches what is already
+  in `output/`.
+- No persistent workspaces or backups yet. Keep anything important in `output/`.
 
-Veröffentlichen: `npm publish` im Ordner `nido` (baut vorher neu).
+## Development
 
-## Grenzen
+```bash
+cd nido && npm install && npm run build && npm link
+npm test
+```
 
-- Höchstens 5 Sandboxes pro Konto in der Beta.
-- `nido shell` fehlt noch. Stattdessen `nido exec`.
-- Der Agent läuft im Vordergrund. Bricht die Verbindung ab, holt
-  `nido pull` das, was schon in `output/` liegt.
-- Keine dauerhaften Arbeitsbereiche und kein Backup (#695).
+`NIDO_API_URL` points nido at another API, for example a local agents-api. Upload and
+download rules live in `src/sync.ts` as pure functions, API calls in `src/api.ts`, login in
+`src/login.ts`. Publish with `npm publish` in this folder; it builds and tests first.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pirol/nido",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Run agents in isolated sandboxes. Give it a folder, get results back.",
   "type": "module",
   "bin": {