From 153340bbc7019b4ad742daabbf9988e779f1af1a Mon Sep 17 00:00:00 2001 From: anupras-mohapatra-arm Date: Tue, 3 Nov 2026 10:47:28 -0600 Subject: [PATCH 1/6] nit --- content/install-guides/opensandbox.md | 181 ++++++++++++++++++++++++++ 1 file changed, 181 insertions(+) create mode 100644 content/install-guides/opensandbox.md diff --git a/content/install-guides/opensandbox.md b/content/install-guides/opensandbox.md new file mode 100644 index 0000000000..14ff49d44b --- /dev/null +++ b/content/install-guides/opensandbox.md @@ -0,0 +1,181 @@ +--- +title: OpenSandbox + +description: Install OpenSandbox on Arm Linux and run a Python command in a Docker-backed sandbox. + +minutes_to_complete: 20 +official_docs: https://open-sandbox.ai/getting-started/ + +author: Anupras Mohapatra + +test_maintenance: false +draft: true + +weight: 1 +tool_install: true +multi_install: false +multitool_install_part: false +layout: installtoolsall +--- + +OpenSandbox provides a server and command-line interface (CLI) for creating and managing isolated environments. Its Docker runtime runs sandboxes as containers, which share the host Linux kernel. + +You'll install OpenSandbox on an `aarch64` Ubuntu 24.04 LTS host. You'll start a local server, create a sandbox, and run a Python command inside it to verify the installation. + +## Before you begin + +You need an Arm Linux system running Ubuntu 24.04 LTS with sudo access. The system also needs to have internet access to the Ubuntu package repositories, Python package index, and Docker Hub. Allow free disk space for Docker images and container data. You don't need kernel-based virtual machine (KVM) for the Docker runtime. + +Check the host architecture and operating system: + +```bash +uname -m +cat /etc/os-release +``` + +Confirm that the architecture is `aarch64` and that the operating system is Ubuntu 24.04 LTS. + +You also need Docker installed on your system. For installation steps, see the [Docker Engine install guide](/install-guides/docker/docker-engine/). + +Confirm that Docker works without `sudo`: + +```bash +docker version +docker info --format '{{.Architecture}}' +``` + +The server version should be at least `20.10`, and the architecture should be `aarch64`. If Docker reports a socket permission error, log out and log back in before continuing. + +### Install uv + +Install `uv` using the [official installer](https://docs.astral.sh/uv/getting-started/installation/): + +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +Make the installed command available in your current shell, then check its version: + +```bash +export PATH="$HOME/.local/bin:$PATH" +uv --version +``` + +Add the same `export PATH` line to `~/.bashrc` if `~/.local/bin` isn't already on your PATH in new shells. + +## Install and configure OpenSandbox + +Install the OpenSandbox server and CLI as user-level tools: + +```bash +uv tool install opensandbox-server +uv tool install opensandbox-cli +``` + +Confirm that both commands are available: + +```bash +opensandbox-server --help +osb --version +``` + +Generate a server configuration for the Docker runtime: + +```bash +opensandbox-server init-config ~/.sandbox.toml --example docker +``` + +In `~/.sandbox.toml`, set `host` under `[server]` to `127.0.0.1`: + +```toml +[server] +host = "127.0.0.1" +``` + +Keep the other values from the generated configuration. Binding the server to localhost keeps its API reachable from the same host without exposing port 8080. + +The example configuration has no API key. Use this configuration only for testing the installation. If the server asks you to acknowledge the unauthenticated configuration, enter `YES`. + +Start the server in this terminal and leave it running: + +```bash +opensandbox-server +``` + +In a second terminal on the same host, check the server health endpoint: + +```bash +curl http://127.0.0.1:8080/health +``` + +The expected output is: + +```output +{"status":"healthy"} +``` + +Configure the CLI to use the local server and proxy sandbox requests through it: + +```bash +osb config init +osb config set connection.domain localhost:8080 +osb config set connection.protocol http +osb config set connection.use_server_proxy true +``` + +## Verify the installation + +Create a sandbox from the Python image with a 30-minute timeout: + +```bash +osb sandbox create --image python:3.12 --timeout 30m -o json +``` + +The first run downloads the Python image and the OpenSandbox execution helper image. The command returns JSON containing the new sandbox ID. + +Copy that ID into a shell variable in the second terminal: + +```bash +sandbox_id="" +``` + +Replace `` with the ID returned by the `create` command. + +Check that the sandbox is healthy: + +```bash +osb sandbox health "$sandbox_id" -o json +``` + +Run commands inside the sandbox: + +```bash +osb command run "$sandbox_id" -o raw -- sh -c 'uname -m' +osb command run "$sandbox_id" -o raw -- sh -c 'python -c "print(6 * 7)"' +``` + +The expected output is: + +```output +aarch64 +42 +``` + +The `aarch64` result confirms that the container runs on Arm. The Python result confirms that command execution works through the OpenSandbox CLI. + +## Delete the test sandbox + +Delete the sandbox, then list sandboxes to confirm deletion: + +```bash +osb sandbox kill "$sandbox_id" -o json +osb sandbox list -o json +``` + +The `kill` command can return `deletion_requested` while removal completes. Repeat the list command if the sandbox is still present. The server configuration, CLI settings, and downloaded images remain available for future use. + +## Next steps + +You can now create and manage Docker-backed sandboxes on Arm Linux. + +For additional commands, see the [OpenSandbox CLI documentation](https://open-sandbox.ai/cli/). For server authentication and deployment settings, see the [OpenSandbox configuration documentation](https://open-sandbox.ai/getting-started/configuration). From 4323058312ccc7d23a36b1f4bdb55f38a5017d07 Mon Sep 17 00:00:00 2001 From: anupras-mohapatra-arm Date: Tue, 3 Nov 2026 10:48:04 -0600 Subject: [PATCH 2/6] initial draft of opensandbox install guide --- content/install-guides/opensandbox.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/install-guides/opensandbox.md b/content/install-guides/opensandbox.md index 14ff49d44b..b1b34d5e5f 100644 --- a/content/install-guides/opensandbox.md +++ b/content/install-guides/opensandbox.md @@ -3,7 +3,7 @@ title: OpenSandbox description: Install OpenSandbox on Arm Linux and run a Python command in a Docker-backed sandbox. -minutes_to_complete: 20 +minutes_to_complete: 15 official_docs: https://open-sandbox.ai/getting-started/ author: Anupras Mohapatra From c924f525020540bfe4b77728230a50b533ef408c Mon Sep 17 00:00:00 2001 From: anupras-mohapatra-arm Date: Tue, 3 Nov 2026 10:51:52 -0600 Subject: [PATCH 3/6] nit --- content/install-guides/opensandbox.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/install-guides/opensandbox.md b/content/install-guides/opensandbox.md index b1b34d5e5f..e5a37f7aa0 100644 --- a/content/install-guides/opensandbox.md +++ b/content/install-guides/opensandbox.md @@ -3,7 +3,7 @@ title: OpenSandbox description: Install OpenSandbox on Arm Linux and run a Python command in a Docker-backed sandbox. -minutes_to_complete: 15 +minutes_to_complete: 20 official_docs: https://open-sandbox.ai/getting-started/ author: Anupras Mohapatra @@ -18,9 +18,9 @@ multitool_install_part: false layout: installtoolsall --- -OpenSandbox provides a server and command-line interface (CLI) for creating and managing isolated environments. Its Docker runtime runs sandboxes as containers, which share the host Linux kernel. +OpenSandbox provides a server and a command-line interface (CLI) for creating and managing isolated environments. Its Docker runtime runs sandboxes as containers that share the host Linux kernel. -You'll install OpenSandbox on an `aarch64` Ubuntu 24.04 LTS host. You'll start a local server, create a sandbox, and run a Python command inside it to verify the installation. +You'll install OpenSandbox on an `aarch64` host with Ubuntu 24.04 LTS or later. You'll start a local server, create a sandbox, and run a Python command inside it to verify the installation. ## Before you begin @@ -33,7 +33,7 @@ uname -m cat /etc/os-release ``` -Confirm that the architecture is `aarch64` and that the operating system is Ubuntu 24.04 LTS. +Confirm that the architecture is `aarch64` and that the operating system is Ubuntu 24.04 LTS or later. You also need Docker installed on your system. For installation steps, see the [Docker Engine install guide](/install-guides/docker/docker-engine/). From 6f549e08c66e7bd3ca802cded616684320c0cccd Mon Sep 17 00:00:00 2001 From: anupras-mohapatra-arm Date: Tue, 3 Nov 2026 11:07:45 -0600 Subject: [PATCH 4/6] adding JSON outputs --- content/install-guides/opensandbox.md | 28 +++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/content/install-guides/opensandbox.md b/content/install-guides/opensandbox.md index e5a37f7aa0..c2c2179216 100644 --- a/content/install-guides/opensandbox.md +++ b/content/install-guides/opensandbox.md @@ -133,13 +133,24 @@ osb sandbox create --image python:3.12 --timeout 30m -o json The first run downloads the Python image and the OpenSandbox execution helper image. The command returns JSON containing the new sandbox ID. -Copy that ID into a shell variable in the second terminal: +The output is similar to: + +```json +{ + "id": "5e4b52ca-9947-4f3a-a1a7-6254239cd431", + "status": "created", + "timeout": "0:30:00", + "image": "python:3.12" +} +``` + +Copy the `id` into a shell variable in the second terminal: ```bash sandbox_id="" ``` -Replace `` with the ID returned by the `create` command. +Replace `` with the `id` returned by your `create` command. Check that the sandbox is healthy: @@ -147,6 +158,15 @@ Check that the sandbox is healthy: osb sandbox health "$sandbox_id" -o json ``` +The output is similar to: + +```json +{ + "sandbox_id": "5e4b52ca-9947-4f3a-a1a7-6254239cd431", + "healthy": true +} +``` + Run commands inside the sandbox: ```bash @@ -161,7 +181,7 @@ aarch64 42 ``` -The `aarch64` result confirms that the container runs on Arm. The Python result confirms that command execution works through the OpenSandbox CLI. +The `aarch64` result confirms that the sandbox container runs on Arm. The Python result confirms that command execution works through the OpenSandbox CLI. ## Delete the test sandbox @@ -176,6 +196,6 @@ The `kill` command can return `deletion_requested` while removal completes. Repe ## Next steps -You can now create and manage Docker-backed sandboxes on Arm Linux. +You can now use OpenSandbox to create and manage Docker-backed sandboxes on Arm Linux. For additional commands, see the [OpenSandbox CLI documentation](https://open-sandbox.ai/cli/). For server authentication and deployment settings, see the [OpenSandbox configuration documentation](https://open-sandbox.ai/getting-started/configuration). From 356eaab3426389d236779b3c9dcc5af9d1ab5a15 Mon Sep 17 00:00:00 2001 From: anupras-mohapatra-arm Date: Tue, 3 Nov 2026 11:15:29 -0600 Subject: [PATCH 5/6] adding JSON output --- content/install-guides/opensandbox.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/content/install-guides/opensandbox.md b/content/install-guides/opensandbox.md index c2c2179216..3907b521eb 100644 --- a/content/install-guides/opensandbox.md +++ b/content/install-guides/opensandbox.md @@ -192,6 +192,27 @@ osb sandbox kill "$sandbox_id" -o json osb sandbox list -o json ``` +The output is similar to: + +```json +[ + { + "sandbox_id": "5e4b52ca-9947-4f3a-a1a7-6254239cd431", + "status": "deletion_requested" + } +] +{ + "items": [], + "pagination": { + "page": 1, + "page_size": 20, + "total_items": 0, + "total_pages": 0, + "has_next_page": false + } +} +``` + The `kill` command can return `deletion_requested` while removal completes. Repeat the list command if the sandbox is still present. The server configuration, CLI settings, and downloaded images remain available for future use. ## Next steps From bfc8b357e060eb284d871c0ac5f422400bf9d5f2 Mon Sep 17 00:00:00 2001 From: anupras-mohapatra-arm Date: Tue, 3 Nov 2026 11:18:17 -0600 Subject: [PATCH 6/6] adding sentence for shutting the running server --- content/install-guides/opensandbox.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/install-guides/opensandbox.md b/content/install-guides/opensandbox.md index 3907b521eb..63dbdbd1ee 100644 --- a/content/install-guides/opensandbox.md +++ b/content/install-guides/opensandbox.md @@ -215,6 +215,8 @@ The output is similar to: The `kill` command can return `deletion_requested` while removal completes. Repeat the list command if the sandbox is still present. The server configuration, CLI settings, and downloaded images remain available for future use. +To shut the running server, press **Ctrl + C**. + ## Next steps You can now use OpenSandbox to create and manage Docker-backed sandboxes on Arm Linux.