Set Up sandboxed.sh and Remote Access with Localtonet

What sandboxed.sh does and how the pieces fit together

sandboxed.sh is a self-hosted mission-execution backend rather than an AI model. The selected runtime performs the agent reasoning and tool use, while sandboxed.sh manages the infrastructure around that runtime. It creates and monitors missions, prepares workspaces, synchronizes configuration, starts the selected harness, and turns runtime output into a unified event stream that its user interfaces can display.

This distinction matters when planning a deployment. Installing sandboxed.sh does not by itself provide model access or authenticate every supported runtime. A usable system also needs at least one configured agent backend, the credentials or local inference access required by that backend, and a workspace in which the mission can operate. The exact authentication method is provider-specific. For example, the project documentation describes API-key or provider-login approaches across its supported runtimes, but those secrets should never be embedded in a public tunnel URL, committed to a repository, or copied into this guide.

Projects, controllers, conversations, and missions

The project architecture separates durable planning from individual execution. A project represents ongoing work such as an audit, benchmark, implementation, or research effort. A controller is the coordinating process that wakes on a schedule, reads the relevant conversation and project state, and decides whether to dispatch work. The control conversation is the durable discussion associated with that project.

A mission is narrower. It is one unit of autonomous execution performed by an agent in an isolated workspace. Missions are appropriate for work that needs a real filesystem, repository operations, builds, tests, or another substantial execution environment. The coordinator decides and organizes; the mission builds or executes.

Prerequisites for a Docker deployment

The project identifies Docker as its recommended installation path and includes a Docker Compose configuration in the repository. A native installation path is also documented for Ubuntu 24.04 LTS, but this guide follows Docker because it is the installation method identified for the normal deployment workflow.

Before changing the host, decide where the service and mission workloads will run. AI coding missions can use substantial CPU, memory, and storage, especially when they install dependencies, compile software, run test suites, or execute several tools in parallel. Capacity requirements depend on the repositories, runtimes, and concurrency settings you choose. The supplied project evidence does not establish one universal minimum CPU, memory, or disk specification, so we should not invent one.

Host preparation checklist

• Choose a host under your administrative control.
• Install Docker and Docker Compose using the supported method for that host operating system.
• Confirm that Docker can start containers and that Compose is available.
• Reserve adequate storage for mission workspaces and container data.
• Decide which supported agent runtime will be configured first.
• Prepare that runtime's credentials without placing secrets in source control.
• Confirm that port 3000 is not already occupied if the documented Compose deployment binds the dashboard there.
• Keep the service local during initial setup and testing.

Install sandboxed.sh with its Docker Compose deployment

The official repository contains the application source, a top-level docker-compose.yml, a Dockerfile, an environment example, dashboard code, backend code, and installation documentation. The intended Docker workflow is to obtain the repository, review the current configuration, supply the required local settings, and launch the repository's Compose deployment.

Exact installation commands and required environment values can change as the project evolves. The supplied evidence establishes the recommended Docker and Docker Compose route, the repository configuration, and the local endpoint, but it does not provide the complete current Docker command sequence or a verified list of mandatory environment variables. We therefore do not reproduce guessed commands or placeholder secrets. Before executing the deployment, compare the checked-out repository's current README.md, INSTALL.md, environment example, and Compose file.

The authoritative project repository is available at the sandboxed.sh GitHub repository. Its documentation site also provides the current setup overview at sandboxed.sh.

Why this guide does not provide speculative environment variables

Copy-and-paste installation articles become dangerous when they freeze rapidly changing defaults. An outdated variable can silently disable a control, point a service at the wrong dependency, or encourage readers to paste secrets into public places. For this project, the checked-out environment example and Compose file are the definitive descriptions of what that version expects.

This limitation does not affect the later Localtonet setup. The integration needs one verified network fact: the working local web service is reachable at http://localhost:3000 from the device running the Localtonet client. If Docker publishes the service only on a different interface or if the Localtonet client runs on another device, the local target must be adjusted to an address that the client device can actually reach.

Verify the dashboard locally before creating a tunnel

Local verification separates application problems from tunnel problems. Start by opening http://localhost:3000 in a browser on the sandboxed.sh host. If the host has no graphical browser, use an HTTP request from its terminal and inspect both the response and the application logs.

curl -I http://localhost:3000

A successful HTTP response confirms that a process is listening and responding, but it does not prove that every mission feature is configured. Continue by loading the full dashboard, checking that its static assets render, and confirming that the frontend can communicate with the backend. A partial page, repeated API errors, or an interface that never leaves a loading state indicates an application configuration issue that should be fixed locally.

Test from the Localtonet client device

If the Localtonet client will run on the same machine, localhost:3000 is the natural target. If it will run on a different device, test the sandboxed.sh address from that device before creating the tunnel. In that arrangement, localhost would refer to the client device itself, not the Docker host.

The target must be an IP address and port reachable from the selected Localtonet client. Do not broaden Docker's host binding or open a LAN firewall merely by habit. Use the narrowest arrangement that supports the intended architecture, and confirm that existing network policy permits the connection.

Create and verify your first sandboxed.sh mission

The documented execution flow begins when a user creates a mission with a workspace and an agent backend. sandboxed.sh then prepares a per-mission workspace directory, synchronizes applicable Library content, writes runtime-specific configuration, launches the selected harness in the correct execution context, and translates its output into events for the dashboard.

Dashboard labels may evolve between releases, so this guide describes the stable concepts rather than inventing a fixed button sequence. In the version you deploy, locate the mission-creation interface and identify the controls corresponding to the workspace, agent or backend, and mission objective.

What sandboxed.sh prepares for a mission

Runtime-specific workspace files are generated according to the selected backend. The project documentation describes OpenCode configuration at the workspace root and under .opencode, Claude Code settings and skills under .claude plus a workspace CLAUDE.md, and Codex configuration under .codex. Gemini and Grok use their native CLI backends with provider-specific authentication.

These generated files are operational details, not templates that should be manually copied between unrelated deployments. Let the application prepare the correct files from the Library, backend settings, and workspace settings. If a mission behaves differently from another workspace, compare those three configuration sources before changing generated output by hand.

Host workspaces and container workspaces

In a host workspace, the harness process executes directly on the host with the mission directory as its working directory. In a container workspace, the process runs through the project's container-aware execution layer. Built-in shell and file operations therefore occur in the selected workspace context.

Do not assume that every host facility automatically appears in a container workspace. The project specifically notes that host desktop streaming and X11 access are not available to container harnesses by default because the host X11 socket is not automatically bind-mounted for that execution. If a mission requires desktop automation, verify the documented workspace and display configuration rather than assuming a normal coding workspace can control the host desktop.

Routine operation, updates, and resource management

A self-hosted agent backend requires more than a successful first launch. Treat the Compose configuration, local settings, persistent data, runtime credentials, Library repository, and workspace storage as separate operational concerns. Back up what is durable, know what can be regenerated, and test restoration before relying on long-running missions.

Monitor the API path as well as mission workloads

Mission work is bursty. Builds, tests, proof workloads, package installations, and parallel tools can consume substantial CPU and memory. The project architecture includes resource-isolation concepts intended to keep mission execution from starving the API and event-streaming path. Actual behavior still depends on the deployment, host resources, and checked-out configuration.

Watch for memory pressure, sustained CPU contention, disk exhaustion, and rapidly growing workspace data. A dashboard that becomes unresponsive during a mission may indicate host resource pressure rather than a networking problem. Compare container statistics, system metrics, API logs, and mission activity before changing the tunnel.

Update deliberately

• Record the deployed revision or release.
• Read release notes and configuration changes before updating.
• Back up durable application state and Library content.
• Review changes to the environment example and Compose configuration.
• Update in a maintenance window when active missions can be stopped safely.
• Repeat the local HTTP check and a disposable test mission after the update.
• Verify remote access only after local behavior is healthy.

Stop versus remove

Stopping containers is different from deleting application state, images, workspaces, or persistent volumes. Before using any destructive Docker cleanup operation, inspect the Compose file and identify which data is persistent. The evidence supplied for this article does not define a universal backup or removal command, so we do not provide one that might delete a deployment's mission history or configuration.

Enable remote dashboard access with a Localtonet HTTP tunnel

Once http://localhost:3000 works from the device that will run our client, an HTTP tunnel is the appropriate Localtonet connection. The supplied project evidence identifies a web service at that endpoint and does not establish a separate raw TCP or UDP service that should be published for this workflow.

Our client establishes an outbound connection from the device to a Localtonet relay server. The resulting tunnel provides a public address without requiring inbound router port forwarding, firewall changes, VPN setup, or a public IP address. The tunnel remains available only while the selected device is connected and the tunnel is running.

For the current dashboard workflow and available fields, consult our Localtonet HTTP tunnel documentation. HTTP process types can include a random subdomain, a custom subdomain, or a custom domain, and all serve the configured content at a public HTTPS address. Availability can depend on current product configuration or plan, so do not assume that every addressing option is available in every account.

Secure a remotely reachable AI-agent dashboard

Publishing an orchestration dashboard expands its reachable audience. The tunnel solves connectivity, but it does not replace application authorization, provider security, repository controls, or careful mission design. A dashboard capable of starting autonomous work should be treated as an administrative interface.

Confirm application authentication before exposure

The supplied project evidence does not establish a universal built-in authentication default for every sandboxed.sh deployment or version. Before starting the public tunnel, verify the authentication behavior of the exact version you installed. If the dashboard does not enforce appropriate access control, do not expose it broadly until a suitable authentication layer or other restriction is in place.

Apply least privilege to repositories and providers

• Use repository credentials limited to the projects the agent actually needs.
• Avoid broad organization-level write access for an initial deployment.
• Separate test and production credentials.
• Limit provider keys according to the provider's available controls.
• Review project autonomy, merge authority, budgets, and parallelism before unattended execution.
• Do not mount host directories merely for convenience.
• Remove credentials that are no longer required.

Protect the device token and public URL

The Localtonet device token identifies the client that runs the tunnel and must remain private. The public URL is not a substitute for a password. Treat an unlisted address as discoverable, and avoid sending it through public issue trackers, screenshots, recordings, or source files.

Stop access when the workflow ends

For temporary monitoring, start the tunnel only when needed and stop it afterward. Deleting an unused tunnel removes its configuration, while stopping it preserves the configuration for later use. Choose the lifecycle action that matches your operational policy.

Troubleshoot installation, missions, and remote access

The local dashboard does not open

Begin with the container state and logs. If a container exits, investigate its first meaningful error instead of repeatedly restarting it. Common categories include missing configuration, inaccessible storage, unavailable dependencies, an occupied host port, or a failed build. Confirm that the checked-out configuration actually publishes the service on port 3000.

If the containers appear healthy, run the local HTTP request again. A connection refusal means no process is reachable at that address. A timeout may indicate binding or network filtering. An HTTP error response proves that the network path works and shifts attention to the application.

The dashboard opens, but no backend works

Separate dashboard health from runtime health. Check whether the selected runtime is installed or otherwise reachable in the execution environment, whether its executable path is correct, and whether its provider authentication is valid. Provider-specific credentials may need to be available inside a mission container rather than only on the host.

Also confirm that the workspace type matches the runtime. A tool installed on the host is not automatically present inside a container workspace. Conversely, host execution carries different isolation and permission implications.

A mission starts but cannot access files

Verify the selected workspace and inspect which paths are available there. Generated runtime configuration should point the harness at the mission workspace. Do not fix a path problem by mounting the entire host filesystem. Add only the smallest required path, or move the test repository into the intended workspace storage.

A mission becomes slow or the dashboard stops updating

Inspect CPU, memory, disk, and container activity. Large builds or parallel tools may contend with the API service. Reduce mission concurrency or workload, correct the host capacity issue, and confirm that persistent storage is not full. If local event streaming is already stalled, changing the public tunnel will not solve the underlying problem.

The local dashboard works, but the public URL does not

• Confirm that the Localtonet client is running and connected.
• Confirm that the configured device is the device actually running the client.
• Confirm that the tunnel was started after it was created.
• Recheck the local IP address and port from the client device.
• If the client is on another machine, do not use localhost unless sandboxed.sh also runs there.
• Verify that the selected relay is currently available in the dashboard.
• Test the assigned public URL again after confirming local connectivity.

The page loads remotely, but live updates fail

First test the same mission locally. If live updates fail locally, inspect sandboxed.sh and runtime logs. If they work locally but not through the public address, collect the browser's network errors and confirm the current application origin, API-base, and streaming configuration. Do not guess unsupported proxy settings. Use the exact application's current documentation and the observed browser error to guide the correction.

Frequently asked questions