Skip to Content
homemade
Dashboard

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.dev

2. 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}'
Output
{
  "id": "k3v9q2m7x1d8r4tp",
  "name": "storefront",
  "status": "active"
}
export PROJECT_ID=k3v9q2m7x1d8r4tp

3. 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_ID

4. 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; done

5. 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"}'
Output
{
  "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"
Output
{
  "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.

On this page