Run commands and work with files

Baseten Sandboxes are now available and free to use until November 16. Each organization can run up to 10 sandboxes at once. To raise this limit, contact support.

After a sandbox reaches status DEPLOYED, run commands and work with files through its sandbox runtime API. The SDKs and the CLI call it for you, and direct HTTP requests and MCP clients call it at the sandbox’s URL. The examples use a running sandbox named hello-world created from Base Image, which includes Python. To create one, see Create a sandbox. Before you start:

Set up your SDK or the CLI. The SDK examples read your API key from BASETEN_API_KEY, and the CLI examples read the sandbox name from SANDBOX_NAME.
For direct HTTP requests and MCP clients, request a sandbox access token and set SANDBOX_TOKEN.

Connect to a sandbox

Each sandbox serves its sandbox runtime API at its own URL. The CLI and SDKs look the URL up for you. Direct HTTP requests and MCP clients need it.

Get the sandbox URL

The sandbox URL is the url field that the create and get requests return. For what each part of the URL means, see Sandbox URLs. To get the sandbox URL:

Run the following code:

import { SandboxClient } from "@basetenlabs/sandbox";

const client = new SandboxClient({ apiKey: process.env.BASETEN_API_KEY! });
const sandbox = await client.get({ name: "hello-world" });
console.log(sandbox.url);

Run the following code:

import os

from baseten.sandbox import SandboxClient

with SandboxClient(api_key=os.environ["BASETEN_API_KEY"]) as client:
    sandbox = client.get(name="hello-world")
    print(sandbox.url)

https://sbx-hello-world-abc123.us-pdx-1.b10.co/

The Python SDK returns the URL with a trailing slash. Remove it before you append a path.

Run the following code:

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/basetenlabs/baseten-go/sandbox"
)

func main() {
    ctx := context.Background()
    client, err := sandbox.NewClient(sandbox.ClientOptions{
        APIKey: os.Getenv("BASETEN_API_KEY"),
    })
    if err != nil {
        log.Fatal(err)
    }
    sb, err := client.Get(ctx, sandbox.GetOptions{Name: "hello-world"})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(sb.URL())
}

Run the following command:

curl --url "https://api.baseten.co/v1/sandboxes/instances/$SANDBOX_NAME" \
  --header "Authorization: Bearer $SANDBOX_TOKEN"

The response’s url field holds the URL. For more information, see Get a sandbox.

Run the following command:

baseten sandbox describe --name "$SANDBOX_NAME" --jq '.url'

"https://sbx-hello-world-abc123.us-pdx-1.b10.co"

Use the URL exactly as the API returns it, and set SANDBOX_URL to it for the HTTP examples on this page.

Call the sandbox runtime API over HTTP

Send requests to the sandbox’s URL with a sandbox access token as a bearer token. To call the sandbox runtime API:

Run the following command to send an authenticated request to the sandbox:

curl --url "$SANDBOX_URL" \
  --header "Authorization: Bearer $SANDBOX_TOKEN"

{"message":"Welcome to your Baseten Sandbox. Discover your capabilities here: /swagger/doc.json","apiReference":"/swagger/doc.json","documentation":"https://docs.baseten.co/sandboxes/overview","description":"This sandbox provides a full-featured environment for running code securely. Visit the documentation to learn how to manage processes, access the filesystem, and more."}

Run the following command to download the OpenAPI spec for the API in that sandbox, including its file and process operations:
curl --url "${SANDBOX_URL%/}/swagger/doc.json" \ --header "Authorization: Bearer $SANDBOX_TOKEN"

Requests without a valid sandbox access token return HTTP 401. For more information, see the Sandbox runtime API reference.

Open a terminal

The CLI opens an interactive shell in the sandbox. The SDKs don’t open terminals; use them to run commands instead. To open an interactive terminal in the sandbox: Run the following command:

baseten sandbox connect --name "$SANDBOX_NAME"

Press Ctrl+D to disconnect.

Connect an MCP client

Each sandbox serves an MCP server at its URL followed by /mcp. An MCP client connected to it gets tools for running commands and for reading, writing, and editing files. This server is separate from the Baseten MCP, which manages resources across your workspace. To connect an MCP client to the sandbox: Configure your MCP client with the following endpoint and authorization header, replacing <SANDBOX_URL> with the sandbox’s URL and <SANDBOX_TOKEN> with a sandbox access token:

<SANDBOX_URL>/mcp
Authorization: Bearer <SANDBOX_TOKEN>

Applications that need tighter control than the MCP server’s tools can define their own tool functions that call an SDK.

Run a command

Run a command in the sandbox and wait for it to exit. The result includes the command’s standard output, standard error, and exit code. To check the sandbox’s Python version:

TypeScript
Python
Go
API
CLI

Run the following code:

import { SandboxClient } from "@basetenlabs/sandbox";

const client = new SandboxClient({ apiKey: process.env.BASETEN_API_KEY! });
const sandbox = await client.get({ name: "hello-world" });
const result = await sandbox.process.exec({
  command: "python3 --version",
  waitForCompletion: true,
});
console.log(result.stdout, result.exitCode);

Run the following code:

import os

from baseten.sandbox import SandboxClient

with SandboxClient(api_key=os.environ["BASETEN_API_KEY"]) as client:
    sandbox = client.get(name="hello-world")
    result = sandbox.process.exec(command="python3 --version", wait_for_completion=True)
    print(result.stdout, result.exit_code)

Run the following code:

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/basetenlabs/baseten-go/sandbox"
)

func main() {
    ctx := context.Background()
    client, err := sandbox.NewClient(sandbox.ClientOptions{
        APIKey: os.Getenv("BASETEN_API_KEY"),
    })
    if err != nil {
        log.Fatal(err)
    }
    sb, err := client.Get(ctx, sandbox.GetOptions{Name: "hello-world"})
    if err != nil {
        log.Fatal(err)
    }
    process, err := sb.Process().Exec(ctx, sandbox.ProcessExecOptions{
        Command:           "python3 --version",
        WaitForCompletion: true,
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(process.Stdout, process.ExitCode)
}

Run the following command:

curl --request POST \
  --url "${SANDBOX_URL%/}/process" \
  --header "Authorization: Bearer $SANDBOX_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"command": "python3 --version", "waitForCompletion": true}'

{"pid":"9","name":"proc-eq76750y","command":"python3 --version","status":"completed","startedAt":"Thu, 05 Nov 2026 18:49:12 GMT","completedAt":"Thu, 05 Nov 2026 18:49:12 GMT","exitCode":0,"workingDir":"/workspace","logs":"Python 3.12.15\n","stdout":"Python 3.12.15\n","stderr":"","restartOnFailure":false,"maxRestarts":0,"restartCount":0,"keepAlive":false,"stdin":false}

The response is the process record, with the command’s output in stdout and its exit code in exitCode. The request returns HTTP 200 even when the command exits with a nonzero code, so check exitCode.

Run the following command:

baseten sandbox exec --name "$SANDBOX_NAME" -- python3 --version

Python 3.12.15

The command’s output streams to your terminal, and its exit code becomes the CLI’s exit code.

DEPLOYED means the sandbox is ready, not that a task succeeded. Confirm a task by its command’s exit code and output. To add environment variables to one command: These variables apply on top of the sandbox’s own environment variables. Replace worker.py with the path to your script in the sandbox.

TypeScript
Python
Go
API
CLI

Update the previous example as follows:

const result = await sandbox.process.exec({
  command: "python3 worker.py",
  env: { LOG_LEVEL: "debug" },
  waitForCompletion: true,
});

Update the previous example as follows:

result = sandbox.process.exec(
    command="python3 worker.py",
    env={"LOG_LEVEL": "debug"},
    wait_for_completion=True,
)

Update the previous example as follows:

process, err := sb.Process().Exec(ctx, sandbox.ProcessExecOptions{
    Command:           "python3 worker.py",
    Env:               map[string]string{"LOG_LEVEL": "debug"},
    WaitForCompletion: true,
})

Run the following command:

curl --request POST \
  --url "${SANDBOX_URL%/}/process" \
  --header "Authorization: Bearer $SANDBOX_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"command": "python3 worker.py", "env": {"LOG_LEVEL": "debug"}, "waitForCompletion": true}'

Run the following command:

baseten sandbox exec --name "$SANDBOX_NAME" --env LOG_LEVEL=debug -- python3 worker.py

Run a background process

Start a long-running command, such as a training script or a server, and return right away. Give the process a name so you can wait for it, read its output, or stop it later. A sandbox goes on standby when it stops receiving requests, which pauses its processes. Turn on keep-alive to keep the sandbox active while the process runs. To run a background process and wait for it:

TypeScript
Python
Go
CLI

Replace worker.py with the path to your script in the sandbox, then run the following code:

import { SandboxClient } from "@basetenlabs/sandbox";

const client = new SandboxClient({ apiKey: process.env.BASETEN_API_KEY! });
const sandbox = await client.get({ name: "hello-world" });
await sandbox.process.exec({
  command: "python3 worker.py",
  name: "worker",
  keepAlive: true,
});
const finished = await sandbox.process.wait({ identifier: "worker" });
console.log(finished.status, finished.exitCode);

To list the sandbox’s processes, call sandbox.process.list(). To stop a process, call sandbox.process.stop({ identifier: "worker" }), or sandbox.process.kill({ identifier: "worker" }) to force it.

Replace worker.py with the path to your script in the sandbox, then run the following code:

import os

from baseten.sandbox import SandboxClient

with SandboxClient(api_key=os.environ["BASETEN_API_KEY"]) as client:
    sandbox = client.get(name="hello-world")
    sandbox.process.exec(command="python3 worker.py", name="worker", keep_alive=True)
    finished = sandbox.process.wait(identifier="worker")
    print(finished.status, finished.exit_code)

To list the sandbox’s processes, call sandbox.process.list(). To stop a process, call sandbox.process.stop(identifier="worker"), or sandbox.process.kill(identifier="worker") to force it.

Replace worker.py with the path to your script in the sandbox, then run the following code:

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/basetenlabs/baseten-go/sandbox"
)

func main() {
    ctx := context.Background()
    client, err := sandbox.NewClient(sandbox.ClientOptions{
        APIKey: os.Getenv("BASETEN_API_KEY"),
    })
    if err != nil {
        log.Fatal(err)
    }
    sb, err := client.Get(ctx, sandbox.GetOptions{Name: "hello-world"})
    if err != nil {
        log.Fatal(err)
    }
    if _, err := sb.Process().Exec(ctx, sandbox.ProcessExecOptions{
        Command:   "python3 worker.py",
        Name:      "worker",
        KeepAlive: true,
    }); err != nil {
        log.Fatal(err)
    }
    finished, err := sb.Process().Wait(ctx, sandbox.ProcessWaitOptions{Identifier: "worker"})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(finished.Status, finished.ExitCode)
}

To list the sandbox’s processes, call sb.Process().List. To stop a process, call sb.Process().Stop with sandbox.ProcessStopOptions{Identifier: "worker"}, or sb.Process().Kill with sandbox.ProcessKillOptions{Identifier: "worker"} to force it.

The example runs a short shell command. Replace it with your own command.

Run the following command to start the process in the background:

baseten sandbox process start --name "$SANDBOX_NAME" --process-name worker --keep-alive -- 'sleep 3; echo finished'

Run the following command to wait for the process to exit:

baseten sandbox process wait --name "$SANDBOX_NAME" --process-name worker

PID:          20
Name:         worker
Command:      sleep 3; echo finished
Status:       completed
Exit code:    0
Working dir:  /workspace
Started:      2026-11-05T18:02:28Z
Completed:    2026-11-05T18:02:31Z

The process’s exit code becomes the CLI’s exit code. Pass --timeout, such as --timeout 1h, to stop waiting after a duration. Neither a timeout nor Ctrl+C stops the process.

Run the following command to print the process’s output:

baseten sandbox process logs --name "$SANDBOX_NAME" --process-name worker

finished

To list the sandbox’s processes, run the following command:

baseten sandbox process list --name "$SANDBOX_NAME"

To stop a running process, run the following command:

baseten sandbox process stop --name "$SANDBOX_NAME" --process-name worker

To force a process to stop, use baseten sandbox process kill with the same flags.

For more information, see baseten sandbox process and the Sandbox runtime API reference.

Read and write files

Write a file into the sandbox and read it back. Files in a sandbox last until the sandbox is deleted or expires; see Local data. To write and read a file:

TypeScript
Python
Go
API
CLI

Run the following code:

import { SandboxClient } from "@basetenlabs/sandbox";

const client = new SandboxClient({ apiKey: process.env.BASETEN_API_KEY! });
const sandbox = await client.get({ name: "hello-world" });
await sandbox.fs.write({ path: "/tmp/hello.txt", content: "hello" });
console.log(await sandbox.fs.read({ path: "/tmp/hello.txt" }));

Run the following code:

import os

from baseten.sandbox import SandboxClient

with SandboxClient(api_key=os.environ["BASETEN_API_KEY"]) as client:
    sandbox = client.get(name="hello-world")
    sandbox.fs.write(path="/tmp/hello.txt", content="hello")
    print(sandbox.fs.read(path="/tmp/hello.txt"))

For operations the SDK doesn’t wrap, sandbox.raw_api is the generated client, and client.sandbox_from_url(url=...) builds a sandbox from a URL you already have.

Run the following code:

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/basetenlabs/baseten-go/sandbox"
)

func main() {
    ctx := context.Background()
    client, err := sandbox.NewClient(sandbox.ClientOptions{
        APIKey: os.Getenv("BASETEN_API_KEY"),
    })
    if err != nil {
        log.Fatal(err)
    }
    sb, err := client.Get(ctx, sandbox.GetOptions{Name: "hello-world"})
    if err != nil {
        log.Fatal(err)
    }
    if err := sb.FS().Write(ctx, sandbox.FileSystemWriteOptions{
        Path:    "/tmp/hello.txt",
        Content: "hello",
    }); err != nil {
        log.Fatal(err)
    }
    content, err := sb.FS().Read(ctx, sandbox.FileSystemReadOptions{Path: "/tmp/hello.txt"})
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(content)
}

Run the following command to write the file:

curl --request PUT \
  --url "${SANDBOX_URL%/}/filesystem/tmp/hello.txt" \
  --header "Authorization: Bearer $SANDBOX_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"content": "hello"}'

{"path":"tmp/hello.txt","message":"File created/updated successfully"}

Run the following command to read it back:

curl --url "${SANDBOX_URL%/}/filesystem/tmp/hello.txt" \
  --header "Authorization: Bearer $SANDBOX_TOKEN"

{"path":"tmp/hello.txt","name":"hello.txt","permissions":"644","size":5,"lastModified":"2026-11-05T18:49:12.167688818Z","owner":"root","group":"root","content":"hello"}

The file’s text is in the content field.

The CLI doesn’t have file commands. Run the following command to read a file with cat:

baseten sandbox exec --name "$SANDBOX_NAME" -- cat /tmp/hello.txt

The SDKs also list, find, search, copy, and remove files. For every file operation, see the Sandbox runtime API reference.

Call an HTTP service in a sandbox

Start an HTTP service in the sandbox, then send requests to it through the sandbox runtime API’s /port/<PORT>/ route with a sandbox access token. Use this route for your own code. To open an application in a browser or share it, create a preview instead. Serve your application on a port other than 8080, where the sandbox API server listens, and 80, which the sandbox reserves for system services. The examples use port 8000. The service must be listening before you send the request. To call an HTTP service in the sandbox:

TypeScript
Python
Go
API
CLI

Run the following code to start the server, wait until it listens on port 8000, send a request, and stop the server:

import { SandboxClient } from "@basetenlabs/sandbox";

const client = new SandboxClient({ apiKey: process.env.BASETEN_API_KEY! });
const sandbox = await client.get({ name: "hello-world" });
await sandbox.process.exec({
  command: "python3 -m http.server 8000",
  name: "web",
  waitForPorts: [8000],
});
try {
  const response = await fetch(`${sandbox.url.replace(/\/$/, "")}/port/8000/`, {
    headers: { Authorization: `Bearer ${process.env.SANDBOX_TOKEN}` },
  });
  console.log(await response.text());
} finally {
  await sandbox.process.stop({ identifier: "web" });
}

<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Directory listing for /</title>
...

Run the following code to start the server, wait until it listens on port 8000, send a request, and stop the server:

import os
from urllib.request import Request, urlopen

from baseten.sandbox import SandboxClient

with SandboxClient(api_key=os.environ["BASETEN_API_KEY"]) as client:
    sandbox = client.get(name="hello-world")
    sandbox.process.exec(
        command="python3 -m http.server 8000",
        name="web",
        wait_for_ports=[8000],
    )
    try:
        request = Request(
            f"{sandbox.url.rstrip('/')}/port/8000/",
            headers={"Authorization": f"Bearer {os.environ['SANDBOX_TOKEN']}"},
        )
        with urlopen(request) as response:
            print(response.read().decode())
    finally:
        sandbox.process.stop(identifier="web")

<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Directory listing for /</title>
...

Run the following code to start the server, wait until it listens on port 8000, send a request, and stop the server:

package main

import (
    "context"
    "io"
    "log"
    "net/http"
    "os"
    "strings"

    "github.com/basetenlabs/baseten-go/sandbox"
)

func main() {
    ctx := context.Background()
    client, err := sandbox.NewClient(sandbox.ClientOptions{
        APIKey: os.Getenv("BASETEN_API_KEY"),
    })
    if err != nil {
        log.Fatal(err)
    }
    sb, err := client.Get(ctx, sandbox.GetOptions{Name: "hello-world"})
    if err != nil {
        log.Fatal(err)
    }
    _, err = sb.Process().Exec(ctx, sandbox.ProcessExecOptions{
        Command:      "python3 -m http.server 8000",
        Name:         "web",
        WaitForPorts: []int{8000},
    })
    if err != nil {
        log.Fatal(err)
    }
    defer sb.Process().Stop(ctx, sandbox.ProcessStopOptions{Identifier: "web"})

    request, err := http.NewRequestWithContext(ctx, http.MethodGet, strings.TrimRight(sb.URL(), "/")+"/port/8000/", nil)
    if err != nil {
        log.Print(err)
        return
    }
    request.Header.Set("Authorization", "Bearer "+os.Getenv("SANDBOX_TOKEN"))
    response, err := http.DefaultClient.Do(request)
    if err != nil {
        log.Print(err)
        return
    }
    defer response.Body.Close()
    if _, err := io.Copy(os.Stdout, response.Body); err != nil {
        log.Print(err)
    }
}

<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Directory listing for /</title>
...

Run the following command to start the server and wait until it listens on port 8000:

curl --request POST \
  --url "${SANDBOX_URL%/}/process" \
  --header "Authorization: Bearer $SANDBOX_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"command": "python3 -m http.server 8000", "name": "web", "waitForPorts": [8000]}'

Run the following command to request the server’s directory listing:

curl --url "${SANDBOX_URL%/}/port/8000/" \
  --header "Authorization: Bearer $SANDBOX_TOKEN"

<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Directory listing for /</title>
...

When you’re finished, run the following command to stop the server:

curl --request DELETE \
  --url "${SANDBOX_URL%/}/process/web" \
  --header "Authorization: Bearer $SANDBOX_TOKEN"

Run the following command to start the server and wait until it listens on port 8000:

baseten sandbox process start --name "$SANDBOX_NAME" \
  --process-name web --wait-for-port 8000 -- python3 -m http.server 8000

Run the following command to request the server’s directory listing:

curl --url "${SANDBOX_URL%/}/port/8000/" \
  --header "Authorization: Bearer $SANDBOX_TOKEN"

<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Directory listing for /</title>
...

When you’re finished, run the following command to stop the server:

baseten sandbox process stop --name "$SANDBOX_NAME" --process-name web

A successful request returns HTTP 200 with Python’s directory listing. Requests without the sandbox access token return HTTP 401.

Get started

Model APIs

Baseten Grid

Inference

Frontier Gateway

Training

Sandboxes

Development

Deployment

Engines

Model Labs

Organization

Hosting options

Observability

Troubleshooting

Run commands and work with files

Connect to a sandbox

Get the sandbox URL

Call the sandbox runtime API over HTTP

Open a terminal

Connect an MCP client

Run a command

Run a background process

Read and write files

Call an HTTP service in a sandbox

Next steps

Preview a sandbox application

Inspect sandbox logs

​Connect to a sandbox

​Get the sandbox URL

​Call the sandbox runtime API over HTTP

​Open a terminal

​Connect an MCP client

​Run a command

​Run a background process

​Read and write files

​Call an HTTP service in a sandbox

​Next steps

Preview a sandbox application

Inspect sandbox logs

Connect to a sandbox

Get the sandbox URL

Call the sandbox runtime API over HTTP

Open a terminal

Connect an MCP client

Run a command

Run a background process

Read and write files

Call an HTTP service in a sandbox

Next steps