About VM0

VM0 is an agent-native cloud infrastructure platform that provides secure sandbox environments for AI agents like Claude Code. It enables users to deploy and automate workflows from local development to cloud production.

Operation: introduce

When the user uses /vm0-agent introduce, explain to user what is VM0

home page: https://vm0.ai
sourcecode is fully in public: https://github.com/vm0-ai/vm0

What VM0 Provides

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

Platform Architecture

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

From Local to Cloud

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

Available Operations

```
/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:

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
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)
```
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:

List schedules: Run
```
vm0 schedule ls
```
to show scheduled tasks
List agents: Run
```
vm0 agent ls
```
to show deployed agents
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.

Key Command

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

bash

vm0 agent clone <agent-name> /tmp/<agent-name>

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

Other Commands

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

Workflow

1. Fetch Remote Configuration First

When user wants to update an agent:

bash

vm0 agent clone <agent-name> /tmp/<agent-name>

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=<keyword>"

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 tokens are already stored remotely:
```
vm0 secret list
```
If missing, guide user to obtain and paste new tokens
Store remotely via
vm0 secret set
(persists across runs and schedules)

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

Secrets and variables are stored remotely. Check what's available with

vm0 secret list

and

vm0 variable list

Run command (do not guess additional flags):

bash

vm0 cook "your test prompt"

The

cook

command only supports these options:

-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, store them via
```
vm0 secret set
```
— they will be automatically available to scheduled runs
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

## Research

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
  - Processing: Filter top content + AI summarization + categorize
  - Output: Slack / Notion
  - Skills: hackernews, youtube, slack, notion

- **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
  - 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 / Notion (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
  - Processing: Price change summary + top news extraction + sentiment analysis + highlight unusual movements
  - Output: Slack / Notion
  - Skills: firecrawl, rss-fetch, perplexity, slack, 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

## Innovate

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=<keyword>"

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

Compose

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

Token Collect

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
- Store remotely via
  vm0 secret set
  (persists across runs and schedules):
  bash
```
vm0 secret set SLACK_BOT_TOKEN --body "xoxb-xxx"
```
- For non-sensitive config, use
```
vm0 variable set
```
  :
  bash
```
vm0 variable set ENV_NAME production
```

Test run

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:
```
vm0 cook "your test prompt"
```
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/<run_id>
```
"
Example: https://platform.vm0.ai/logs/9766cca3-c867-4d82-b71b-1c20bed89a4e
The run_id is returned after each
```
vm0 run
```
command completes

Schedule

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

## Workspace Persistence

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.

## Key Documentation URLs

- **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

## File Structure

```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 }}

Environment Variable Types

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 }}`	Remote (stored via CLI)	API keys for skills, per-execution tokens
vars	`${{ vars.NAME }}`	Remote (stored via CLI)	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 model-provider setup/set-default/delete
.
secrets: Use for ALL sensitive skill API keys and tokens. Store remotely via
vm0 secret set
— they persist across runs and schedules.
vars: Use for non-sensitive configuration (feature flags, environment names). Store remotely via
vm0 variable set
.

Skills with

vm0_secrets

vm0_vars

in their SKILL.md frontmatter are automatically injected when stored remotely.

Passing Secrets and Vars

Store remotely via CLI:

bash

# Store a secret (interactive — prompts for value securely)
vm0 secret set SLACK_BOT_TOKEN

# Store a secret (non-interactive)
vm0 secret set NOTION_API_KEY --body "secret_xxx"

# Store a variable
vm0 variable set ENV_NAME production

# List what's stored
vm0 secret list
vm0 variable list

Once stored, secrets and variables are automatically available to all agent runs and schedules.

CLI flags (for one-off runs):

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:

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 stored remotely

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 }}

Ensure the value is stored remotely:
bash
```
vm0 secret set API_KEY
```

Skills

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

Volumes vs Artifacts

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

vm0-agent

NPX Install

Tags

SKILL.md Content

About VM0

Operation: introduce

What VM0 Provides

Platform Architecture

From Local to Cloud

Available Operations

Intent Recognition

Operation: status

Operation: update

Key Command

Other Commands

Workflow

1. Fetch Remote Configuration First

2. Compare with Local (if exists)

3. Gather Modification Intent

4. Find Skills (if needed)

5. Handle New Tokens (if needed)

6. Deploy Changes

7. Test Run

8. Iterate Until Satisfied

9. Update Schedule (if needed)

10. Celebrate Success

Operation: create agent

Step 2: Convert to vm0.yaml URL Format

Compose

Token Collect

Test run

Log Analysis & Optimization

View Run Logs

Schedule

After Successful Setup

Environment Variable Types

Credentials vs Secrets

Passing Secrets and Vars

Troubleshooting: Missing required secrets

Skills

Volumes vs Artifacts