Using Heyo Computer

Overview

You drive Heyo through its MCP server, usually from an agent such as Claude Code. Every action is a tool call: create a sandbox, run a command, commit files to a repo, deploy it. There is no separate dashboard to learn, and no git or Docker is needed on your side.

This guide was itself written and deployed with Heyo: the HTML lives in a Heyo repo and is served as a static site.

Core concepts

Namespace

Your token confines you to one namespace. The repo tools and applb_deploy use it automatically when you leave namespace out, and every artifact tag you publish must start with <namespace>/. Run heyo_whoami to see yours.

app-lb

The app load balancer. It holds deployments (sites or VM pools), builds them from a repo or pulls them from an artifact, assigns each a hostname, and routes traffic to healthy replicas.

Credential tiers

Two scopes matter, and they are checked in different places:

• Admin tier (none / view / admin): what the admin API requires. Publishing artifacts needs admin for the whole namespace.
• Deployment scope: which deployments a token may reach through their own gate.

A token can pass one check and fail the other, so on any 401 or 403 read both fields from heyo_whoami.

Getting started

1. Connect the MCP serverAdd the Heyo MCP server to your agent with the token you were issued. In Claude Code the tools appear as mcp__heyo-…__*.
2. Check who you areCall heyo_whoami. Note your namespace, admin_scope and expires_in_secs.
3. Check the platformCall heyo_status to see which services the server reaches and any current faults.
4. Ask for a planNot sure how to do something? Call heyo_guide with your goal in plain words, or with an error message, and it returns the tools to call and in what order.

Sandboxes

A sandbox is a VM for an agent to work in: install dependencies, run a build, execute tests, then pull the results out.

1. Create itsandbox_create {name?, image?, disk_size_gb?} boots a VM from a hub image (default heyo/debian:latest) with a /workspace disk, and waits until it is ready.
2. Get code inSmall files: sandbox_write_file (up to 1 MiB). Larger: sandbox_upload {id, path: "/workspace/app"} returns a one-time URL; curl -T repo.tar.gz '<url>' and it is unpacked there.
3. Run commandsShort (under ~30s): sandbox_exec. Longer: sandbox_exec_start, then poll sandbox_exec_status {id, operation, offset}. Several can run at once.
4. Get results outsandbox_read_file for small files, or sandbox_download {id, path} for a file or a whole directory as a tar.gz URL.
5. Pause or finishsandbox_stop frees the VM but keeps /workspace; sandbox_start brings it back. sandbox_kill deletes it.

# one sandbox_exec call: cd and run in the same command
sandbox_exec {
  "id": "sbx-123",
  "command": "cd /workspace/app && npm ci && npm test"
}

Deploy a static site

For HTML/JS/CSS that is already built. Nothing in the repo is executed on the server, so commit the built output.

1. Build locally if neededFrameworks produce a dist/ or build/ folder. Plain HTML needs no build.
2. Create a reporepo_create {name: "my-site"} creates a git repo in your namespace. It is idempotent: an existing repo is reused.
3. Commit the filesrepo_write_files {repo, files: [{path, content}], message}. Use encoding: "base64" for images and other binaries. Up to 64 MiB per commit.
4. Deployrepo_deploy {repo, kind: "site", context?: "dist", spa?: true, host?}. Without host, the site is served at <repo>.<region domain>; the result tells you which.
5. Open itVisit https://<host>/. Sites are public by default.

repo_write_files {
  "repo": "my-site",
  "message": "Initial site",
  "files": [
    { "path": "index.html", "content": "<!doctype html><h1>Hello</h1>" },
    { "path": "logo.png", "content": "iVBORw0KGgo…", "encoding": "base64" }
  ]
}

repo_deploy { "repo": "my-site", "kind": "site" }

Deploy an app (VM)

For anything that runs a process: an API, a web server, a worker. Heyo builds your Dockerfile into a microVM image and runs it behind app-lb.

1. Write a DockerfileInstall the app (e.g. into /app) plus socat. Heyo uses socat to stream the app's stdout/stderr out of the VM; without it, logs never appear.
2. Create the repo and commitrepo_create, then repo_write_files with your source and the Dockerfile.
3. Deployrepo_deploy {repo, kind: "vm", port, start_command}. It waits for the image build.
4. Verifyapplb_get_deployment {id} and applb_metrics show whether replicas are healthy.

# Dockerfile
FROM node:20-slim
RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY . .
RUN npm ci --omit=dev

# repo_deploy
{
  "repo": "my-api",
  "kind": "vm",
  "port": 8080,
  "start_command": "cd /app && setsid nohup node server.js </dev/null &"
}

Artifacts

An alternative to repos: publish a versioned bundle of files to your namespace's artifact store, then point a deployment at it.

1. Publishart_publish_files {tag: "<namespace>/<name>:<version>", files: [...]} with file contents inline (up to 64 MiB). Already have a tarball? Use art_publish {tag, content_base64}.
2. Deployapplb_deploy a site whose artifact block is just {ref: "<tag>"}. app-lb pulls it with its own credential, so the tag can stay private.
3. Manage versionsart_list_tags, art_get_tag, art_get_manifest, art_fetch, art_delete_tag, and art_set_public to make a tag publicly fetchable.

Redeploying

Then poll applb_job {job_id, deployment} until it finishes. Pass base (the branch's current commit from repo_get) to repo_write_files if you want the commit to fail rather than overwrite someone else's concurrent change.

Monitoring

Troubleshooting

First move for any unfamiliar error: paste it into heyo_guide {goal: "<the error>"}.

Tool reference

For the full deployment spec, call applb_spec_schema.