Run Mastra agents and workflows on your own VM

Set up Mastra#

Deploy sets it up on a new VM. To do it yourself:

ssh exe.dev new --name=my-mastra
ssh my-mastra.exe.xyz

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs
npx -y create-mastra@1 my-agents --llm openai < /dev/null

cd ~/my-agents
(umask 077; printf 'OPENAI_BASE_URL=https://llm.int.exe.xyz/v1\nOPENAI_API_KEY=exe.dev\n' > .env)
npm run build -- --studio

sudo tee /etc/systemd/system/mastra.service >/dev/null <<'EOF'
[Unit]
Description=Mastra server
After=network-online.target
Wants=network-online.target

[Service]
User=exedev
WorkingDirectory=/home/exedev/my-agents
EnvironmentFile=/home/exedev/my-agents/.env
Environment=NODE_ENV=production PORT=8000 MASTRA_STUDIO_PATH=.mastra/output/studio MASTRA_AUTO_DETECT_URL=true
ExecStart=/usr/bin/node .mastra/output/index.mjs
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl enable --now mastra

Open Studio#

Open https://my-mastra.exe.xyz/ and sign in to exe.dev. Under Agents, the starter agent chats with GPT through the LLM integration, searches and fetches the web, keeps memory across threads, and reads, writes, and runs commands in ~/my-agents/workspace on this VM; it asks before deleting anything. Workflows, Traces, and Logs are in the sidebar.

The project is yours to change: agents in src/mastra/agents, tools in src/mastra/tools, and everything registered in src/mastra/index.ts. Shelley, or any coding agent, can make the changes; the project's AGENTS.md tells it how. After a change, on the VM:

cd ~/my-agents
npm run build -- --studio && sudo systemctl restart mastra

Add a scheduled workflow#

hn-digest.ts is a workflow of two steps: fetch the top Hacker News stories, then have a model write a short digest to workspace/digests/<date>.md, where the starter agent can read it. It runs every day at 07:00 UTC. On the VM, add it and register it:

cd ~/my-agents
curl -fsSL --create-dirs -o src/mastra/workflows/hn-digest.ts https://exe-staging.dev/deploy/mastra/hn-digest.ts
sed -i "s|^import { agent } from './agents/agent';|&\nimport { hnDigest } from './workflows/hn-digest';|; s|^  agents: { agent },|&\n  workflows: { hnDigest },|" src/mastra/index.ts
grep -c hnDigest src/mastra/index.ts
npm run build -- --studio && sudo systemctl restart mastra

Expect 2 from grep. Once /health answers, run it now rather than at 07:00:

curl -s -X POST localhost:8000/api/workflows/hn-digest/start-async \
  -H 'Content-Type: application/json' -d '{"inputData":{"count":5}}'

Expect "status":"success" and the digest, after about ten seconds. Then ask the starter agent in Studio for today's digest. Studio lists the schedule at https://my-mastra.exe.xyz/workflows/schedules, with Pause and Resume; it's kept in mastra.db, so it survives restarts.

The HTTP API answers the same way your own code calls it. From this VM:

curl -s localhost:8000/api/agents/agent/generate -H 'Content-Type: application/json' \
  -d '{"messages":[{"role":"user","content":"Hi"}],"memory":{"thread":"t1","resource":"me"}}'

From another of your exe.dev VMs, use a VM-to-VM integration to my-mastra, which keeps port 8000 private.

Give each conversation a VM#

The starter agent runs commands on the Mastra VM itself. For agents that install packages, run Docker, or serve apps, give each thread a VM of its own instead. exe-sandbox.ts is a Mastra workspace sandbox that is an exe.dev VM, made with exe.dev's TypeScript SDK on the thread's first command and kept until you delete it. vm-agent.ts is an agent that uses one per thread.

The Mastra VM makes those VMs through an integration that holds the API key: no key is ever on a VM. On your computer:

ssh exe.dev integrations add exe-dev --name mastra-vms \
  --tag mastra-sandbox --cmds new,ls,ssh,rm --attach vm:my-mastra

The integration can make, reach, and delete VMs tagged mastra-sandbox, and nothing else; the VMs it makes get that tag. Only the Mastra VM can use it. On the VM, check it, then add the two files and register the agent:

curl -s -X POST https://mastra-vms.int.exe.xyz/exec -d ls
cd ~/my-agents
npm install @exedev/sdk@0.4
curl -fsSL -o src/mastra/exe-sandbox.ts https://exe-staging.dev/deploy/mastra/exe-sandbox.ts
curl -fsSL -o src/mastra/agents/vm-agent.ts https://exe-staging.dev/deploy/mastra/vm-agent.ts
sed -i "s|^import { agent } from './agents/agent';|&\nimport { vmAgent } from './agents/vm-agent';|; s|^  agents: { agent },|  agents: { agent, vmAgent },|" src/mastra/index.ts
grep -c vmAgent src/mastra/index.ts
npm run build -- --studio && sudo systemctl restart mastra

Expect {"vms":[]} from the check and 2 from grep. In Studio, open VM Agent and ask: "Make a small Flask to-do app, serve it on port 8080, and give me the link." The first command takes a few seconds while the VM starts. The link, https://mastra-<id>.exe.xyz:8080/, opens for you after exe.dev login. A later message in the same thread finds the same VM, with its files and running services; a new thread gets a new one.

Warning

VM Agent runs commands with sudo, without asking. That's what the thread VMs are for: they hold nothing else. Keep the Mastra VM, which can make VMs on your account, to yourself, and never attach the integration to the mastra-sandbox tag, which would let thread VMs do the same.

To use the sandbox in your own agents, pass a resolver as vm-agent.ts does, or a fixed one: sandbox: new ExeSandbox({ id: 'builds' }). ExeSandbox also takes workingDirectory, timeout, and env. Off exe.dev, pass token: an exe.dev API key from ssh exe.dev ssh-key generate-api-key --label=mastra --tag=mastra-sandbox --cmds=new,ls,ssh,rm --exp=30d.

Clean up#

Thread VMs stay until you delete them; each counts toward your plan's VM limit. On your computer, ssh exe.dev ls lists them, with their thread as the comment. To delete every VM tagged mastra-sandbox:

ssh exe.dev ls --json |
  jq -r '.vms[] | select(.tags // [] | index("mastra-sandbox")) | .vm_name' |
  xargs -r ssh exe.dev rm

When you're done with them, ssh exe.dev integrations remove mastra-vms. ssh exe.dev rm my-mastra deletes the Mastra VM and its data.

Troubleshooting#

• Studio loads but can't reach the server, or asks for an instance URL: check that the unit has MASTRA_AUTO_DETECT_URL=true, then sudo systemctl daemon-reload && sudo systemctl restart mastra.
• sudo journalctl -u mastra -f shows the server's log; build errors appear in npm run build, not there.
• Connection error or 401 from the model: check .env. The LLM integration is reachable only from exe.dev VMs.
• VM Agent fails with 403 and integration not found: run the command in Give each conversation a VM with this VM's name, or ssh exe.dev integrations attach mastra-vms vm:<this-vm>.
• VM Agent fails during new: exe.dev refused a VM, often because the plan's VM limit is reached. Delete old thread VMs.