Create Your First Sandbox

This quickstart creates a sandbox from base, writes a file, runs a shell command, prints the result, and deletes the sandbox.

Before You Start

You need:

• A SeaCloud API key that can create sandboxes.
• Access to the base official template in the target environment.
• Node.js, Python, or Go installed locally.
• Network access from your runtime to https://sandbox-gateway.cloud.seaart.ai.

1. Configure Credentials

Create a SeaCloud API key, then export the gateway URL and token in your shell or runtime secret manager.

export SEACLOUD_BASE_URL="https://sandbox-gateway.cloud.seaart.ai"
export SEACLOUD_API_KEY="YOUR_API_KEY"

Keep tokens server-side

Do not expose SEACLOUD_API_KEY or envdAccessToken in browser code, agent-visible logs, or generated files.

2. Install An SDK

Node

npm install @seacloudai/sandbox

Python

pip install seacloud-sandbox

Go

go get github.com/SeaCloudAI/sandbox-go

3. Create, Run, And Clean Up

Node

import { Sandbox } from "@seacloudai/sandbox";

const sandbox = await Sandbox.create("base", {
  waitReady: true,
  timeout: 1800,
});

try {
  await sandbox.files.write("/root/workspace/hello.txt", "hello from node\n");

  const run = await sandbox.commands.run("sh", {
    args: ["-lc", "pwd && cat /root/workspace/hello.txt"],
  });

  console.log(run.exitCode, run.stdout);
} finally {
  await sandbox.delete();
}

Python

from sandbox import Sandbox

sandbox = Sandbox.create("base", waitReady=True, timeout=1800)

try:
    sandbox.files.write("/root/workspace/hello.txt", "hello from python\n")

    run = sandbox.commands.run(
        "sh",
        args=["-lc", "pwd && cat /root/workspace/hello.txt"],
    )

    print(run["exit_code"], run["stdout"])
finally:
    sandbox.delete()

Go

ctx := context.Background()
ready := true
timeout := int64(1800)

sbx, err := sandbox.Create(ctx, "base", &sandbox.CreateOptions{
  WaitReady: &ready,
  Timeout:   &timeout,
})
if err != nil {
  log.Fatal(err)
}
defer sbx.Delete(ctx)

files, _ := sbx.Files()
_, _ = files.Write(ctx, "/root/workspace/hello.txt", []byte("hello from go\n"))

cmds, _ := sbx.Commands()
run, _ := cmds.Run(ctx, "sh", &sandbox.CommandRunOptions{
  Args: []string{"-lc", "pwd && cat /root/workspace/hello.txt"},
})

log.Println(run.ExitCode, run.Stdout)

Expected Output

The command should print an exit code of 0 and output similar to:

/root/workspace
hello from node

Language-specific stdout wrappers may differ, but a successful run has three properties:

1. The sandbox reaches running.
2. The file under /root/workspace/hello.txt is readable.
3. Cleanup calls delete() without a lifecycle error.

What You Just Did

Step	API surface
Create sandbox	POST /api/v1/sandboxes through the SDK
Wait for readiness	waitReady: true waits until runtime APIs can be used
Write a file	Runtime filesystem APIs behind sandbox.files
Run a command	Runtime process APIs behind sandbox.commands
Delete sandbox	DELETE /api/v1/sandboxes/:sandboxID through sandbox.delete()

First-Run Troubleshooting

Symptom	Check
401 or 403	SEACLOUD_API_KEY is present, valid, and scoped to the target project.
template not found	List official templates in the target environment and confirm base is visible.
Sandbox waits too long	Increase lifecycle timeout; check sandbox detail for timeline and diagnostic.
Runtime credentials are missing	Fetch sandbox detail and confirm envdUrl and envdAccessToken are present.
Command times out	Increase runtime command timeoutMs; this is milliseconds, not seconds.
Cleanup fails	Retry delete() with the sandbox ID, then check lifecycle state.

Curl Smoke Test

Use this when SDK setup fails and you want to verify the gateway/API key first:

curl -sS "${SEACLOUD_BASE_URL}/api/v1/sandboxes" \
  -H "X-API-Key: ${SEACLOUD_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{
    "templateID": "base",
    "timeout": 1800,
    "waitReady": true
  }' | jq .

Save the returned sandboxID and delete it after the test:

curl -sS -X DELETE "${SEACLOUD_BASE_URL}/api/v1/sandboxes/${SANDBOX_ID}" \
  -H "X-API-Key: ${SEACLOUD_API_KEY}" -i

Next Steps

• Use lifecycle APIs for reconnect, pause, refresh, and timeout changes.
• Open apps through network and preview URLs.
• Build reusable environments with sandbox templates.