Run a task

cd my-project
nido init
nido secret set anthropic
nido run
  • nido init writes a nido.md into the folder.
  • nido secret set anthropic stores your Anthropic key once. It is never shown again.
  • nido run uploads the folder, runs the agent and brings the output/ folder back.

The sandbox keeps running after the run, so a second nido run only uploads what changed. Start from scratch with nido run --fresh. Remove the sandbox with nido rm <name>.

nido.md

The text below the header is the task. The settings are in the x-nido block.

---
title: Summarize this folder
x-nido:
  agent: claude
  secrets: [anthropic]
  output: output/
  files:
    exclude: [node_modules, .venv, "*.log"]
---

Read the files in this folder and write a short summary to output/summary.md
Field in x-nido Meaning
agent The agent that works on the task. claude is supported today.
command Instead of an agent: any shell command, as a string or a list.
name Sandbox name, see Several tasks in one folder.
files.exclude Files and folders that are not uploaded.
files.include When set, only these paths are uploaded.
secrets Names of stored secrets the sandbox may use, see Secrets.
network Extra hosts the sandbox may reach, for example pypi.org.
storage Storage volumes the sandbox sees at /data/<name>, see Storage.
from A template the sandbox starts from, see Backups and templates.
output Folder inside the project that comes back after the run.
image Your own container image. Defaults to an image with Claude Code, Codex, OpenCode, charta and kyte.

Everything outside x-nido is ignored. A file without x-nido does not run.

Several tasks in one folder

Any Markdown file with an x-nido block is a task:

nido run tasks/report.md
nido pull tasks/report.md

Each task file gets its own sandbox. Its name comes from name, then id in the header, then the file name. For nido.md it is the folder name.

nido uploads the folder you run it from, not just the folder of the task file. Use files.include to send less.

Coming from nido.json

nido migrate turns a nido.json into a nido.md with the same settings and removes the old file. nido still reads nido.json for now.