> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superserve.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate from Modal

> Move your sandboxes, images and agent code from Modal Sandboxes to Superserve. Includes an API mapping, before and after code, a migration script and a prompt for coding agents.

Superserve runs cloud coding agents, long-running agents, CI workers, background jobs, evals, and RL environments in isolated VMs. If you run these on Modal today, most code moves call by call.

## How Superserve compares

Source: [ComputeSDK ratings](https://www.computesdk.com/benchmarks/sandboxes/compare/modal-vs-superserve),
Nov 16, 2026.

## Ready to switch

Pick how you want to migrate. Do it yourself step by step, or give the prompt to a coding agent and let it change your code.

> [tab] Human
>
> > [!NOTE]
> >
> > **Before you start**
> >
> > * **Get a Superserve API key.** Sign in to the [console](https://console.superserve.ai?utm_source=docs\&utm_medium=link), or sign up for free (no card required). Open **API Keys** and click **Create Key**. See [Get an API key](https://console.superserve.ai/api-keys/).
>
> **1. Install the SDK and set your API key**
>
> Install the Superserve SDK next to Modal. Set `SUPERSERVE_API_KEY` in your environment and CI secrets.
>
> ```bash Python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
> pip install superserve
> export SUPERSERVE_API_KEY=ss_live_...
> ```
>
> ```bash TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
> npm install @superserve/sdk
> export SUPERSERVE_API_KEY=ss_live_...
> ```
>
> **2. Map the API**
>
> The main changes: you build your Modal image into a template once, every sandbox needs a `name` instead of an app, commands are shell strings instead of argument lists, and a timeout pauses the sandbox instead of terminating it.
>
> > [tab] Python
> >
> > | Task | Modal | Superserve |
> > | - | - | - |
> > | Create | `modal.Sandbox.create(app=, image=, timeout=, env=, tags=)` | `Sandbox.create(name=, from_template=, timeout_seconds=, env_vars=, metadata=)`. `name` is required. |
> > | Image | `modal.Image.debian_slim().pip_install(...)`, built when you create the sandbox | `Template.create(name=, from_=img, steps=[RunStep(run=...)])`, built once. Then `from_template=name`. |
> > | Reconnect | `modal.Sandbox.from_id(id)` | `Sandbox.connect(id)`. Resumes a paused sandbox automatically. |
> > | Run a command | `p = sb.exec("npm", "test", env=, workdir=, timeout=)`, then `p.wait()` | `sbx.commands.run("npm test", env=, cwd=, timeout_seconds=)`. Takes a shell string and waits. |
> > | Background process | `sb.exec(...)` without `wait()` | `await sbx.commands.spawn(cmd)` on `AsyncSandbox` |
> > | Files | `sb.filesystem.write_bytes(data, path)` / `read_bytes(path)` | `sbx.files.write(path, data)` / `read(path)`. The path comes first. |
> > | Snapshot | `sb.snapshot_filesystem()` returns an image, then `Sandbox.create(image=img)`. Filesystem only. | `sbx.snapshot()`, then `Sandbox.create(name=, from_snapshot=)`. Saves memory and disk; forks keep running processes. |
> > | Memory snapshot | `sb._experimental_snapshot()`, then `Sandbox._experimental_from_snapshot(snap)`. Needs `_experimental_enable_snapshot=True`. | `sbx.snapshot()`. Every snapshot includes memory. |
> > | Pause and resume | `sb._experimental_pause()` / `_experimental_resume()`. Experimental; persistent sandboxes only. | `sbx.pause()` / `sbx.resume()` |
> > | Timeout | `timeout=` on create. Default 5 minutes. Terminates the sandbox. | `timeout_seconds=` on create or `sbx.update(timeout_seconds=)`. Pauses. |
> > | Idle timeout | `idle_timeout=`. Terminates the sandbox. | `idle_timeout_seconds=`. Pauses. |
> > | Env vars and secrets | `env={...}`, `secrets=[modal.Secret.from_name(...)]` | `env_vars={...}` on create, `env` per command, `secrets={"ENV_VAR": "secret-name"}` for API keys. See [Secrets](https://docs.superserve.ai/secrets/overview.md). |
> > | Public URL | `encrypted_ports=[port]` on create, then `sb.tunnels()[port].url` | `sbx.publish_preview_port(port, access="public")`, then `sbx.get_preview_url(port)`. New sandboxes route only published ports. See [Preview URLs](https://docs.superserve.ai/sandbox/preview-urls.md). |
> > | Authenticated URL | `sb.create_connect_token(port=port)` returns `url` and `token` | `sbx.publish_preview_port(port, access="private")`, then `sbx.get_preview_url(port)`. For the token, use `sbx.get_preview_token(port)` (send `token` in the returned `header`) or `sbx.get_signed_preview_url(port)` for a browser. |
> > | List and terminate | `modal.Sandbox.list(app_id=)` / `sb.terminate()` | `Sandbox.list()` / `sbx.kill()` |
>
> > [tab] TypeScript
> >
> > | Task | Modal | Superserve |
> > | - | - | - |
> > | Create | `modal.sandboxes.create(app, image, { timeoutMs, env })` | `Sandbox.create({ name, fromTemplate, timeoutSeconds, envVars, metadata })`. `name` is required. |
> > | Image | `modal.images.fromRegistry(img).dockerfileCommands([...])` | `Template.create({ name, from: img, steps: [{ run }] })`, built once. Then `fromTemplate: name`. |
> > | Reconnect | `modal.sandboxes.fromId(id)` | `Sandbox.connect(id)`. Resumes a paused sandbox automatically. |
> > | Run a command | `p = await sb.exec(["npm", "test"], { env, workdir, timeoutMs })`, then `await p.wait()` | `sbx.commands.run("npm test", { env, cwd, timeoutMs })`. Takes a shell string and waits. |
> > | Background process | `sb.exec([...])` without `wait()` | `sbx.commands.spawn(cmd)` |
> > | Files | `sb.filesystem.writeBytes(data, path)` / `readBytes(path)` | `sbx.files.write(path, data)` / `read(path)`. The path comes first. |
> > | Snapshot | `sb.snapshotFilesystem()` returns an image, then `modal.sandboxes.create(app, img)`. Filesystem only. | `sbx.snapshot()`, then `Sandbox.create({ name, fromSnapshot })`. Saves memory and disk; forks keep running processes. |
> > | Memory snapshot | `sb.experimentalSnapshot()`, then `modal.sandboxes.experimentalFromSnapshot(snap)` | `sbx.snapshot()`. Every snapshot includes memory. |
> > | Pause and resume | Not in the JavaScript SDK | `sbx.pause()` / `sbx.resume()` |
> > | Timeout | `timeoutMs` on create. Default 5 minutes. Terminates the sandbox. | `timeoutSeconds` on create or `sbx.update({ timeoutSeconds })`. Pauses. |
> > | Idle timeout | `idleTimeoutMs`. Terminates the sandbox. | `idleTimeoutSeconds`. Pauses. |
> > | Env vars and secrets | `env`, `secrets: [await modal.secrets.fromName(...)]` | `envVars` on create, `env` per command, `secrets: { ENV_VAR: "secret-name" }` for API keys. See [Secrets](https://docs.superserve.ai/secrets/overview.md). |
> > | Public URL | `encryptedPorts: [port]` on create, then `(await sb.tunnels())[port].url` | `await sbx.publishPreviewPort(port, { access: "public" })`, then `sbx.getPreviewUrl(port)`. New sandboxes route only published ports. See [Preview URLs](https://docs.superserve.ai/sandbox/preview-urls.md). |
> > | Authenticated URL | `await sb.createConnectToken({ port })` returns `url` and `token` | `await sbx.publishPreviewPort(port, { access: "private" })`, then `sbx.getPreviewUrl(port)`. For the token, use `await sbx.getPreviewToken(port)` (send `token` in the returned `header`) or `await sbx.getSignedPreviewUrl(port)` for a browser. |
> > | List and terminate | `modal.sandboxes.list({ appId })` / `sb.terminate()` | `Sandbox.list()` / `sbx.kill()` |
>
> To turn a Modal image into a template, see [Create a template](https://docs.superserve.ai/templates/create.md).
>
> **3. Update your code**
>
> Build the template once. Then replace the app and image with a `name` and `from_template`, turn argument lists into shell strings, and convert timeouts to seconds.
>
> ```ts Modal theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
> import { ModalClient } from "modal"
>
> const modal = new ModalClient()
> const app = await modal.apps.fromName("my-app", { createIfMissing: true })
> const image = modal.images
>   .fromRegistry("python:3.11")
>   .dockerfileCommands(["RUN pip install pytest"])
>
> const sb = await modal.sandboxes.create(app, image, {
>   timeoutMs: 600_000,
>   env: { MODE: "ci" },
>   encryptedPorts: [8000],
> })
> await (await sb.exec(["pytest"])).wait()
> const url = (await sb.tunnels())[8000].url
> const img = await sb.snapshotFilesystem()
> const fork = await modal.sandboxes.create(app, img)
> ```
>
> ```ts Superserve theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
> import { Sandbox, Template } from "@superserve/sdk"
>
> // Build once. Sandboxes then start from the template.
> const tpl = await Template.create({
>   name: "my-tpl",
>   from: "python:3.11",
>   steps: [{ run: "pip install pytest" }],
> })
> await tpl.waitUntilReady()
>
> const sbx = await Sandbox.create({
>   name: "ci-run",
>   fromTemplate: "my-tpl",
>   timeoutSeconds: 600,
>   envVars: { MODE: "ci" },
> })
> // run() stops a command after 30 s by default
> await sbx.commands.run("pytest", { timeoutMs: 10 * 60 * 1000 })
> await sbx.publishPreviewPort(8000, { access: "public" }) // a Modal tunnel is public
> const url = sbx.getPreviewUrl(8000)
> const snap = await sbx.snapshot()
> const fork = await Sandbox.create({ name: "fork", fromSnapshot: snap })
> ```
>
> ```python Modal theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
> import modal
>
> app = modal.App.lookup("my-app", create_if_missing=True)
> image = modal.Image.debian_slim().pip_install("pytest")
>
> sb = modal.Sandbox.create(
>     app=app,
>     image=image,
>     timeout=600,
>     env={"MODE": "ci"},
>     encrypted_ports=[8000],
> )
> sb.exec("pytest").wait()
> url = sb.tunnels()[8000].url
> img = sb.snapshot_filesystem()
> fork = modal.Sandbox.create(app=app, image=img)
> ```
>
> ```python Superserve theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
> from superserve import RunStep, Sandbox, Template
>
> # Build once. Sandboxes then start from the template.
> tpl = Template.create(
>     name="my-tpl",
>     from_="python:3.11",
>     steps=[RunStep(run="pip install pytest")],
> )
> tpl.wait_until_ready()
>
> sbx = Sandbox.create(
>     name="ci-run",
>     from_template="my-tpl",
>     timeout_seconds=600,
>     env_vars={"MODE": "ci"},
> )
> # run() stops a command after 30 s by default
> sbx.commands.run("pytest", timeout_seconds=10 * 60)
> sbx.publish_preview_port(8000, access="public")  # a Modal tunnel is public
> url = sbx.get_preview_url(8000)
> snap = sbx.snapshot()
> fork = Sandbox.create(name="fork", from_snapshot=snap)
> ```
>
> **4. Move existing sandboxes with the migration script**
>
> The script copies a directory from each running sandbox of a Modal app into a new Superserve sandbox. It does not change or terminate your Modal sandboxes; it removes only the temporary archive. If a copy fails, the script deletes the new Superserve sandbox. Run it with your Modal credentials and `SUPERSERVE_API_KEY` set. Set `SRC` to the directory your sandboxes write to.
>
> ```python migrate_from_modal.py theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
> import sys
>
> import modal
> from superserve import Sandbox
>
> APP = "my-app"  # the Modal app that owns your sandboxes
> SRC = "/root"  # directory to copy from each Modal sandbox
> DST = "/home/user"  # directory to copy into in Superserve
> TEMPLATE = "superserve/base"  # or the template you built from your Modal image
> TIMEOUT_SECONDS = 10 * 60  # limit for each archive, upload and extract
> failed = False
>
> app = modal.App.lookup(APP)
> for src in modal.Sandbox.list(app_id=app.app_id):
>     sid = src.object_id
>     try:
>         tar = src.exec(
>             "tar", "czf", "/tmp/state.tgz", "-C", SRC, ".", timeout=TIMEOUT_SECONDS
>         )
>         if tar.wait() != 0:
>             raise RuntimeError(tar.stderr.read())
>         tgz = src.filesystem.read_bytes("/tmp/state.tgz")
>     except Exception as err:
>         print(f"{sid}: archive failed: {err}", file=sys.stderr)
>         failed = True
>         continue
>     finally:
>         # Remove the temporary archive from the source, also after a failure.
>         try:
>             if src.exec("rm", "-f", "/tmp/state.tgz").wait() != 0:
>                 raise RuntimeError("rm failed")
>         except Exception:
>             print(f"{sid}: remove /tmp/state.tgz by hand", file=sys.stderr)
>
>     dst = Sandbox.create(
>         name=f"from-modal-{sid}",
>         from_template=TEMPLATE,
>         metadata={**src.get_tags(), "migrated_from": sid},
>     )
>     try:
>         dst.files.write("/tmp/state.tgz", tgz, timeout=TIMEOUT_SECONDS)
>         out = dst.commands.run(
>             f"tar xzf /tmp/state.tgz -C {DST} && rm /tmp/state.tgz",
>             timeout_seconds=TIMEOUT_SECONDS,
>         )
>         if out.exit_code != 0:
>             raise RuntimeError(out.stderr)
>     except Exception as err:
>         print(f"{sid}: copy failed: {err}", file=sys.stderr)
>         failed = True
>         # Delete the new sandbox so a failed copy does not keep running.
>         try:
>             dst.kill()
>         except Exception:
>             print(f"{sid}: delete {dst.id} by hand", file=sys.stderr)
>         continue
>     print(f"{sid} -> {dst.id}")
>
> sys.exit(1 if failed else 0)
> ```
>
> ```ts migrate-from-modal.ts theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
> import { ModalClient } from "modal"
> import { Sandbox } from "@superserve/sdk"
>
> const APP = "my-app" // the Modal app that owns your sandboxes
> const SRC = "/root" // directory to copy from each Modal sandbox
> const DST = "/home/user" // directory to copy into in Superserve
> const TEMPLATE = "superserve/base" // or the template you built from your Modal image
> const TIMEOUT_MS = 10 * 60 * 1000 // limit for each archive, upload and extract
>
> const modal = new ModalClient()
> const app = await modal.apps.fromName(APP)
> for await (const src of modal.sandboxes.list({ appId: app.appId })) {
>   const sid = src.sandboxId
>   let tgz: Uint8Array
>   try {
>     const tar = await src.exec(
>       ["tar", "czf", "/tmp/state.tgz", "-C", SRC, "."],
>       { timeoutMs: TIMEOUT_MS },
>     )
>     if ((await tar.wait()) !== 0) throw new Error(await tar.stderr.readText())
>     tgz = await src.filesystem.readBytes("/tmp/state.tgz")
>   } catch (err) {
>     console.error(`${sid}: archive failed: ${err}`)
>     process.exitCode = 1
>     continue
>   } finally {
>     // Remove the temporary archive from the source, also after a failure.
>     await src
>       .exec(["rm", "-f", "/tmp/state.tgz"])
>       .then(async (rm) => {
>         if ((await rm.wait()) !== 0) throw new Error("rm failed")
>       })
>       .catch(() => console.error(`${sid}: remove /tmp/state.tgz by hand`))
>   }
>
>   const dst = await Sandbox.create({
>     name: `from-modal-${sid}`,
>     fromTemplate: TEMPLATE,
>     metadata: { ...(await src.getTags()), migrated_from: sid },
>   })
>   try {
>     await dst.files.write("/tmp/state.tgz", tgz, { timeoutMs: TIMEOUT_MS })
>     const out = await dst.commands.run(
>       `tar xzf /tmp/state.tgz -C ${DST} && rm /tmp/state.tgz`,
>       { timeoutMs: TIMEOUT_MS },
>     )
>     if (out.exitCode !== 0) throw new Error(out.stderr)
>   } catch (err) {
>     console.error(`${sid}: copy failed: ${err}`)
>     process.exitCode = 1
>     // Delete the new sandbox so a failed copy does not keep running.
>     await dst
>       .kill()
>       .catch(() => console.error(`${sid}: delete ${dst.id} by hand`))
>     continue
>   }
>   console.log(`${sid} -> ${dst.id}`)
> }
> ```
>
> Each archive, upload and extract can take up to 10 minutes. For large directories or slow connections, raise `TIMEOUT_SECONDS` / `TIMEOUT_MS`.
>
> The script copies files. Start your services in the new sandbox, then take a Superserve [snapshot](https://docs.superserve.ai/sandbox/snapshots.md) to save memory, processes and disk together.
>
> **5. Verify and cut over**
>
> Run your test suite against Superserve. Check the sandbox list in the [console](https://console.superserve.ai?utm_source=docs\&utm_medium=link). When the results match, send production traffic to Superserve.
>
> **6. Remove Modal when nothing uses it**
>
> After the cutover, search your code and deployments for other Modal uses, such as Modal Functions. If none remain, remove the `modal` package and delete your Modal token from your environment and CI secrets. If some remain, keep the package and the token for them.
>
> ```bash Python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
> pip uninstall modal
> ```
>
> ```bash TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
> npm uninstall modal
> ```

> [tab] Agent
>
> Paste this prompt into Claude Code, Codex, Cursor or another coding agent at the root of your repo. The agent changes the code and runs your tests. You review the diff.
>
> ```text Migration prompt theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
> Migrate this repository from Modal Sandboxes to the Superserve SDK.
>
> Reference: https://docs.superserve.ai/llms-full.txt (read it first).
>
> Before you start: ask me for a Superserve API key if SUPERSERVE_API_KEY is not set.
> I get it from the console (https://console.superserve.ai/api-keys/). Do not create a key yourself.
>
> 1. Install superserve (pip) or @superserve/sdk (npm) next to modal. Do not remove modal.
>    Add SUPERSERVE_API_KEY to code, .env.example, and CI config.
> 2. Find every use of modal.Sandbox (Python) or modal.sandboxes (TypeScript).
>    Change only sandbox code. Leave Modal Functions as they are and list them.
>    Apply this mapping:
>    - modal.Image definitions used by sandboxes -> Template.create({name, from, steps}), built once.
>      Python: Template.create(name=, from_=, steps=[RunStep(run=...)]).
>    - Sandbox.create(app=, image=, timeout=, env=) -> Sandbox.create({name, fromTemplate,
>      timeoutSeconds, envVars}). name is required: derive it from context. Drop the app.
>    - sb.exec("cmd", "arg") + wait() -> commands.run("cmd arg"). It takes one shell string:
>      quote arguments (Python: shlex.join). It waits and returns exitCode, stdout, stderr.
>      It does not throw on a nonzero exit code, so check exitCode where the code checked returncode.
>      Without timeoutMs, run() stops the command after 30 seconds. Modal exec has no default
>      timeout, so set timeoutMs on installs, builds, tests and any other command that can take longer.
>    - sb.exec(...) without wait() -> commands.spawn(cmd). Python: on AsyncSandbox.
>    - filesystem.write_bytes(data, path) / read_bytes(path) -> files.write(path, data) / files.read(path)
>    - snapshot_filesystem() + Sandbox.create(image=img) -> snapshot() + Sandbox.create({name, fromSnapshot})
>    - _experimental_snapshot() / _experimental_from_snapshot() -> snapshot() / fromSnapshot
>    - timeout and idle_timeout -> timeoutSeconds and idleTimeoutSeconds. Superserve pauses
>      on timeout, Modal terminates. If the code relies on the sandbox ending, call kill().
>    - secrets=[modal.Secret.from_name(x)] -> create the Superserve secret, then
>      secrets: {ENV_VAR: "secret-name"}.
>    - encrypted_ports=[p] + tunnels()[p].url -> publishPreviewPort(p, {access: "public"}),
>      then getPreviewUrl(p).
>    - create_connect_token(port=p) -> publishPreviewPort(p, {access: "private"}), then
>      getPreviewUrl(p). Send the Superserve preview credential: getPreviewToken(p) returns
>      {header, token} for machine clients; getSignedPreviewUrl(p) returns a URL for browsers.
>    - A new port is public by default. New sandboxes route only published ports.
>      Ports must be 1024 to 65535.
>    - Sandbox.from_id(id) -> Sandbox.connect(id). Sandbox.list() / terminate() -> Sandbox.list() / kill().
>    - Python: use snake_case (from_template, timeout_seconds, env_vars, from_snapshot).
> 3. Run the test suite. Fix failures. Do not delete Modal code paths you cannot test; list them.
> 4. Report: files changed, tests run and their result, and anything left for a human.
> 5. Only after I confirm the cutover: search the repo and its deploy config for other Modal uses,
>    such as Modal Functions. If none remain, uninstall modal and remove the Modal token.
>    If some remain, keep modal and the token, and list the remaining uses.
> ```
>
> ### Give your agent the full reference
>
> | Resource | Use |
> | - | - |
> | [`docs.superserve.ai/llms-full.txt`](https://docs.superserve.ai/llms-full.txt) | The whole docs in one file for the agent context |
> | [`superserve` skill](https://github.com/superserve-ai/superserve/tree/main/skills/superserve) | Full SDK reference for Claude Code and other skill-aware agents |
> | [Superserve MCP server](https://docs.superserve.ai/integrations/mcp.md) | Lets the agent create and test sandboxes while it migrates |
>
> The API mapping and the migration script are in the **Human** tab.

## Known differences

| Area | What to do |
| - | - |
| Timeout behavior | Modal terminates a sandbox at its timeout or idle timeout. Superserve pauses it and stops compute billing. Call `kill()` or set `autoDeleteSeconds` if you want it gone. |
| Commands | Modal `exec` takes an argument list. Superserve `commands.run` takes one shell string, waits for it, and does not throw on a nonzero exit code. Quote arguments and check `exitCode` / `exit_code`. Modal `exec` has no default timeout, but `run()` stops a command after 30 seconds, so set `timeoutMs` / `timeout_seconds` on installs, builds and tests. |
| Images | Build your image into a template once with `Template.create`. Every sandbox then starts from the built template. Set `vcpu` and `memory_mib` on the template. |
| Grouping | Group sandboxes with `metadata` and filter `Sandbox.list` by it. |
| Secrets | A Modal secret puts the real value in the environment. A Superserve secret keeps the real value out of the sandbox: code sees a stand-in value, and Superserve attaches the real value to outbound requests. Use `envVars` for values that are not credentials. |
| Preview ports | Modal opens tunnels for the ports you list at create time. Superserve publishes ports on a running sandbox, and a new port is public by default. Publish with `access: "private"` and send a preview token to keep a port protected. |
| Process state | The migration script moves files, not memory. Take a Superserve snapshot after you restart services. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.