Quickstart
Create a VM from one of your projects, run a command in it, read the output and delete the VM.
You need curl, jq and a project that has finished its first build.
1. Create an API key
In the dashboard, open Account → API keys and create a key, or run homemade api-key create --name quickstart. Copy the key; it is shown once. Then set it for this shell:
export HOMEMADE_API_KEY=hmk_…
export API=https://api.homemade.dev2. Pick a project
List your projects and keep the id of the one to start a VM from.
curl -s $API/api/projects \
-H "Authorization: Bearer $HOMEMADE_API_KEY" \
| jq '.projects[] | {id, name, status}'{
"id": "k3v9q2m7x1d8r4tp",
"name": "storefront",
"status": "active"
}export PROJECT_ID=k3v9q2m7x1d8r4tp3. Create a VM
The VM boots from the project's latest build of main. Pass branch, size or name to choose otherwise. The answer comes right away, while the VM is still starting.
VM_ID=$(curl -s -X POST $API/api/vms \
-H "Authorization: Bearer $HOMEMADE_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"projectId\": \"$PROJECT_ID\"}" \
| jq -r '.vm.id')
echo $VM_ID4. Wait until it runs
Poll the VM until vm.state is running. A VM from a ready build usually gets there in a few seconds.
until [ "$(curl -s $API/api/vms/$VM_ID \
-H "Authorization: Bearer $HOMEMADE_API_KEY" \
| jq -r '.vm.state')" = running ]; do sleep 2; done5. Run a command
The command runs in the project folder as the VM's user, and the answer arrives when it ends. Add cwd, env or timeoutMs to the body as needed.
curl -s -X POST $API/api/vms/$VM_ID/exec \
-H "Authorization: Bearer $HOMEMADE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"command": "node --version && git log -1 --oneline"}'{
"durationMs": 41,
"exitCode": 0,
"stderr": "",
"stderrTruncated": false,
"stdout": "v26.13.1\n3f9c2e1 Add checkout page\n",
"stdoutTruncated": false,
"timedOut": false
}For a command that runs longer than about a minute, such as a test suite, add ?stream=1 to the URL. The answer then streams one JSON line per chunk of output and ends with an exit line.
6. Delete the VM
Deleting a VM removes it and its disk. This cannot be undone.
curl -s -X DELETE $API/api/vms/$VM_ID \
-H "Authorization: Bearer $HOMEMADE_API_KEY"{
"ok": true,
"state": "stopped"
}Next
The API reference lists every operation: sleeping and waking VMs, renaming them, sending a message to the coding agent inside, and managing keys.