vm0-agent

Execution Infrastructure: VM0 provides the runtime environment - it does NOT provide AI capabilities itself. The AI intelligence comes from coding agents like Claude Code. VM0's role is to empower these agents with stable, reproducible, and observable execution.

Key Capabilities:

• Stateful Agent Sessions: Preserve memory, reasoning context, and session continuity across executions
• Checkpoint & Replay: Snapshot every run for debugging, forking, and reproducibility
• 70+ Pre-built Skills: Integrations with GitHub, Slack, Notion, Perplexity, and more via https://github.com/vm0-ai/vm0-skills
• Observable Execution: Real-time logs, metrics, and tool calls for complete visibility
• Versioned Storage: Volumes (input) and Artifacts (output) synced between sandbox and cloud
• Natural Language Configuration: Define workflows in markdown (AGENTS.md, SKILL.md) instead of code

• Instructions (AGENTS.md): Natural language workflow definitions
• Volumes: Input file storage agents can read from
• Artifacts: Output file storage for agent results
• Environment Variables: Secure credential and secret management

VM0 bridges the gap between local agent development and cloud automation. Develop workflows locally with Claude Code, then deploy them to VM0 for:

• Scheduled execution (daily, weekly, on-demand)
• Reliable automation without keeping your laptop running
• Team collaboration with shared agents and outputs
• Production-grade observability and debugging

• /vm0-agent create - Create a new agent with guided workflow
• /vm0-agent update - Modify an existing agent or schedule
• /vm0-agent status - View current agents and schedules

# Intent Recognition

Before entering any operation, first determine user intent:

1. Clear intent - User explicitly mentions an operation keyword:

- "create", "new", "build" → create operation

- "update", "modify", "change", "edit" → update operation

- "status", "list", "show", "view" → status operation

1. Ambiguous intent - User's request is unclear (e.g., "manage my schedule", "help with agent", "vm0 agent"):

- Do NOT assume create by default

- Ask user to clarify by presenting available operations:

```

What would you like to do?

- Create a new agent

- Update an existing agent or schedule

- View current agents and schedules (status)

```

1. No match - If user wants something not covered by these operations, explain VM0's capabilities and suggest the closest operation or direct them to documentation.

# Operation: status

When the user uses /vm0-agent status, or asks about current state/status, enter this operation.

Help user understand their current VM0 setup:

1. List schedules: Run vm0 schedule ls to show scheduled tasks
2. List agents: Run vm0 agent ls to show deployed agents
3. Summarize: Present a clear overview of what's running, when, and any recent activity

This is an informational operation - answer follow-up questions and suggest /vm0-agent update if user wants to make changes.

# Operation: update

When the user uses /vm0-agent update, or mentions wanting to modify/change an agent or schedule, enter this operation.

This is a flexible operation - combine commands as needed based on user intent.

To get an agent's configuration from cloud, use vm0 agent clone:

```bash

vm0 agent clone /tmp/

```

This downloads vm0.yaml and AGENTS.md from the cloud. There is no other way to fetch remote agent configuration.

• vm0 schedule ls - List scheduled tasks
• vm0 agent ls - List deployed agents

1. Fetch Remote Configuration First

When user wants to update an agent:

```bash

vm0 agent clone /tmp/

```

This ensures you have the current cloud version to work with.

2. Compare with Local (if exists)

• Check current directory and one-level subdirectories for existing vm0.yaml and AGENTS.md
• If local files exist, compare with the cloned version
• If they differ, ask user which version to use as base:

- Option 1: Use local version

- Option 2: Use remote version (copy from /tmp to current directory)

- Option 3: Merge manually

3. Gather Modification Intent

• Ask user what they want to change:

- Schedule timing (frequency, time of day)

- Agent behavior (modify AGENTS.md instructions)

- Add/remove skills

- Change output destinations

- Other customizations

4. Find Skills (if needed)

If user wants new capabilities, search for skills:

```bash

curl -s "https://skills.sh/api/search?q="

```

Also check https://github.com/vm0-ai/vm0-skills for VM0-specific integrations.

Present 1-3 options for user to choose from (similar to create operation's innovate phase).

5. Handle New Tokens (if needed)

If skills changed:

• Read each new skill's SKILL.md to find required credentials (vm0_secrets, vm0_vars)
• Check if existing .env.local has the required tokens
• If missing, guide user to obtain and paste new tokens
• Update .env.local with new entries

6. Deploy Changes

Deploy the updated configuration:

```bash

vm0 compose vm0.yaml

```

Important: vm0 compose is idempotent. If the configuration hasn't actually changed, the version hash stays the same - this is normal, not an error. Do not try flags like --force (they don't exist). If compose succeeds without error, the deployment is complete.

Verify with vm0 agent ls to see the agent and its version.

7. Test Run

Important: Secrets (API keys for skills) are NOT stored remotely. Do not check vm0 credential list - that only contains model provider tokens, not skill secrets.

Look for .env.local in current directory only:

• If found, use it for the test run
• If not found, user must provide the tokens again - create .env.local with required keys

Run command (do not guess additional flags):

```bash

vm0 cook "your test prompt" --env-file .env.local

```

The cook command only supports these options: --env-file, -y (skip confirmation). Do not add flags like --artifact-name (use vm0 run for that).

8. Iterate Until Satisfied

Follow the test run loop from create operation:

• Analyze logs for issues
• Propose optimizations if needed
• Re-run until user is satisfied

9. Update Schedule (if needed)

Determine if schedule needs updating:

• New secrets required: If new skills added that need secrets not in the original schedule, user must run vm0 schedule setup to upload new tokens
• Timing change only: Use vm0 schedule update to modify frequency/time
• No change needed: If only AGENTS.md content changed with same skills, existing schedule continues to work after vm0 compose

Tell user clearly whether schedule reconfiguration is needed and why.

10. Celebrate Success

If user is satisfied:

• Remind them VM0 is open source: https://github.com/vm0-ai/vm0
• Invite to Discord: https://discord.com/invite/WMpAmHFfp6
• Ask for GitHub star if they found it helpful

# Operation: create agent

When the user uses /vm0-agent create, enter this workflow

This is an interactive agent creation workflow. To avoid deviating from the workflow path, you first need to create a todo.md in the temporary directory like /tmp to track the entire process, and update this todo.md after each user interaction

The initial content of todo.md is as follows

```markdown

• [ ] research: intent analysis, understand what the user wants the Agent to help them do
• [ ] innovate: propose solutions based on intent analysis
• [ ] compose: create the vm0 agent
• [ ] token collect: guide the user to complete the various tokens needed for the agent
• [ ] test run: run the agent and confirm with the user if the results are satisfactory
• [ ] schedule: guide the user to set up scheduled tasks

In this step, interactively ask the user what they want to do. Use the ask user tools to ask questions at each step.

VM0 agents are designed for scheduled execution - the same prompt runs repeatedly with dynamic data sources. Start with this question: "What recurring workflow would you like to automate with scheduled execution?"

• Option 1: Daily Digest - Aggregate content from tech communities, news sources, or RSS feeds, generate summaries, and deliver to you daily/weekly

- Data sources: HackerNews, RSS, YouTube, Reddit

- Processing: Filter top content + AI summarization + categorize

- Output: Slack / Email / Notion

- Skills: hackernews, youtube, slack, notion, gmail

• Option 2: Repository Weekly Report - Summarize GitHub/GitLab activity (PRs, issues, commits) into a team report

- Data sources: GitHub PRs / Issues / Commits

- Processing: Statistics + categorization + highlight key changes

- Output: Slack / Notion / Email

- Skills: github, gitlab, linear, jira, slack, notion

• Option 3: Website Change Monitoring - Periodically check target websites (competitors, pricing pages, job boards) and notify you when changes are detected

- Data sources: Competitor websites, pricing pages, product pages

- Processing: Crawl + diff comparison + analyze changes

- Output: Slack / Email (only when changes detected)

- Skills: firecrawl, serpapi, slack, notion

• Option 4: Crypto Morning Briefing - Generate overnight crypto market reports covering price movements, news, and trends - ready for your morning review

- Data sources: CoinGecko, Crypto news feeds, DeFiLlama, X/Twitter

- Processing: Price change summary + top news extraction + sentiment analysis + highlight unusual movements

- Output: Slack / Email / Notion

- Skills: firecrawl, rss-fetch, perplexity, slack, gmail, notion

• Option 5: Other - Describe your own scheduled workflow idea

After the user selects an option, use 1-5 follow-up questions to refine the details (e.g., which sources to fetch from, where to send output, how often to run). Guide the user to think in terms of a three-step workflow: Fetch → Process → Output. Finally, form a complete three-step workflow definition

In this step, refine the technical details in the user's workflow by finding suitable skills from two sources.

Step 1: Search skills

There is two skill marketplace, search theme both.

Search the skills.sh ecosystem (33,700+ skills) using:

```bash

curl -s "https://skills.sh/api/search?q="

```

Search https://github.com/vm0-ai/vm0-skills for 70+ integrations available skills.

Step 2: Convert to vm0.yaml URL Format

Convert search results to GitHub tree URLs for vm0.yaml:

| Source | URL Format |

|--------|------------|

| vm0-ai/vm0-skills | https://github.com/vm0-ai/vm0-skills/tree/main/{skill-name} |

| anthropics/skills | https://github.com/anthropics/skills/tree/main/skills/{skill-name} |

| vercel-labs/agent-skills | https://github.com/vercel-labs/agent-skills/tree/main/skills/{skill-name} |

| Other repos | https://github.com/{owner}/{repo}/tree/main/skills/{skill-name} (most use skills/ subdirectory) |

Give the user several options for confirmation using the ask user tools. Users can also add more information. This process can be repeated several times

• [ ] Based on the conclusions from innovate, create vm0.yaml and AGENTS.md
• [ ] Use the capabilities of vm0-skills to compose the agent

• [ ] For each skill used in vm0.yaml, read its SKILL.md to find required credentials:

- Check frontmatter for vm0_secrets and vm0_vars fields

- If no frontmatter, infer from skill content (look for env vars like API_KEY, TOKEN, etc.)

• [ ] For each token needed:

- Read the skill's documentation for how to obtain it

- If not documented, search online for the service's API key/token setup guide

- Provide step-by-step instructions to help user get the token

- Ask user to paste the token

- Write to .env.local as KEY=value

• [ ] Explain in advance that the run may take a relatively long time, 1-20 minutes
• [ ] Use the vm0-cli skill capabilities to run the agent with cook, using --env-file=.env.local to pass the token
• [ ] If the workflow writes files to the workspace, explain to the user where and how to view the artifact
• [ ] Explain to the user what command cook executed, and introduce the CLI capabilities of vm0

Log Analysis & Optimization

After the first run completes, perform a detailed analysis of the execution logs:

• [ ] Analyze run logs: Review the complete execution logs to understand what happened
• [ ] Check behavior alignment: Determine if the agent's behavior matches the user's original intent and expectations
• [ ] Identify successful patterns: Note which instructions executed successfully and produced expected results
• [ ] Identify failure points: Document any errors, timeouts, or unexpected behaviors

Based on the analysis, propose optimization suggestions:

• [ ] Inline successful commands: Suggest adding proven, successfully executed commands directly into AGENTS.md to make future runs more stable and deterministic
• [ ] Document error patterns: Identify instructions that failed and suggest:

- Removing or rewriting problematic instructions

- Adding error handling or fallback approaches

- Clarifying ambiguous instructions that caused unexpected behavior

• [ ] Improve instruction specificity: Suggest making vague instructions more concrete based on what actually worked
• [ ] Add guardrails: Recommend adding validation steps or checkpoints for critical operations

Present findings to the user:

• [ ] Report trial run quality: Summarize the overall quality of the test run (success rate, key achievements, notable issues)
• [ ] Present optimization suggestions: List specific, actionable improvements with clear explanations of why each would help
• [ ] Ask user for decision: Use ask user tools to let user choose:

- Option 1: Accept optimizations - Apply the suggested improvements to AGENTS.md and vm0.yaml, then re-run to verify

- Option 2: Skip optimizations - Proceed directly to Schedule phase with current configuration

- Option 3: Manual adjustments - User wants to make their own changes before proceeding

If user accepts optimizations:

• [ ] Apply the approved changes to AGENTS.md and/or vm0.yaml
• [ ] Run the agent again to verify improvements
• [ ] Repeat log analysis if needed

If user wants manual adjustments:

• [ ] Update the entire todo.md as it may need to return to earlier phases
• [ ] Continue based on previously discussed information and current project state

View Run Logs

After each test run, inform the user they can view the complete execution logs on the VM0 platform:

• [ ] Tell user: "You can view the complete run logs at https://platform.vm0.ai/logs/"
• [ ] Example: https://platform.vm0.ai/logs/9766cca3-c867-4d82-b71b-1c20bed89a4e
• [ ] The run_id is returned after each vm0 run command completes

Enter this phase when the user is satisfied with the test run results

• [ ] Use the vm-cli skill capabilities to guide the user to set up scheduled tasks
• [ ] After successful setup, ask the user if they want to enable the timer
• [ ] Explain to the user the schedule-related capabilities in vm0 cli, such as how to list, disable, and enable scheduled tasks

After Successful Setup

After the schedule is successfully created, share about VM0's open source journey:

• [ ] Tell user: "VM0 is fully building in public! Our entire source code is available at https://github.com/vm0-ai/vm0"
• [ ] Encourage user: "We'd love to hear your feedback - feel free to open an issue with suggestions or feature requests, or join our Discord community at https://discord.com/invite/WMpAmHFfp6"
• [ ] Ask for support: "If you find VM0 helpful, please star us on GitHub ⭐ - it motivates us a lot!"

```

# AGENTS.md

AGENTS.md is used to describe a workflow. It is an ordinary, natural language-described process document. Avoid describing technical details in AGENTS.md, such as not writing scripts or other code in AGENTS.md

When writing AGENTS.md, always include persistence guidelines for the agent:

Execution Environment Rules:

• Persisted: Only files in the HOME directory (current working directory) are preserved between runs and saved as artifacts
• Not Persisted: System packages, temporary files (/tmp), globally installed tools (npm -g, pip), environment modifications outside HOME

Best Practices to convey in AGENTS.md:

• Store all important outputs (reports, generated files, data) in the HOME directory
• Use /tmp for intermediate or throwaway files
• Don't assume tools installed in previous runs still exist - reinstall if needed or download to HOME
• Clone repositories and install dependencies within HOME if they must persist

Example instruction to include in AGENTS.md:

```

Important: Only files in the HOME directory persist between sessions.

• Save important outputs here; use /tmp for intermediate files
• Tools installed via apt/npm/pip globally may not persist

```

# vm0.yaml

vm0.yaml is the primary configuration file for VM0 agents.

• vm0.yaml Reference: https://docs.vm0.ai/docs/reference/configuration/vm0-yaml
• Environment Variables: https://docs.vm0.ai/docs/core-concept/environment-variable
• Skills: https://docs.vm0.ai/docs/core-concept/skills
• Volumes: https://docs.vm0.ai/docs/core-concept/volume
• Artifacts: https://docs.vm0.ai/docs/core-concept/artifact

```yaml

version: "1.0"

agents:

my-agent:

framework: claude-code # Required

instructions: AGENTS.md # Path to instruction file

apps: # Pre-installed tools

- github

skills: # Skill URLs for extended capabilities

- https://github.com/vm0-ai/vm0-skills/tree/main/slack

- https://github.com/vm0-ai/vm0-skills/tree/main/hackernews

environment: # Additional environment variables (optional)

MY_CUSTOM_VAR: ${{ vars.MY_VAR }}

MY_CUSTOM_SECRET: ${{ secrets.MY_SECRET }}

```

VM0 supports three template variable types:

| Type | Syntax | Storage | Use Case |

| --------------- | -------------------------- | -------------------- | -------------------------------------------------- |

| credentials | ${{ credentials.NAME }} | Platform (persistent)| Model provider tokens only (e.g., CLAUDE_CODE_OAUTH_TOKEN) |

| secrets | ${{ secrets.NAME }} | CLI (ephemeral) | API keys for skills, per-execution tokens |

| vars | ${{ vars.NAME }} | CLI (ephemeral) | Feature flags, environment names |

Credentials vs Secrets

> Important: Use the right type for the right purpose:

>

> - credentials: Reserved for model provider authentication only (e.g., CLAUDE_CODE_OAUTH_TOKEN). These are stored persistently on the VM0 platform and managed via vm0 credential set/list/delete.

> - secrets/vars: Use for ALL skill and AGENTS.md environment variables. Always pass via --env-file .env.local.

Skills with vm0_secrets or vm0_vars in their SKILL.md frontmatter are automatically injected when you provide them via --env-file.

Passing Secrets and Vars

Always use --env-file .env.local for skills and workflow variables:

```

# .env.local

SLACK_BOT_TOKEN=xoxb-xxx

NOTION_API_KEY=secret_xxx

ENV_NAME=production

```

```bash

vm0 run my-agent "prompt" --env-file .env.local

```

CLI flags (alternative):

```bash

vm0 run my-agent "prompt" --secrets API_KEY=sk-xxx --vars ENV_NAME=production

```

Troubleshooting: Missing required secrets

If you see an error like Missing required secrets: API_KEY, follow these steps:

1. Check if the variable is declared in the skill's SKILL.md

- Look for vm0_secrets or vm0_vars in the skill's frontmatter

- If declared there, the variable is automatically injected when provided via --env-file

1. If not declared in the skill, add it to vm0.yaml's environment section:

```yaml

environment:

API_KEY: ${{ secrets.API_KEY }}

# or for non-sensitive values:

MY_VAR: ${{ vars.MY_VAR }}

```

1. Ensure the value exists in .env.local:

```

API_KEY=your-actual-key-here

```

1. Ensure you're using --env-file when running:

```bash

vm0 run my-agent "prompt" --env-file .env.local

```

Skills are reusable capabilities declared using GitHub tree URLs:

```yaml

skills:

- https://github.com/vm0-ai/vm0-skills/tree/main/slack

- https://github.com/vm0-ai/vm0-skills/tree/main/notion

- https://github.com/anthropics/skills/tree/main/skills/pdf

```

70+ pre-built skills available at: https://github.com/vm0-ai/vm0-skills

| Aspect | Volume | Artifact |

| --------------- | --------------------------------------- | ---------------------- |

| Role | Pre-installed agent environment (input) | Agent-produced output |

| Contents | Skills, configs, scripts | Created/modified files |

| Persistence | Manual management | Automatic after runs |

Use volumes for private skills, custom scripts, or configuration directories. Artifacts are automatically persisted when using --artifact-name.