Skip to main content

Getting started with Morph Devboxes

Morph Devboxes are the simplest way to code with AI in the cloud. Previously, working with agents like OpenAI Codex, Claude Code, or Gemini CLI in the cloud required you to use restrictive, opaque, and asynchronous web interfaces or otherwise set up a VPS and worry about sandboxing and provisioning different development environments. Devboxes on Morph Cloud, on the other hand, are all of the following:

  • Development: VSCode/Cursor + tmux integration for CLI agents make iteration fast, and snapshots/branching let you keep “infinitely many” workspaces ready to go.

  • Prototyping: expose an interactive preview of a web app or API, and optionally disable auto-sleep / TTL policies to behave like a persistent VPS.

  • Sharing & collaboration: devboxes are shareable live via URL to anyone in your Morph Cloud organization, and you can create multiple organizations as needed.

  • Programmable, shareable, and easily reproducible development environments. Devboxes are programmable: you can specify, create, interact with, and manage devboxes entirely over the Devbox API. Every devbox is created from a template that integrates with our secrets manager and which can be shared with a short URL. You can also programmatically configure devboxes with remote desktops for computer‑use, or arbitrary web applications for full‑stack development.

  • Shared workspaces for CLI agents with easy human‑in‑the‑loop interaction. Devboxes expose a full tmux API, which lets you programmatically manage coding agents like OpenAI Codex or Claude Code. These fully persistent sessions remain interactive and can be easily accessed through the devbox web interface, through SSH, or puppeteered through the Devbox API.

  • Full virtual machines capable of running any configuration of containers: docker‑in‑docker, a local Kubernetes cluster, self‑hosted Supabase, etc. There is experimental support for Windows, OSX (x86), and nested virtualization as well.

  • Serverless and elastic. Devboxes can branch to hundreds of parallel replicas or scale to zero after a period of inactivity, preserving all application and memory state.

  • Full‑featured cloud development environments. Devboxes integrate with Git auth and include one‑click integrations for VSCode and Cursor that let you connect from your local editors with a single click.

Useful links:

Prerequisites​

  • An API key from the Morph Cloud dashboard: https://cloud.morph.so
  • Optionally set the base URL (defaults to the hosted service)
export MORPH_API_KEY="<your-api-key>"
# Optional. Defaults to https://devbox.svc.cloud.morph.so
export MORPH_DEVBOX_BASE_URL=${MORPH_DEVBOX_BASE_URL:-"https://devbox.svc.cloud.morph.so"}
# 1) Start a devbox from a template
morphcloud devbox template list
TEMPLATE_ID="<template-id>"

DEVBOX_ID=$(
  morphcloud devbox start "$TEMPLATE_ID" --name "my-devbox" --json | jq -r '.id'
)
echo "Devbox: $DEVBOX_ID"

# 2) Run a command via SSH
morphcloud devbox ssh "$DEVBOX_ID" echo "Hello from a Morph Devbox!"

# 3) Prototype: expose a preview URL (example: port 3000)
morphcloud devbox ssh "$DEVBOX_ID" bash -lc "nohup python3 -m http.server 3000 >/tmp/http.log 2>&1 &"
morphcloud devbox expose-http "$DEVBOX_ID" --name app --port 3000

# 4) Pause / resume (serverless-style)
morphcloud devbox pause "$DEVBOX_ID"
morphcloud devbox resume "$DEVBOX_ID"

# 5) Clean up
morphcloud devbox delete "$DEVBOX_ID"

Advanced: Devboxes API with curl​

The examples below mirror the Devboxes product workflow: create from a snapshot, expose a web app, automate work with tmux, and pause/resume elastically. All endpoints require a Bearer token in Authorization.

# 1) Create a devbox from a snapshot (frozen state)
SNAPSHOT_ID="<snapshot-id>"
CREATE_BODY='{"name":"my-devbox","metadata":{}}'
DEVBOX=$(curl -sS -H "Authorization: Bearer $MORPH_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST "$MORPH_DEVBOX_BASE_URL/api/devboxes?snapshot_id=$SNAPSHOT_ID" \
  -d "$CREATE_BODY")
DEVBOX_ID=$(echo "$DEVBOX" | jq -r '.id')
echo "Created devbox: $DEVBOX_ID"

# 2) Expose a local HTTP service from inside the devbox (e.g., port 3000)
curl -sS -H "Authorization: Bearer $MORPH_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST "$MORPH_DEVBOX_BASE_URL/api/devboxes/$DEVBOX_ID/http" \
  -d '{"name":"app","port":3000}' | jq '.networking.http_services'

# 3) Automate agents with tmux (create a session and send keys)
curl -sS -H "Authorization: Bearer $MORPH_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST "$MORPH_DEVBOX_BASE_URL/api/devboxes/$DEVBOX_ID/tmux/sessions" \
  -d '{"name":"work","detached":true}' | jq '.session'

curl -sS -H "Authorization: Bearer $MORPH_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST "$MORPH_DEVBOX_BASE_URL/api/devboxes/$DEVBOX_ID/tmux/send-keys" \
  -d '{"sequence":["git clone https://github.com/morph-labs/example-app","ENTER","cd example-app","ENTER","npm install","ENTER","npm run dev","ENTER"],"literal":true,"pause_ms":250}' | jq '.ok'

# 4) Pause / Resume elastically
curl -sS -H "Authorization: Bearer $MORPH_API_KEY" \
  -X POST "$MORPH_DEVBOX_BASE_URL/api/devboxes/$DEVBOX_ID/pause" | jq '.status'
curl -sS -H "Authorization: Bearer $MORPH_API_KEY" \
  -X POST "$MORPH_DEVBOX_BASE_URL/api/devboxes/$DEVBOX_ID/resume" | jq '.status'

# 5) Save a snapshot of current state (for sharing or instant restore)
curl -sS -H "Authorization: Bearer $MORPH_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST "$MORPH_DEVBOX_BASE_URL/api/devboxes/$DEVBOX_ID/save" \
  -d '{"name":"checkpoint-1"}' | jq

# 6) Clean up when done
curl -sS -H "Authorization: Bearer $MORPH_API_KEY" \
  -X DELETE "$MORPH_DEVBOX_BASE_URL/api/devboxes/$DEVBOX_ID" | jq

Notes:

  • POST /api/devboxes?snapshot_id=... creates a devbox from any valid snapshot.
  • POST /api/devboxes/{id}/http returns the updated devbox with public service URLs in networking.http_services.
  • Devboxes support wake-on-SSH/HTTP and TTL policies to auto-pause idle machines.
  • tmux endpoints enable multi-pane, multi-agent workflows you can script via API.
  • For least-privilege in-agent automation inside a running devbox, mint or use a scoped agent token instead of handing the agent a broad MORPH_API_KEY.
  • To quickly "open in VSCode" or Cursor, use the Devboxes web interface and click the VSCode/Cursor action for your devbox.

Use the web dashboard​

Prefer a graphical workflow?

  1. Sign in at https://cloud.morph.so
  2. Open the Devboxes section in the left navigation
  3. Create a devbox from a snapshot or template
  4. Click “Open in VSCode” or “Open in Cursor” for a one‑click SSH session
  5. Use Live Preview to share HTTP services securely with teammates
  6. Pause/resume or snapshot whenever you like

API coverage​

The Devboxes API provides endpoints for lifecycle, metadata, HTTP exposure, tmux automation, uploads, and templates. Highlights from the OpenAPI spec include:

  • Core: List devboxes, get details and summaries
  • Lifecycle: Create from snapshot, save (snapshot), branch, delete, pause, resume, reboot
  • Actions: Update display name and metadata, expose/unexpose HTTP services
  • Tmux: Install, list sessions, create/rename/kill sessions, send keys, capture snapshots
  • Uploads: Authenticated file and image uploads into the devbox
  • Templates: List/create/update/cache templates, stream build events, and share via short URLs

See the full OpenAPI docs at https://devbox.svc.cloud.morph.so/docs