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:

  • 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 a VSCode integration that allows you to connect to them from your local VSCode 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 DEVBOX_BASE_URL=${DEVBOX_BASE_URL:-"https://devbox.svc.cloud.morph.so"}

Quickstart 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 "$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 "$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 "$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 "$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 "$DEVBOX_BASE_URL/api/devboxes/$DEVBOX_ID/pause" | jq '.status'
curl -sS -H "Authorization: Bearer $MORPH_API_KEY" \
  -X POST "$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 "$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 "$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.
  • To quickly “open in VSCode”, use the Devboxes web interface and click the VSCode 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” 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